# ADR-0017: Size budgets: measure before capping

Status: Accepted
Date: 2026-09-18
Deciders: Wesley Cormier

## Context

This package targets televisions and set-top boxes. There, bytes are parse time
on a slow CPU over a slow link, so the size of each subpath is a product
constraint, not a vanity metric. The package is split into subpaths
(`@standarx/nav`, `/gamepad`, `/spatial`, `/focus-ring`, `/debug`, plus framework
adapters), which makes "how big is the package" ambiguous: a core-only consumer
pays nothing for the gamepad engine.

Budgets are enforced here by `scripts/size-budget.ts`, and the script hit the
ambiguity first: each line is measured with the layers it shares with the core
marked `external`, because otherwise every subpath line would be charged for the
core again and a 3 kB line would mean nothing (`scripts/size-budget.ts:5-12`).
Those externals are named file by file and never globbed, because `*` does not
cross a path separator and a glob is how a budget line stops measuring without
ever going red (`scripts/size-budget.ts:67-79`).

The measurements below are inherited from the predecessor implementation
([ADR-0002](0002-license-and-copyright.md)) and not re-derived here: min+gzip at
Bun's default gzip level, each line measured with the layers it shares marked
external.

| Line | Measured | Cap |
|---|---|---|
| input system (intents + engage) | 1.93 kB | 2.00 kB |
| gamepad engine | 2.35 kB | 3.00 kB |
| spatial engine | 2.81 kB | 3.00 kB |
| modality tracker | 0.74 kB | 1.00 kB |

Not one of those four names is a line here: this repository measures `core`,
`gamepad engine`, `spatial engine`, `focus ring`, `debug`, `auto mount`,
`react adapter`, `vue adapter`, `svelte adapter`, `angular adapter`, `keyboard` and one line per
keyboard layout (`scripts/size-budget.ts:80-186`), and `src/input-system.ts` is
charged to the core line rather than costed on its own
(`scripts/size-budget.ts:81-86`). The table is context for the shape of the
problem, not a set of ceilings.

One further figure circulates and must be labelled: the spatial engine bundled
with **nothing** external was reported at 3 303 B, above 3 kB — inherited from the
predecessor implementation ([ADR-0002](0002-license-and-copyright.md)) and not
re-derived here. It does not contradict the 2.81 kB line — it is the other
question, asked of the same module, and both questions are worth asking. A
whole-package line used to ask it of every runtime entry at once; it was removed
on 2026-09-23 because no consumer downloads every entry and the sum went red when
the package gained one rather than when anything grew — the amendment at the foot
of this record. Three
further figures of 2026-08-27 (2.48 kB gamepad, 2.89 kB spatial, 1.34 kB focus
ring) are inherited from the predecessor implementation
([ADR-0002](0002-license-and-copyright.md)) and not re-derived here; they are
historical and only ever quoted with that date attached.

The budget script lives here: `scripts/size-budget.ts`, wired as
`bun run check:size` (`package.json`) and run in CI
(`.github/workflows/ci.yml:57-58`). It declares fourteen lines
(`scripts/size-budget.ts:80-186`), every one of them capped from a measurement
taken in this repository — the dated amendments below are that record.

## Decision

1. One **marginal** line per opt-in subpath — gamepad engine, spatial engine,
   focus ring, debug — measured with its siblings external: what a consumer who
   already imports the core pays to add it. A second kind of line, one
   whole-package sum, was part of this decision until 2026-09-23; the amendment
   at the foot of this record is why it is gone and what replaced it.
2. A cap is written **only after the first measurement in this repository**. An
   inherited number is context, never a ceiling: the bundler, the target and the
   file layout all change in the move.
3. Caps are the measured value rounded **up to the next quarter kB**. That is
   headroom for noise, not for growth, and the script says so where it fails:
   write the next 0.25 kB above the measurement and record it in an amendment here
   (`scripts/size-budget.ts:393-397`).
4. A cap is raised only by amending this ADR, in its own commit. Never in the
   pull request that exceeded it. The pull request that exceeds a cap either gets
   smaller or gets an amendment first.
5. **A line without a cap fails the run.** `cap: null` means "measured, not yet
   ceilinged": the line is bundled and reported like any other and the run exits
   non-zero printing the number, so the cap can be written from it
   (`scripts/size-budget.ts:14-16`, `scripts/size-budget.ts:393-397`). A default
   would be a guess the file ratifies by being green.
6. The script is **JavaScript only**. This package ships no stylesheet, so nothing
   in the script compiles or measures CSS: it imports `node:fs` and `node:path` and
   nothing else (`scripts/size-budget.ts:18-19`), and it measures built JavaScript
   out of `dist/`.
7. Measurements are min+gzip at Bun's default gzip level. That reads a little
   heavier than `gzip -9`. One level is cited, never a mix
   (`scripts/size-budget.ts:11-12`).
8. Every size in a committed document carries its command and date
   ([CONTRIBUTING](../../CONTRIBUTING.md)) and says whether it was measured here or
   is inherited.

## Consequences

- No cap can be written before a build exists, so rule 5 keeps `check:size` red
  until the first measurement is recorded — and red earlier still, with a message
  telling the reader to run `bun run build`, while `dist/` is missing
  (`scripts/size-budget.ts:382-385`). The sequence is red, measure, cap, green, and
  the amendments below are where each cap was written from its measurement.
- Bundling every subpath alone and then all of them together is more work per run
  and a longer report. Accepted: the single-number version lets a shared module
  quietly get expensive for everyone while every individual line stays green.
- The 1.93 kB of 2.00 kB on the input system — inherited from the predecessor
  implementation ([ADR-0002](0002-license-and-copyright.md)) and not re-derived
  here — left almost no room. If the same shape reappears here, the first
  measurement gives a cap of 2.00 or 2.25 kB and the next feature on that line
  needs an amendment. That is the mechanism working, not failing.
- Rule 4 makes some pull requests two commits instead of one. That is the price
  of a cap that means anything.
- The focus ring is a special case the budget alone does not capture: it ships no
  stylesheet at all, so a small bundled size does not mean a complete feature.
  Its defaults and the six custom properties that override them are
  [ADR-0020](0020-focus-ring-defaults.md).
- Budgets constrain the engine described in [ADR-0016](0016-scoring-constants-provenance.md);
  a change to the scoring rule is both a fixture question and a size question.

## Amendment, 2026-09-19: the first measurement, and three defects it exposed

`bun run build && bun run check:size`, run 2026-09-19 on the extraction branch,
bun 1.4.0, tsdown 0.23.0, target `browser`, minified and gzipped at Bun's default
level. Caps by rule 3, the measurement rounded up to the next quarter kB.

| Line | min | min+gzip | cap | what the line leaves out |
|---|---|---|---|---|
| core | 7.64 kB | 3.08 kB | 3.25 kB | nothing — it is the baseline |
| gamepad engine | 5.37 kB | 2.48 kB | 2.50 kB | `dom/event.js`, `intent-bus.js` |
| spatial engine | 7.23 kB | 3.03 kB | 3.25 kB | `dom/event.js`, `dom/query.js`, `tabbable.js` |
| focus ring | 3.03 kB | 1.44 kB | 1.50 kB | `dom/event.js`, `dom/query.js`, `modality.js` |
| debug | 0.75 kB | 0.50 kB | 0.75 kB | `spatial/spatial.js`, `spatial/geometry.js` |
| whole package | 22.31 kB | 8.64 kB | 8.75 kB | nothing; the debug entry is not in it |

The core line carries `tabbable.js` and `dom/query.js` because the root entry
re-exports six tabbable symbols. That is a deliberate cost: it is what makes
`isFocusable` available to a consumer without pulling an engine. `dom/raf.js` and
`dom/platform.js` are charged to the spatial engine and `dom/platform.js` again to
the focus ring, because no root export reaches either — a marginal cost is what
each subpath adds, and both subpaths do add them.

Three defects in the script were found by running it for the first time, each of
which would have made a line green while measuring nothing:

1. Four lines named `../types.js` external. `src/types.ts` is types only, so
   nothing is emitted for it and the name matched no file. The existence guard
   caught it; without that guard the external would simply have been ignored.
2. Every line was bundled as a bare entry. Against a package declaring
   `sideEffects: false`, nothing keeps an entry's exports alive: the core measured
   **0.24 kB**, and its bundle was a list of export names whose declarations had
   all been dropped. Every line now goes through the namespace-into-a-sink module
   that previously only the whole-package line used.
3. Bun's `external` option does not match a relative specifier written out in
   full. `external: ["../dom/event.js"]` was accepted, matched nothing, and each
   subpath line silently measured the core along with itself. Externals now go
   through an `onResolve` plugin comparing resolved absolute paths. The corrected
   figures are the ones tabled above; before the fix the same build reported
   spatial 3.41 kB, focus ring 1.93 kB and debug 1.55 kB.

Rule 3's quarter-kB rounding leaves the gamepad and whole-package lines at 99 % of
their caps. That is the rule working as written — headroom for noise, not for
growth — and the next commit that grows either one needs an amendment here first.

**The react adapter line, added the same day:** 2.35 kB min, **1.13 kB min+gzip**,
capped at 1.25 kB. It leaves out `input-system.js` and `modality.js`, which the
core already pays for, and `react` and `react/jsx-runtime`, which are optional
peers the consumer supplies. `internal/env.js` and `internal/equality.js` are
charged here rather than to the core: they exist only for the adapter, and the
core inlines its single assertion and has no `utils` module at all.

That line exposed a fourth script defect, of the same family as the three above:
the external mechanism handled relative paths only, so `react` was bundled into
the measurement and the line first read **9.77 kB min+gzip, 29.04 kB minified** —
a consumer's own copy of React reported as this package's cost. A bare specifier
is now matched by name, and it has no file to check against because it is not a
file of this package.

The whole-package line does not include the react entry, and that is deliberate:
its contract is "every runtime entry bundled with nothing external", and react is
external by definition.

## Amendment, 2026-09-20: the pre-merge review, and four caps rewritten

`bun run build && bun run check:size`, run 2026-09-20 on the extraction branch,
bun 1.4.0, tsdown 0.23.0, same target and gzip level as the amendment above. Caps
by rule 3, the measurement rounded up to the next quarter kB.

| Line | min | min+gzip | cap | was |
|---|---|---|---|---|
| core | 7.76 kB | 3.13 kB | 3.25 kB | 3.25 kB, unchanged |
| gamepad engine | 5.37 kB | 2.48 kB | 2.50 kB | 2.50 kB, unchanged |
| spatial engine | 7.28 kB | 3.04 kB | 3.25 kB | 3.25 kB, unchanged |
| focus ring | 3.22 kB | 1.51 kB | **1.75 kB** | 1.50 kB |
| debug | 0.62 kB | 0.40 kB | **0.50 kB** | 0.75 kB |
| react adapter | 2.87 kB | 1.30 kB | **1.50 kB** | 1.25 kB |
| whole package | 22.67 kB | 8.77 kB | **9.00 kB** | 8.75 kB |

Three of the four moves are raises, and they are what rule 4 exists to make
deliberate. The fourth is a cut.

- **Focus ring, 1.44 → 1.51 kB.** The overlay now carries its own `z-index`, as the
  custom property `--snav-focus-ring-z-index` defaulting to 1700
  (`src/focus-ring/focus-ring.ts:52`), and fades in and out under its own WAAPI
  animation, `ring.animate` (`src/focus-ring/focus-ring.ts:150`), rather than a CSS
  `transition: opacity` — this package ships no stylesheet to hold either. Both were
  defects found in review, not features: without the first the ring paints behind
  any dialog, and without the second it cuts in and out. Both are covered: the ring
  paints at 1700 and stacks above a `z-index:1300` dialog
  (`src/focus-ring/focus-ring.browser.test.ts:135`,
  `src/focus-ring/focus-ring.browser.test.ts:167-168`), and it leaves a running
  animation behind rather than vanishing
  (`src/focus-ring/focus-ring.browser.test.ts:180-181`).
- **React adapter, 1.13 → 1.30 kB.** `NavDocumentProvider` no longer lets an inline
  `doc` getter's identity reach the provider's effect, and `keymap` is now compared
  entry-wise the way `plugins` already was. The shared `recordEquals` is charged
  here for the same reason `arrayEquals` is.
- **Whole package, 8.64 → 8.77 kB.** The sum of the focus-ring growth and the
  unwinding a throwing plugin teardown now does in `input-system.js`. The react
  entry is still not on this line.
- **Debug, capped at 0.75 kB, measured 0.40 kB.** A cut, not a raise. The cap was
  written from a 0.50 kB measurement taken before `explainMove` was refactored to
  ask `findBestCandidate` for its winner; the line shrank and the cap did not
  follow, leaving 87 % slack that rule 3 does not allow. The table in the
  amendment above still reads 0.50 kB, which is what the line measured on the day
  that amendment is dated — it stands as the record of 2026-09-19, and this row is
  the record of what the same command prints now.

Rule 4 says a cap is raised by an amendment in its own commit and never in the
pull request that exceeded it. Read literally that forbids this amendment, since
the caps above were themselves first written three commits earlier in this same
pull request. The rule is aimed at a later feature PR quietly buying itself room;
the extraction PR that both writes the first caps and then corrects them against
a review is the case the rule was not written for. The amendment is still its own
commit, which is the part that carries the intent.

The quarter-kB rounding now leaves only the gamepad engine at 99 %. It has not
moved since the first measurement, and the next commit that grows it still needs
an amendment here first.

## Amendment, 2026-09-20: a fifth script defect, in the debug line's externals

No cap moved. What moved is what the debug line measures, which is the same family of
defect as the four above: `tabbable.js` was not in its `external` list, so the line
charged the debug entry for a copy of it that no consumer downloads.

It went unnoticed because `explainMove` imported nothing from the core — the omission
cost nothing until something did. Adding `scanNativeSelects`, which calls the engine's
`isFocusable` ([ADR-0021](0021-native-select-on-television.md)), took the line from
0.40 kB to **0.77 kB min+gzip against a 0.50 kB cap, 153 %** — a failure that was
almost entirely the measurement rather than the code.

The spatial line already declares `../tabbable.js` external, and for exactly the
reason that applies here: the core exports it, so a subpath measured next to the core
must not be charged for it. Nothing reaches `/debug` without the core — the entry
re-exports the engine's own scoring types. With the external added the line reads
**0.78 kB min, 0.49 kB min+gzip, 97 % of its unchanged cap**
(`bun run build && bun run check:size`, 2026-09-20).

That 97 % is the rule working as rule 3 intends — headroom for noise, not for growth.
The next diagnostic added to the debug entry needs a cap amendment here before it
lands, and unlike this one it will be a real 0.25 kB of bytes.

The general lesson, now the fifth time: an `external` list is a claim about what the
consumer already has, and it is only tested by a line that actually imports something.
Four lines still have entries no current import exercises.

## Amendment, 2026-09-20: four lines for the keyboard, and the shape of a layout line

`bun run build && bun run check:size`, same toolchain as the two amendments above. Four
lines added for the on-screen keyboard of
[ADR-0022](0022-virtual-keyboard.md), each written the way rule 5 asks: added with
`cap: null`, the run went red printing the number, and the cap is the next quarter kB
above it.

| Line | min | min+gzip | cap | what the line leaves out |
|---|---|---|---|---|
| keyboard | 3.38 kB | 1.55 kB | 1.75 kB | `dom/event.js`, `dom/query.js`, `keymap.js`, `tabbable.js` |
| keyboard layout qwerty | 0.87 kB | 0.45 kB | 0.50 kB | nothing — a layout imports nothing |
| keyboard layout azerty | 0.88 kB | 0.49 kB | 0.50 kB | nothing |
| keyboard layout alphabetic | 0.53 kB | 0.36 kB | 0.50 kB | nothing |

**A note on rule 4, so this does not read as a dodge.** The keyboard was first measured
at 1.42 kB and capped at 1.50. Two defects found by its own tests — a controlled React
field rejecting a keystroke, and a caret left at position 0 on open — added 0.13 kB and
took it to 1.55, over that cap. The cap moved to 1.75 rather than the module getting
smaller. Rule 4 is not bent by that: it forbids raising a cap that is *in the
repository*, and this one had been written minutes earlier in the same uncommitted change,
from a measurement of a module that was not finished. What lands here is a first cap under
rule 2, taken from the finished module. A cap that had ever been committed would have
meant the amendment first, in its own commit, as rule 4 says.

**What a layout line is for.** A layout imports nothing at all — its only import is the
type, and a type erases — so its `external` list is empty and its number is the data,
whole. That makes the line a test of decision 3 of ADR-0022 rather than a budget: a
layout is supposed to be literal data, and a layout line that stops being tiny is
behaviour that leaked into one. The azerty line at 0.49 of 0.50 is the tightest in the
file, and it is tight for an honest reason — it carries an accented layer qwerty does not.
The next character added to it needs an amendment here.

## Amendment, 2026-09-20: the keyboard cap goes to 2.25 kB, for a plugin that had no paint

`bun run build && bun run check:size`, same toolchain as the amendments above.

| Line | min | min+gzip | old cap | new cap |
|---|---|---|---|---|
| keyboard | 4.47 kB | 2.01 kB | 1.75 kB | 2.25 kB |

**Rule 4, properly this time.** The 1.75 kB cap above was committed, so unlike the note
in the previous amendment this is a cap *in the repository* being raised. That is what
rule 4 reserves an amendment in its own commit for, and this is that commit: the code it
pays for lands in the next one.

**What the 0.46 kB buys.** The keyboard shipped with no style at all. A plugin that
appends an unstyled `<div>` to `document.body` inherits the page's block layout, so it
drew itself the full width of the viewport — measured at 1280 by 304 on a 1280 by 800
window, 38% of the screen, over whatever was under it — and it was anchored to nothing,
which is the opposite of the `<select>` menu a surface expects. That was a defect
against [ADR-0020](0020-focus-ring-defaults.md)'s own reasoning, which the focus ring
follows and this plugin did not: a plugin that needs a stylesheet imported ships broken
to whoever forgets, so it carries its own paint inline.

So the bytes are the paint, the placement that anchors the box to the field and flips it
above when there is no room below, the `activate` opening mode, and the close-on-leave
that stops an open keyboard from swallowing the page's activations. Measured after the
fix at 492 by 338, 16% of the same viewport.

**Rule 3 gives 2.25.** The measurement is 2.01 kB and the next quarter above it is 2.25.
The line sits at 89% used, which is the same headroom the module had before.

## Amendment, 2026-09-21: the keyboard cap goes to 3.00 kB, for the preview row and the caret

`bun run build && bun run check:size`, run 2026-09-21, same toolchain as the amendments above.

| Line | min | min+gzip | old cap | new cap |
|---|---|---|---|---|
| keyboard | 6.60 kB | 2.82 kB | 2.25 kB | 3.00 kB |

**Rule 4, again properly.** The 2.25 kB cap was committed by the amendment above, so this is a
cap in the repository being raised, in its own commit, with the code landing in the next one.

**What the 0.81 kB buys.** A preview row at the bottom of the box that mirrors the field — its
value on one line, a caret drawn where the field's selection is, bullets for a password — and
the directions moving that caret while the row has the focus; a caret the plugin owns for a
field that exposes no selection; the focus put back on the key at the same position after a
shift or layer re-render, which used to drop it to `body`; a fifth custom property for the
box's text colour; the four attribute names as exported constants; and all four insets written
by the placement. The record is [ADR-0022](0022-virtual-keyboard.md), amendment of the same day.

**No new external, and the one that was avoided.** The caret moves through the keyboard's own
scope, so the line imports nothing it did not import before and its `external` list is
unchanged. The design that was measured and rejected — the engage grammar, A holding the caret
— would have imported `pushEngageScope`, and `engage.js` is a core export that the keyboard line
does not declare external: the measurement would have charged the consumer a second copy, which
is the family of defect the amendment on the debug line describes, for the sixth time. It did
not happen because the import did not.

**A figure in this record is corrected.** The amendment above says the box measured "492 by
338, 16% of the same viewport". That was measured through a stale rule in the playground's
stylesheet, `inset: auto 0 72px 0` on `[data-snav-keyboard]`, which stretched the box from the
plugin's `top` to 72 px above the bottom — 338 is 800 − 390 − 72 — and over the field. With
that rule deleted and the plugin owning all four insets, the same page measures the box at 492
by 335, from 356 to 691 above a field at 695 to 716 (chromium, 1280 by 800, 2026-09-21). The
height is the playground's 44 px keys plus the preview row; a page that styles its keys
differently gets a different box, which is why the number travels with the page.

**Rule 3 gives 3.00.** The measurement is 2.82 kB and the next quarter above it is 3.00. The
line sits at 94% used.

## Amendment, 2026-09-21: the whole-package line holds every runtime entry, and its cap goes to 12.50 kB

`bun run build && bun run check:size`, run 2026-09-21, same toolchain as the amendments above.

| Line | min | min+gzip | old cap | new cap |
|---|---|---|---|---|
| whole package | 32.84 kB | 12.40 kB | 9.00 kB | **12.50 kB** |
| gamepad engine | 5.42 kB | 2.49 kB | 2.50 kB | 2.50 kB, unchanged |

**The note was false, and it was the line that made it false.** `whole package` reads "every
runtime entry bundled once, nothing external — the debug entry is excluded on purpose". It held
four entries: `index`, `gamepad`, `spatial`, `focus-ring`. The package exports nine runtime
subpaths. The keyboard, its three layouts and the React adapter were outside the one line whose
whole purpose is to catch what the individual lines cannot — a shared module getting expensive for
everyone while every line stays green. A gate that names nine and measures four is worse than one
that names four: it reports green about a claim it never tested.

**Decision 1 and the stance of 2026-09-19 are reversed, nominally.** Decision 1 asks for "one
whole-package line, every runtime entry bundled with nothing external", and the amendment of
2026-09-19 closes with "The whole-package line does not include the react entry, and that is
deliberate: its contract is *every runtime entry bundled with nothing external*, and react is
external by definition." Both keep their words; this record is where they stop holding. The
contract had two halves
and they have come apart. "Every runtime entry" and "nothing external" cannot both hold once the
package ships an adapter whose peer is somebody else's library. This record keeps the first half
and gives up the second, for two specifiers and no more: `react` and `react/jsx-runtime`.

**Why the peer has to be external rather than the entry absent.** Measured, same command and day:
with the react entry on the line and no external list, `whole package` reads 21.06 kB min+gzip.
That number is about React, not about this package — it is the size of a library every consumer of
the adapter already has and which [ADR-0011](0011-package-layout-and-adapters.md) declares an
optional peer, never a dependency. Bundling it would make the line grow when React grows, which is
the opposite of what rule 1 asks a budget to measure. The react adapter's own line has declared
those two specifiers external since it was written; this line now says the same thing.

**What the 3.62 kB is made of.** From 8.78 kB: the keyboard plugin adds 2.21, its three layouts
0.48 together, and the React adapter 0.93. None of it is new code — all of it was already shipped
and already measured on a line of its own. What changed is that the sum now includes it.

**One thing the line overstates, on purpose.** No consumer ships three keyboard layouts; the
subpaths exist precisely so a French application ships no Cyrillic. The line is not a claim about
what one consumer downloads — the per-subpath lines are that — it is the ceiling on everything the
package ships as runtime code, so that no entry can grow unwatched. Reading it as a download size
would overstate by roughly the two layouts nobody takes.

**The gamepad engine moved, and this record says so a commit late.** The amendment of 2026-09-20
ends "the next commit that grows it still needs an amendment here first". The commit that added
the `navigator.getGamepads` guard ([ADR-0013](0013-browser-baseline-and-fallbacks.md), amendment of
2026-09-21) grew the line from 2.48 to 2.49 kB and did not come here first. Rule 4 is written
about raising a cap and no cap moved — 2.49 rounds up to the same 2.50 — so the run stayed green
and the rule was not broken; the expectation that amendment set was, and this is the record of it
rather than a silence. The line now sits at 100 % of its cap with **eleven bytes** to spare — 2 549
of 2 560, the two numbers the rounding to 2.49 and 2.50 kB hides, read off the same run. The
next commit that touches the gamepad engine does need a cap here first, and this time the sentence
is load-bearing.

**Rule 3 gives 12.50.** The measurement is 12.40 kB and the next quarter above it is 12.50. The
line sits at 99 % used, which is rule 3 working as intended: headroom for noise, not for growth.

## Amendment, 2026-09-22: a twelfth line for the vanilla auto-mount, and the whole package goes to 12.75 kB

`bun run build && bun run check:size`, run 2026-09-22, same toolchain as the amendments above.
This record comes **before** the commit that adds the entry, which is what rule 4 asks of a cap
that has to move.

| Line | min | min+gzip | old cap | new cap |
|---|---|---|---|---|
| auto mount | 1.04 kB | 0.62 kB | none, the line is new | **0.75 kB** |
| whole package | 33.64 kB | 12.64 kB | 12.50 kB | **12.75 kB** |

**Why a line at all, for 0.62 kB.** Decision 2 gives every subpath its own line, and rule 5 of the
budget script makes a line without a cap fail the run (`scripts/size-budget.ts:393-397`). The
vanilla auto-mount helper is a subpath, `@standarx/nav/auto`
([ADR-0023](0023-vanilla-auto-mount.md)), so it gets a line whether or not the number is
interesting. It is small because it is meant to be: two branches, a mode read off one attribute,
and `createInputSystem` called once.

**Its externals are one specifier, and the reason is the rule about globs.** The line names
`../input-system.js` external and nothing else. That is the only module the helper imports, and
nothing reaches `/auto` without the core, so charging a second copy of the input system here would
measure bytes no consumer downloads. The `SpatialMode` type the helper's config names is a
**type-only** import, which erases at build: there is no spatial module on this line to externalise
in the first place, and the helper's 0.62 kB is therefore a number about the helper.

**0.62 on its own line and 0.24 on the whole-package line are two different measurements, and both
are right.** The whole package moved from 12.40 to 12.64 kB min+gzip — 0.24 kB — while the helper's
own line reads 0.62. Neither is wrong and neither is the other's error: on its own line the module
is bundled alone with the core external, and on the whole-package line it is one module among
twelve, minified and compressed against everything else the package ships. The per-subpath line
answers "what does adding this next to the core cost"; the whole-package line answers "how much
runtime code does this package ship". The gap between them is what sharing a minifier and a gzip
window buys, not a defect in either line.

**Rule 3 gives 0.75 and 12.75.** The helper measures 0.62 and the next quarter above it is 0.75, at
83 % used. The whole package measures 12.64 and the next quarter above it is 12.75, at 99 % used —
the same one-percent margin the line has carried since the amendment above, and for the same
reason: rule 3 is headroom for noise, not for growth. The next entry point added to this package
needs an amendment here before its commit, and at 99 % that sentence is load-bearing again.

## Amendment, 2026-09-22: the auto-mount line reads 0.60, not the 0.62 recorded above

Same day, same toolchain, one commit later. Making `MODE_ATTRIBUTE` private — the spatial
engine's nine attribute constants are private for the reason
[ADR-0011](0011-package-layout-and-adapters.md) gives, and `data-snav-mode` is the same kind of
name — dropped the export and with it a few bytes.

| Line | min+gzip before | min+gzip now | cap |
|---|---|---|---|
| auto mount | 0.62 kB | **0.60 kB** | 0.75 kB, unchanged, 80 % used |
| whole package | 12.64 kB | **12.63 kB** | 12.75 kB, unchanged, 99 % used |

No cap moves, so rule 4 is not in play and the run never went red. This record exists because
the amendment above states 0.62 and 12.64 as measurements, and those two numbers stopped being
true before the pull request that carries them was opened.

**One other slip in the amendment above, corrected here rather than edited there.** It says the
helper is "one module among twelve" on the whole-package line. Twelve is the number of budget
*lines*; the whole-package line groups **ten** entries, and the bundle behind it holds more
modules than either number, since each entry drags its own graph in. The sentence's point — that
a module compresses better among everything else the package ships than it does bundled alone —
is unaffected by the miscount. The amendment above is not edited:
it is what was measured when it was written, which is the whole point of dating it. A reader
comparing either record against `bun run check:size` should expect 0.60 and 12.63, and the
figures quoted in [ADR-0023](0023-vanilla-auto-mount.md) are the corrected ones.

## Amendment, 2026-09-23: the whole-package line is removed, and what it stood for is checked directly

Decision 1 asked for two kinds of line: a marginal one per subpath, and one whole-package sum.
The second is gone. Eleven lines remain and none of them moved.

**The question that ended it.** No consumer downloads every entry — that is the entire point of
the subpath layout ([ADR-0011](0011-package-layout-and-adapters.md)). A React application
downloads the core and the react adapter; a vanilla one downloads the core. The amendment of
2026-09-21 already conceded this in so many words: "The line is not a claim about what one
consumer downloads — the per-subpath lines are that." What nobody asked until now is what the
line therefore *did*, and the honest answer is that it conflated two different events. Existing
code getting fatter is the thing worth catching. A new entry being added is not — it harms no
existing consumer — and because the line is a **sum**, that is exactly what made it go red. Each
of `/auto`, Vue, Svelte and Angular would have needed a cap raise for it, four amendments that
could only ever say yes. A gate that cannot say no is ceremony.

**What it was really guarding, and what now guards it.** The externals rule names one genuine
hole: a module marked `external` on every line that reaches it is charged to nobody and can grow
without a single line going red. The whole-package sum was a proxy for that, and a poor one —
it would have shown the growth as a number, never as a name. `check:size` now walks each line's
own graph, stops at that line's externals, and takes the union: any built module outside it is
reported by name and fails the run. Proved by making the failure happen on 2026-09-23 — marking
`dom/platform.js` external on both lines that reach it turns the run red with
`charged to no line: dom/platform.js`, and reverting it green.

**One measurement worth keeping.** The first attempt read the graph from the bundler with a
catch-all `onResolve`. That changes how the entry is tree-shaken: the core line fell from
3.13 kB to **0.38** while reporting success — the same class of silent under-measurement decision
5 and the synthetic-module comment already describe. The graph is therefore parsed from the built
output instead, and `moduleImports` carries that reason.

**What is lost.** No single number now says "everything this package ships as runtime code". That
number was 12.63 kB on 2026-09-22 and no document quotes it as a consumer cost any more; the
README shows the core's 3.13 kB instead, which is what every consumer actually pays. If a future
question genuinely needs the total, it is one `bun run build` and a sum away, and it does not
need a cap to be answerable.

**Rule 4 is untouched** and now applies only where it means something: a cap moves when measured
code outgrows it. Adding an entry no longer moves anybody's cap.

## Amendment, 2026-09-23 (second): a twelfth line, for the Vue adapter

`bun run build && bun run check:size`, run 2026-09-23. The Vue adapter is a subpath,
`@standarx/nav/vue` ([ADR-0027](0027-vue-adapter.md)), so it gets a line; it is new, so no cap
moves and rule 4 is not in play. The line went in with `cap: null` first and the run went red as
rule 5 intends, `vue adapter: measured 1.40 kB min+gzip and has no cap`, then the cap was written.

| Line | min | min+gzip | cap |
|---|---|---|---|
| vue adapter | 3.12 kB | **1.40 kB** (1 434 B) | **1.50 kB** (1 536 B), 93 % used |
| react adapter | 3.32 kB | 1.42 kB (1 452 B, was 1 450) | 1.50 kB, unchanged, 95 % used |

**Rule 3 gives 1.50.** The next quarter above 1.40 kB is 1.50 kB, 102 bytes of room.

**Its externals mirror the React line's.** `vue`, a peer the consumer supplies, and
`../input-system.js` and `../modality.js`, which the core already ships
(`scripts/size-budget.ts:135-141`). The three `internal/` modules are charged here as they are to
the React line: `env.js`, `equality.js`, and `scope-registry.js`, which the same pull request moved
out of the React adapter so that both adapters share it. That move is the React line's 2 bytes.

Twelve lines, every built module charged to one: `size budgets passed for 12 lines, and all 30
built modules are charged to one`, 2026-09-23.

## Amendment, 2026-09-24: a thirteenth line, for the Svelte adapter

`bun run build && bun run check:size`, run 2026-09-24. The Svelte adapter is a subpath,
`@standarx/nav/svelte` ([ADR-0028](0028-svelte-adapter.md)), so it gets a line; it is new, so no cap
moves and rule 4 is not in play. The line went in with `cap: null` first and the run went red as
rule 5 intends, `svelte adapter: measured 1.45 kB min+gzip and has no cap`, then the cap was
written.

| Line | min | min+gzip | cap |
|---|---|---|---|
| svelte adapter | 3.19 kB | **1.45 kB** (1 481 B) | **1.50 kB** (1 536 B), 96 % used |
| vue adapter | 3.12 kB | 1.40 kB (1 434 B), unchanged | 1.50 kB, unchanged, 93 % used |
| react adapter | 3.32 kB | 1.42 kB (1 452 B), unchanged | 1.50 kB, unchanged, 95 % used |

**Rule 3 gives 1.50.** The next quarter above 1.45 kB is 1.50 kB, 55 bytes of room — less than
either sibling has, and the reason the adapter's development warning is one short sentence.

**Its externals mirror the React and Vue lines'.** `svelte` and `svelte/store`, peers the consumer
supplies, and `../input-system.js` and `../modality.js`, which the core already ships
(`scripts/size-budget.ts:142-148`). The three `internal/` modules are charged here as they are to
the other two adapter lines.

Thirteen lines, every built module charged to one: `size budgets passed for 13 lines, and all 31
built modules are charged to one`, 2026-09-24.

## Amendment, 2026-09-24 (second): a fourteenth line, for the Angular adapter

`bun run build && bun run check:size`, run 2026-09-24. The Angular adapter is a subpath,
`@standarx/nav/angular` ([ADR-0029](0029-angular-adapter.md)), so it gets a line; it is new, so no
cap moves and rule 4 is not in play. The line went in with `cap: null` first and the run went red as
rule 5 intends, `angular adapter: measured 1.67 kB min+gzip and has no cap`, then the cap was
written.

| Line | min | min+gzip | cap |
|---|---|---|---|
| angular adapter | 3.80 kB | **1.67 kB** (1 707 B) | **1.75 kB** (1 792 B), 95 % used |
| svelte adapter | 3.19 kB | 1.45 kB (1 481 B), unchanged | 1.50 kB, unchanged, 96 % used |
| vue adapter | 3.12 kB | 1.40 kB (1 434 B), unchanged | 1.50 kB, unchanged, 93 % used |
| react adapter | 3.32 kB | 1.42 kB (1 452 B), unchanged | 1.50 kB, unchanged, 95 % used |

**Rule 3 gives 1.75.** The next quarter above 1.67 kB is 1.75 kB, 85 bytes of room. It is the
heaviest adapter line, 226 bytes above the svelte one; which part of the module those bytes are is
not measured.

**Its externals mirror the other adapter lines'.** `@angular/core`, the peer the consumer supplies,
and `../input-system.js` and `../modality.js`, which the core already ships
(`scripts/size-budget.ts:149-155`). The three `internal/` modules are charged here as they are to
the other three adapter lines.

Fourteen lines, every built module charged to one: `size budgets passed for 14 lines, and all 32
built modules are charged to one`, 2026-09-24.

## Alternatives considered

**A bundlephobia badge in the README.** Rejected: it is not blocking, it lags
the published version, it cannot exist before publication, and it measures one
thing (the whole package) out of the several this package needs measured. A
badge also invites a number without the command that produced it, which rule 8
forbids.

**A single total cap for the package.** One ceiling, everything bundled.
Rejected: it charges a core-only consumer for the gamepad engine they never
import, and hides a regression in one subpath behind slack in another. The same
choice was made once before, a single 4 kB line for the two engines **split** rather
than raised when the pair measured 5.16 kB — inherited from the predecessor
implementation ([ADR-0002](0002-license-and-copyright.md)) and not re-derived here.
The split is what this repository does: fourteen separate lines, one per entry
(`scripts/size-budget.ts:80-186`).

**`size-limit` instead of a written script.** Rejected: these budgets ask "what does
a consumer pay", not "how big is this file" (`scripts/size-budget.ts:5-7`), so
`size-limit` would need a synthetic entry per line anyway — which is what every line
here is already bundled through (`scripts/size-budget.ts:308-332`).

**Inherit the caps rather than measure them.** Rejected by rule 2. An inherited cap
would be green or red for reasons belonging to a build this repository does not run:
a different bundler, a different target and a different file layout. Every cap here
was written from a measurement taken here — the two amendments above are the record,
and the numbers are in `scripts/size-budget.ts:80-186`.

## Evidence

- Inherited measurements, min+gzip at Bun's default gzip level: input system 1.93 kB
  of 2.00 kB (96 %), gamepad 2.35 kB of 3.00 kB (78 %), spatial 2.81 kB of 3.00 kB
  (94 %), modality tracker 0.74 kB of 1.00 kB (74 %), together with the 3 303 B
  spatial-without-externals figure. All inherited from the predecessor implementation
  ([ADR-0002](0002-license-and-copyright.md)) and not re-derived here.
- This repository's `scripts/size-budget.ts`, declared as `check:size`
  (`package.json`): fourteen lines — `core` (`index.js`), `gamepad engine`, `spatial
  engine`, `focus ring`, `debug`, `auto mount`, `react adapter`, `vue adapter`, `svelte adapter`,
  `angular adapter`, `keyboard` and one per keyboard layout
  (`scripts/size-budget.ts:80-186`). Each opt-in line names the part of the core graph
  it also imports as `external`, file by file and never globbed, because `*` does not
  cross a path separator and a glob is how a line stops measuring while staying green
  (`scripts/size-budget.ts:67-79`; the lists themselves at
  `scripts/size-budget.ts:87-166`), while `core` declares none. All fourteen caps are written
  (`scripts/size-budget.ts:84`, `scripts/size-budget.ts:90`,
  `scripts/size-budget.ts:97`, `scripts/size-budget.ts:104`,
  `scripts/size-budget.ts:111`, `scripts/size-budget.ts:121`,
  `scripts/size-budget.ts:131`, `scripts/size-budget.ts:138`, `scripts/size-budget.ts:145`,
  `scripts/size-budget.ts:152`, `scripts/size-budget.ts:159`, `scripts/size-budget.ts:169`,
  `scripts/size-budget.ts:177`, `scripts/size-budget.ts:183`); a line whose `cap` is
  `null` prints its measurement
  and exits non-zero (`scripts/size-budget.ts:393-397`), and a missing `dist/` exits
  first with a message pointing at `bun run build`
  (`scripts/size-budget.ts:382-385`).
- The coverage check that replaced the whole-package line: `builtModules`
  (`scripts/size-budget.ts:195-207`) walks `dist/`, `chargedBy`
  (`scripts/size-budget.ts:230-244`) walks each line's graph and stops at its externals,
  and `uncoveredModules` (`scripts/size-budget.ts:251-253`) names what no line pays for.
  The graph is read off the built output by `moduleImports`
  (`scripts/size-budget.ts:215-223`) rather than asked of the bundler, because a catch-all
  `onResolve` changes how the entry is tree-shaken — measured on 2026-09-23, it took the
  core line from 3.13 kB to 0.38. Ten unit cases in `scripts/size-budget.test.ts`.
- Bun's default gzip level, and the instruction never to mix it with `gzip -9`:
  `scripts/size-budget.ts:11-12`. Why `size-limit` would need a synthetic entry per line
  anyway, and the synthetic module every line is bundled through:
  `scripts/size-budget.ts:5-7` and `scripts/size-budget.ts:308-332`.
- Historical figures of 2026-08-27 (2.48 kB gamepad, 2.89 kB spatial, 1.34 kB focus
  ring): inherited from the predecessor implementation
  ([ADR-0002](0002-license-and-copyright.md)) and not re-derived here. That gamepad
  figure is numerically identical to the gamepad line measured here on 2026-09-19 and
  again on 2026-09-20; they are measurements of different builds, and neither is
  evidence for the other.
- Measured here: `bun run build && bun run check:size` (both scripts in `package.json`) on
  2026-09-19 and again on 2026-09-20, when the file held eleven lines, and on 2026-09-22
  for the twelfth, and on 2026-09-23, after the whole-package line had gone, for the vue
  adapter's, and on 2026-09-24 for the svelte and angular adapters'; the lines and their
  caps are `scripts/size-budget.ts:80-186`, and the run is enforced in CI
  (`.github/workflows/ci.yml:57-58`).
- The rule that a size in a document travels with its command and date:
  [CONTRIBUTING](../../CONTRIBUTING.md), and `.github/PULL_REQUEST_TEMPLATE.md:46` as
  a checklist item.