svg-injector AGENTS.md

AGENTS.md

Rules for coding agents that the code and config don't already state. Keep it that way: a constraint that can live in a comment next to the thing it constrains belongs there, not here.

Writing

• NZ English everywhere ("colour", "behaviour", "initialise").
• Match a document's length to what it needs. Cover the substance, then stop: no filler sections, restated summaries or boilerplate.
• Simple, direct technical language. No marketing speak.
• Commit subjects are one capitalised line, git log --oneline style. Add a body whenever the change had a reason the diff does not show: what it fixes, what it rules out, what constraint forced the shape it has. Mechanical changes need none.
• No conventional-commit prefixes (feat:, fix:, chore(deps):) in commit subjects or PR titles. Write a plain capitalised sentence. Nothing reads the prefix: the version bump comes from the PR label, and renovate is set to semanticCommits: "disabled" to match.
• PR titles are copied verbatim into the generated release notes, so write them as the changelog line you want readers to see.
• Hard-wrap commit message bodies at 72 columns; git log does not reflow them. Do not hard-wrap PR or issue descriptions: GitHub reflows markdown, and its web editor leaves wrapped source ragged once anyone edits it.
• README.md follows standard-readme. Per-feature detail belongs in examples/*/README.md, linked from there.
• README.md states current behaviour; MIGRATION.md states what changed and keeps the upgrade steps in full. Neither re-derives the other.
• Code comments record non-obvious behaviour, constraints and decisions, not what the line already says.

Architecture

SVGInjector normalises its argument, then runs one pipeline per element: split the sprite fragment off the URL, load, transform, swap.

• svg-injector.ts owns the afterEach and afterAll accounting. Every path out of injectElement, errors included, calls back exactly once. Add one that doesn't and afterAll silently never fires.
• defer.ts enforces the callback timing svg-injector.ts documents. A path already running inside an XHR event or a deferred task calls back directly, which is why load-svg-uncached.ts and the handleLoadedSvg error paths hold no defer.
• inject-element.ts is that per-element pipeline, and the only module that chooses a load path.
• parse-data-url.ts intercepts data:image/svg+xml before any request is made, so data URLs never reach the XHR layer.
• load-svg-cached.ts and load-svg-uncached.ts wrap make-ajax-request.ts. The cache key is the URL with the fragment stripped, so every symbol taken from one sprite shares a single request.
• extract-symbol.ts, renumerate-svg-iri-elements.ts and eval-svg-scripts.ts are the transform steps, applied in that order.