# Contributing to standarnav

standarnav (npm package `@standarx/nav`) is published — `0.1.0` since
2026-09-22 — and v0 is in progress: the public API is not frozen. This
document explains how to set up the project, what is expected of a pull
request, and how to report a bug. Read it before opening a pull request.

## Prerequisites

- [bun](https://bun.sh). The repository pins the version in `.bun-version`
  (`1.4.0`); CI installs that exact version through
  `oven-sh/setup-bun` (`.github/workflows/ci.yml:22-24`). Use that version or
  a newer one. Never use `npm` or `npx` in this repository — every command
  below is a `bun` command. The release workflow carries the one documented
  exception: its publish step calls the npm CLI (`npm publish --provenance` in
  `.github/workflows/release.yml`), because publication has to happen from CI
  *with* a provenance attestation and the `bun` client emits none. That
  exception is recorded, with the issue it turns on and the dates, in
  [ADR-0012](docs/adr/0012-versioning-and-release.md) — nothing else here may
  reach for npm.
- A Playwright browser for the browser test project. The default engine is
  Chromium (`vitest.config.ts`):

  ```sh
  bun x playwright install chromium
  ```

  Install `firefox` and `webkit` the same way when you need to reproduce the
  CI matrix locally.
- Node is not required to run the scripts below; `bun` runs them directly.

## Setup

```sh
bun install
```

## Scripts

The scripts used for contribution checks, read from the `scripts` field of
`package.json` on 2026-09-22. Run them with `bun run <script>`.

| Script | Command | Purpose |
|---|---|---|
| `dev` | `vite playground --open` | Serve the fixture page in `playground/`. It imports the engine from `src/` directly, so Vite compiles it and a change is on screen on the next reload with no build step between. |
| `build` | `tsdown` | Build the package (ESM, unbundled, with `.d.ts`). It rewrites the `exports` map of `package.json`, so a build has to leave the tree byte-identical — see the drift gate below. |
| `typecheck` | `tsc --noEmit` | Type-check without emitting output. |
| `lint` | `biome check .` | Lint and format-check with Biome. |
| `lint:fix` | `biome check --write .` | Lint and fix what Biome can fix automatically. |
| `format` | `biome format --write .` | Format the codebase with Biome. |
| `test` | `vitest run` | Run every test project (unit and browser). |
| `test:unit` | `vitest run --project unit` | Run the Node-based unit tests only. |
| `test:browser` | `vitest run --project browser` | Run the browser tests on one engine, Chromium unless `SNAV_BROWSER` says otherwise (`vitest.config.ts`). |
| `test:watch` | `vitest` | Run tests in watch mode. |
| `check:size` | `bun run scripts/size-budget.ts` | Measure the min+gzip size of every published entry of `dist/` against its cap. Needs a build first. |
| `check:package` | `bun run scripts/check-package.ts` | Refuse any runtime dependency in `package.json`, then pack the tarball and run `publint --strict` and `attw --profile esm-only` on it — the real artifact npm receives, not the source tree. |
| `check:docs` | `bun run scripts/check-citations.ts` | Resolve every `path:line` citation, bare `:NNN` anchor and link in every tracked `.md` against the tree, and refuse an absolute path or a `.local` reference (see "No documentation claim without its proof"). A required step of the CI lint job, independent of Biome. |

There is no benchmark script. Vitest 5 no longer exports `bench`, and nothing
in this repository measures throughput; a performance claim in a document needs
a measurement you took yourself, with its command and date.

Before opening a pull request, run at minimum:

```sh
bun run lint
bun run check:docs
bun run typecheck
bun run test
bun run build
bun run check:package
bun run check:size
```

All of those were run here on 2026-09-22 and pass. Between them they reproduce
five of the eleven checks CI runs (nine jobs, one of them a three-engine matrix);
the firefox and webkit runs and the React 18.3, Vue 3.3.0, Svelte 5.0.0 and Angular 20.0.0 floor jobs only exist in CI, which
reports them on the pull request. Measured on the same date: `bun run test:unit`
is 110 tests in 11 files, `bun run test:browser` is 257 passed and 1 skipped in
13 files — 367 passed and 1 skipped in total. The
one skip is a documented shadow-DOM fixture
(`src/spatial/spatial.browser.test.ts:921`, [ADR-0008](docs/adr/0008-shadow-dom.md)),
not a test someone silenced. A red CI is about your change; treat it that way.

## Conventional commits

Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <short summary>
```

Types used in this repository: `feat`, `fix`, `perf`, `docs`, `refactor`,
`test`, `chore`, `ci`. The type is also what releases: release-please bumps a
patch on `fix`, a minor on `feat`, and publishes the result, while `docs`,
`refactor`, `test`, `chore` and `ci` are hidden from the CHANGELOG and bump
nothing. So a change confined to `.md` files is `docs`, never `fix(docs)` — a
`fix` on a document publishes a release for a document. The CHANGELOG of
`0.1.0` carries five such entries under "Bug Fixes", which is the lesson
([ADR-0012](docs/adr/0012-versioning-and-release.md), amendment of
2026-09-22, third).

Scopes describe the area touched, for example `spatial`, `gamepad`, `react`,
`focus-ring`, `keymap`, `modality`, `tabbable`. Use no scope for changes that
span the whole repository (a root `chore` or `ci` change, for instance).

Examples:

```
feat(spatial): add app-mode composite crossing for gamepad
fix(gamepad): correct dead-zone renormalisation at the sector boundary
docs(react): document useIntentScopeHost cleanup order
```

### No AI co-author trailer

Never add an AI co-author trailer to a commit message — no `Co-Authored-By`
trailer generated by a tool, under any name. Authorship trailers are for
human contributors only.

## Release notes

[ADR-0012](docs/adr/0012-versioning-and-release.md) accepts semver starting
at 0.x, and the release tool is decided: **release-please**. It reads the
Conventional Commit history of `main` and keeps a release pull request open
carrying the version bump and the CHANGELOG it writes from those commits,
which is why the commit rules above are load-bearing rather than cosmetic.

The wiring exists — `release-please-config.json`, `.release-please-manifest.json`
and `.github/workflows/release.yml` — and has released: `0.1.0` reached npm on
2026-09-22 from that workflow, and the CHANGELOG at the root is what it wrote.

The release note is the squashed commit subject. A pull request that changes
anything a consumer can observe carries one sentence saying what changed for
that consumer, in English, naming the affected subpath rather than the file;
that sentence becomes the subject of the squash merge, and so the CHANGELOG
entry. A documentation-only or internal-refactor pull request says so
explicitly instead of leaving the line out, and is typed accordingly.

## Tests are required for every behaviour change

Every change to behaviour needs a test. There is no exception for "obvious"
fixes.

- A change that touches the DOM (focus movement, attribute reads or writes,
  scroll handling, the focus ring overlay) needs a browser test, and it must
  pass on the three engines of the CI matrix: Chromium, Firefox, and WebKit
  (the `browser` job, `.github/workflows/ci.yml:103-129`). Locally,
  `bun run test:browser` runs one engine at a time; select the other two with
  the environment variable the configuration reads:

  ```sh
  SNAV_BROWSER=firefox bun run test:browser
  SNAV_BROWSER=webkit bun run test:browser
  ```

  A unit test running in Node is not a substitute for a browser test when
  real DOM APIs (`focus()`, `getBoundingClientRect`, `checkVisibility`,
  `document.activeElement`) are involved. Browser tests are named
  `*.browser.test.ts` or `*.browser.test.tsx`; everything else stays in the
  `unit` project (`vitest.config.ts`).
- Pure functions (geometry scoring, keymap resolution, attribute parsing) are
  covered by unit tests under the `unit` Vitest project.
- `passWithNoTests` is deliberately **not** set (`vitest.config.ts`). An
  empty project means the globs stopped matching, which is a discovery
  breakage, and it has to be as red as a failing assertion rather than a green
  run of nothing. Do not add the flag to get past a red run.
- A change to the React, the Vue, the Svelte or the Angular adapter is held to the shared adapter suite in
  `src/adapter-parity.ts`, not to tests of its own invention: one system and
  not during the first render, LIFO scope order, a scope released when only
  its own subtree unmounts, a trap that stops the walk, a base scope reached
  through that trap, a composite inside the trapping surface reached when both
  pass `within` and silenced when neither does, a base re-registered in its
  place on a rerender, and the order scopes were opened in kept across a system
  rebuild. Each adapter
  implements `ParityAdapter` and runs the same suite: React in
  `src/react/react.browser.test.tsx`, Vue in `src/vue/vue.browser.test.ts`, Svelte in
  `src/svelte/svelte.browser.test.ts`, Angular in `src/angular/angular.browser.test.ts`. Extend
  the suite rather
  than working around it. A separate CI job reinstalls React 18.3 over the
  lockfile's 19 and typechecks and runs the browser suite against it
  (the `react-floor` job, `.github/workflows/ci.yml:75-101`): the declared peer
  range is `>=18.3.0`, and every other job installs `--frozen-lockfile`, so
  without that job the floor of the range is a promise nothing keeps. A change
  that needs a React 19 API narrows the peer range in the same pull request.
  The Vue adapter has the same guard, the `vue-floor` job
  (`.github/workflows/ci.yml:136-161`), which installs exactly `vue@3.3.0`: a change
  that needs a later Vue API raises the `>=3.3.0` peer range in the same pull request.
  The Svelte adapter has it too, the `svelte-floor` job
  (`.github/workflows/ci.yml:169-193`), which installs exactly `svelte@5.0.0` and runs the
  unit project as well, for the server render: a change that needs a later Svelte API raises
  the `>=5.0.0` peer range in the same pull request.
  The Angular adapter has it too, the `angular-floor` job
  (`.github/workflows/ci.yml:202-226`), which installs exactly 20.0.0 of `@angular/core` and of
  the four Angular packages the tests load, and runs the unit project as well: a change that
  needs a later Angular API raises the `>=20.0.0` peer range in the same pull request.
- A pull request without a test for the behaviour it changes is not merged.

## Size budgets are blocking

The build job of CI runs `bun run check:size` after the build, the drift gate
and `check:package` (`.github/workflows/ci.yml:50-58`). The script is
`scripts/size-budget.ts`. It measures fourteen lines against the built `dist/`:
the core (`index.js`), the gamepad engine, the spatial engine, the focus ring,
the debug entry, the auto-mount helper, the React, Vue, Svelte and Angular adapters, the on-screen
keyboard and one line per keyboard layout — each bundled with the sibling entries it
also imports left external, so the number is the marginal cost of adding that
subpath next to what it already sits beside. That is usually the core, but not
always: the debug line externalises `./spatial/spatial.js` and
`./spatial/geometry.js`, so it is charged against the spatial engine rather than
against the core (`scripts/size-budget.ts:108-117`), and the core line has no
externals at all (`scripts/size-budget.ts:81-86`). There is no "whole
package" line since 2026-09-23: a coverage check names any built module that no
line pays for instead ([ADR-0017](docs/adr/0017-size-budgets.md)). Every line, single-entry ones
included, goes through a synthetic module that imports each entry as a
namespace into an exported sink: a bare entry is tree-shaken against
`sideEffects: false` and measures a list of export names whose declarations
have all been dropped, and a `export * from` shim is dropped by ES semantics
the same way. Each line is minified and gzipped at Bun's default level; that
reads a little heavier than `gzip -9`, so never mix the two in one comparison.
The script also fails with a clear message when `dist/` is missing.

**Externals are named file by file. Never write a glob.** `../*` does not
cross a path separator, so it marks `../modality.js` external and silently
misses `../dom/query.js`; `./*` on a top-level entry can externalise the
line's own contents and report a re-export stub as proof. Either way the line
stops measuring and never goes red again. Derive a line's externals from the
built graph in `dist/`, not from `src/` — the two disagree, because a
types-only module emits no `.js` and a type-only import erases. A named
external that resolves to no file is a hard error rather than a silent
no-op, which is the check that keeps this honest.

Every line is capped. Measured here with `bun run build && bun run check:size`
on 2026-09-21, min+gzip against cap:

```
core            3.13 / 3.25 kB
gamepad engine  2.49 / 2.50 kB
spatial engine  3.04 / 3.25 kB
focus ring      1.51 / 1.75 kB
debug           0.49 / 0.50 kB
react adapter   1.30 / 1.50 kB
keyboard        2.82 / 3.00 kB
layout qwerty   0.45 / 0.50 kB
layout azerty   0.49 / 0.50 kB
layout alphabetic  0.36 / 0.50 kB
```

The run passes. A `null` cap is still a legal state in the script and still
fails the run printing the measurement — that is how a newly added line is
capped from a real number rather than from a guess the script then ratifies by
staying green ([ADR-0017](docs/adr/0017-size-budgets.md)) — but no line is in
that state today. If `check:size` exits non-zero, a line is over its cap or a
new line has no cap yet; either way it is about your change.

A pull request that touches a measured entry pastes the `check:size` lines
for that entry into its description, so the size change is visible in review
rather than reconstructed afterwards.

A pull request that would exceed a cap does not raise the cap in the same
change: it either reduces the size, or it links an ADR amendment (see
[ADRs](#adrs-architecture-decision-records)) that proposes and justifies the
new cap. The budget script itself is not the place to negotiate a larger
number.

## No documentation claim without its proof

Every number, benchmark result, or compatibility claim in a Markdown file
needs one of:

- a test that asserts it,
- a measurement with the exact command that produced it and the date it was
  run, or
- a source URL (a spec, a caniuse/MDN entry, a competitor's own repository).

A claim with none of these is written as "not measured yet" or "to be
verified" instead of being asserted. This applies to README, ADRs, the
specification, and the roadmap alike.

Two rules about the paths inside those claims:

- Every cited path is a path in **this** repository, at a real line you have
  opened. Line anchors go stale; re-read the one you are citing rather than
  carrying it forward from the paragraph you are editing. A claim this project
  did not re-derive gets no path at all: it is marked as inherited from the
  predecessor implementation
  ([ADR-0002](docs/adr/0002-license-and-copyright.md)) and not re-derived here,
  so a reader knows there is nothing here to check it against.
- Never write an absolute filesystem path into a committed file, and never
  reference the gitignored `.local` scratch directory from one.

`bun run scripts/check-citations.ts` checks the mechanical half of those rules
across every tracked `.md`: a cited file must exist, the line must be inside
it, and the first and last line of a range must not be blank — landing on
whitespace is what a drifted anchor looks like. It also refuses an absolute
path and a scratch-directory reference outright. What it cannot see is an
anchor that drifted onto some *other* real line, which is why the prose names
the symbol it is pointing at: a reader can then see the mismatch.

A path written in full once and then cited as `` `:NNN` `` for the lines around
it is checked the same way, against the file the prose named last — the reading
a human already gives it. So name the file again whenever the subject changes,
and never leave a bare anchor above the first path on the page: with nothing to
resolve it against, it fails the run rather than pointing somewhere plausible.

## Code and comments

- Code, identifiers, commit messages, and comments are in English.
- No comments by default. Write a comment only when it explains a non-obvious
  WHY that the code cannot express by itself — never a restatement of WHAT
  the code does.

## Markdown: English canonical, French mirror for user documentation

Every committed `.md` file is English. User-facing documentation under
`docs/` follows an additional rule: `docs/en` is canonical, and `docs/fr` is
its strict, file-by-file mirror. A documentation page without its mirror
does not merge — add the French page in the same pull request, or hold the
English page until it is ready.

Both directories exist since 2026-09-22, four pages each: `attributes.md`,
`navigation.md`, `react.md` and `focus-ring.md`. `auto.md` joined them afterwards, `vue.md` on
2026-09-23, and `svelte.md` and `angular.md` on 2026-09-24. `docs/` also holds `adr/`,
`research/` and `specification.md`, all of which are English-only by the
paragraph below. In a mirror, the prose is translated and everything that is
the contract — code blocks, attribute and property names, cited paths, table
cells holding code — is identical on both sides.

This mirror rule applies to user-facing documentation only. Governance files
(this one, the code of conduct, the security policy), ADRs, the
specification, and the roadmap stay English-only with no mirror. The policy
and its reasons are recorded in
[`docs/adr/0015-language-policy.md`](docs/adr/0015-language-policy.md).

## ADRs (Architecture Decision Records)

Decisions with lasting consequences (an API shape, a breaking rename, a size
budget, a supported-runtime tier) are recorded as an ADR under `docs/adr/`,
numbered `NNNN-title.md`. An ADR starts with a `# ADR-NNNN: Title` heading,
then `Status`, `Date` and `Deciders` lines, then the sections `## Context`,
`## Decision`, `## Consequences`, `## Alternatives considered` and
`## Evidence` (commands, URLs, dates). The full rules, the numbering, and the
index of the existing records are in
[`docs/adr/README.md`](docs/adr/README.md). Read an existing ADR before
proposing a new one — [`docs/adr/0005-real-dom-focus.md`](docs/adr/0005-real-dom-focus.md)
is a worked example — and link related ADRs by file name from the one you
add.

See also [`docs/specification.md`](docs/specification.md) for the engine
specification and [`ROADMAP.md`](ROADMAP.md) for what is planned versus what
exists today.

## Licensing of contributions

This project is MIT licensed. Contributions are accepted under
inbound=outbound: by submitting a contribution, you agree it is licensed to
the project under the same MIT license as the rest of the codebase, with no
separate agreement required.

## Pull request checklist

Before requesting review, confirm:

- [ ] Commit messages follow Conventional Commits, with an appropriate scope.
- [ ] No commit carries an AI co-author trailer.
- [ ] Every behaviour change has a test; DOM-touching changes pass on
      Chromium, Firefox and WebKit.
- [ ] `bun run lint`, `bun run typecheck`, `bun run test`, and `bun run build`
      pass locally.
- [ ] `bun run build` left the tree clean, or the rewritten `exports` map in
      `package.json` is committed with the change (`git diff --exit-code` is a
      CI gate).
- [ ] `bun run check:package` passes: no runtime dependency, and the packed
      tarball is clean under `publint --strict` and `attw`.
- [ ] The `bun run check:size` lines for every entry the change touches are
      pasted in the description, and no cap is exceeded — or the pull request
      links an ADR amendment proposing the new cap.
- [ ] The description carries the one-sentence user-facing change, or states
      that the change is documentation-only or internal.
- [ ] Every number or claim added to documentation carries its proof (test,
      measurement with command and date, or URL) or is marked "not measured
      yet" / "to be verified".
- [ ] New or changed code and comments are in English; no comment restates
      WHAT the code already says.
- [ ] Any new or changed user-facing documentation page under `docs/en` has
      its `docs/fr` mirror in the same pull request.
- [ ] A decision that deserves an ADR has one, linked from the pull request
      description.

## Reporting a bug

Open a bug with the "Bug report" issue template
(`.github/ISSUE_TEMPLATE/bug_report.yml`). It asks for the information a
report needs to be reproduced without a round trip:

1. **A minimal HTML fixture.** A single self-contained `.html` file that
   reproduces the issue with the smallest possible markup and inline styles,
   no CSS framework. The template ships a skeleton to start from.
2. **The runtime.** Browser and version, operating system or TV model, and
   the input device that produced the wrong move (keyboard, d-pad, stick,
   remote, pointer).
3. **Expected versus actual focus**, described concretely: which element
   `document.activeElement` should point to after the move, and which one it
   points to instead.

A report missing the fixture or the runtime information takes longer to
triage and may be sent back for these details before it is investigated.

A device observation with no bug attached (a television or a gamepad you
tested) goes to the "Device report" template
(`.github/ISSUE_TEMPLATE/device_report.yml`) instead: those reports are what
later compatibility claims will point at.