svg-injector: Instructions file for Codex

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").
• Commit subjects and PR titles are one plain capitalised sentence, git log --oneline style, with no conventional-commit prefix (feat:, fix:, chore(deps):). Nothing reads a prefix: the version bump comes from the PR label.
• Add a commit 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. Hard-wrap it at 72 columns.
• PR titles are copied verbatim into the generated release notes, so write them as the changelog line you want readers to see.
• Do not hard-wrap markdown files, PR descriptions or issue descriptions.
• 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.

Architecture

SVGInjector runs one pipeline per element: split the sprite fragment off the URL, load, transform, swap, settle. CONTEXT.md names the stages. inject-element.ts is that pipeline, and the header comments of the modules under it say what each owns.

Every path out of injectElement, errors included, settles exactly once. Add one that doesn't and afterAll silently never fires. The transform and beforeEach run consumer code, and are the two paths where a throw has to settle before it escapes.

XHR is a decision, not leftover legacy. It carries the file:// allowances make-ajax-request.ts documents, and its content-type check runs at readyState 2 so a rejected response aborts before its body arrives. fetch does neither. Don't migrate it without new evidence. Safari is the engine that decides anything file:// and the only one those allowances are load-bearing in; measured on Chrome 151, Safari 26.5 and Firefox 146.