# Conventions

The rules a change to this theme has to follow. Every one of them is a bug that was hit, and
most are enforced by a gate — the gate is named next to the rule so you can check yourself
before pushing.

Read this before your first patch. For what the theme *is*, start at
[architecture.md](architecture.md).

## The two commands

```sh
npm run check        # every gate below, in one run; must exit 0 before you push
owlab test --release 25.12.4 --install 'dist/noarch/luci-theme-footstrap-*.apk' \
  --assert 'package luci-theme-footstrap' \
  --assert 'http 200 /cgi-bin/luci/admin/status/overview'
```

…and the same again with `--release 24.10.8 --install 'dist/all/*.ipk'`. One run per format:
`--install` is a host-side glob evaluated per router, so a pattern matching both hands the apk box
an ipk.

Nothing in `package.json` is shipped. `luci.mk` copies `htdocs/` and `ucode/` verbatim and
never invokes node, and the OpenWrt buildbot has no node at all.

## Keep owlab installed, and run the change on a router

**owlab is required, not a convenience.** Install it once and keep it:

```sh
go install owfeed.org/owlab/cmd/owlab@latest
owlab doctor
```

**A change that alters behaviour is not finished until it has run on a real OpenWrt userland**, on
**both** package managers — 25.12/apk and 24.10/opkg. Not "it should work", not "the gates are
green": run it. `owlab up` gives you four disposable routers from `owlab.yaml`, and
`owlab test` is the local form of the same assertions CI's `verify` job makes. How:
[development.md](development.md).

Why the rule is written down rather than assumed: **every gate in this repository is static.** They
read files. Not one of them opens a page. The classes of bug they structurally cannot see:

- a preference that writes to the wrong place (the appearance axes were gated on their *contract*
  while one of them silently rewrote a router-wide default);
- anything that only appears once a session, a poller or a second browser exists;
- a template that compiles and renders the wrong thing;
- an install path — `postinst`, `uci-defaults`, the marker file, a conffile surviving an upgrade;
- any difference between apk and opkg.

A stubbed harness in node is worth running for what it does prove — that a module initialises, that
an axis stores where you think — but it proves nothing about the router. Say which of the two you
did; do not let one stand in for the other.

**If you genuinely cannot run it** (no Docker on the machine), say so plainly in the commit or the
PR rather than reporting the change as verified. An untested change described as tested is worse
than an untested change.

## Writing CSS

**Read only the private tier.** Every rule in `styles/` reads `--fs-*` and nothing else. The
export names (`--primary-color-high`, `--text-color-*`, …) are defined *from* the private tier
and are for third-party apps only.

```css
color: var(--fs-dim);                                    /* yes */
color: var(--text-color-medium);                         /* no — audit.py --strict fails */
```

Why: `:root` is one shared scope, and every `luci-app-*` puts its CSS in the same document
**unlayered**, which outranks any `@layer`. A hostile `:root` recoloured **312 of 336** gallery
elements before the tiers were split, and 0 after — the measurement and the two tiers are in
[design-system.md](design-system.md).

**Put the rule in the right layer instead of reaching for `!important`.** Layer order is
`tokens, base, theme, page`, and a later layer beats an earlier one regardless of specificity —
so a `theme` rule never needs a flag to beat `base`.

**`!important` inverts layer order** — the mechanics and the numbers behind that are in
[css.md](css.md). Two consequences for a patch:

- If a rule needs a flag to beat **another footstrap rule**, the rule is in the wrong layer.
  Move it or merge the two.
- A legitimate flag fights only what layers cannot outrank: inline `style=` and unlayered
  rules injected by an app.

The one flag sanctioned against *our own* rules is `theme/95-a11y-media.css`:
`prefers-reduced-motion` has to kill animations declared in `base` too, and only an important
declaration reaches back a layer. Everything else on the allowlist fights something outside the
cascade — `theme/90-responsive` and `pages/20-overview` outrank a `style=` written by `29_ports.js`
and `ui.js`, `theme/45-misc` widens the box the realtime graphs size inline and repaints its inline
black border, `theme/65-dropdown` frees `.hide-close` from a RichListValue's inline `min-width:25vw`,
and `styles/base` keeps the six
`.left`/`.right`/… forcing utilities plus two inline-style fighters. `audit.py` keeps that list
(`BANG_OK`), `.stylelintrc.json` states the reason for each file, `npm run bang-ok` holds the two in
step, and `css-metrics` caps the total at **27**.

**Win on specificity, never on source order.** Two rules with the same specificity where the
later one is load-bearing is the same failure as 220 `!important`, only quieter. Cap:
`[1,7,0]`, held by `css-metrics`.

**Edit the rule that already styles the selector.** Do not append a second one. The shadowed-
declaration counter in `audit.py` is at **0** and stays there.

**No colour literals.** A `#hex` follows neither the palette nor dark mode. The single exception
is `--fs-scrim` — black at .7 is the absence of light behind a dialog, not a shade of any token.

**Stay inside your zone.** There are three: the theme's own chrome (`fs-*` names, `data-fs-chrome`
roots — ours alone, and fenced against foreign CSS); the shared LuCI widget surface (`cbi-*`,
`.table`, `.alert-message` — ours to style, nobody's to own); and another package's namespace,
which the theme never reaches into. `fs-overview.js` used to live in `luci-mod-status`'s global
include directory, where LuCI evaluates every `*.js` — so it was downloaded and run on the
overview of routers using a different theme. It is a chrome module now. The fence that keeps
foreign CSS out of zone one is described in [third-party-apps.md](third-party-apps.md).

**Coverage is a contract.** A selector no stock LuCI page renders still gets styled: some
third-party `luci-app-*` emits it. "Looks unused, delete it" un-styles somebody's app. PurgeCSS,
uncss and any coverage-based trimming are forbidden here. The one safe dead-CSS search is
`css-orphans`, and it is safe only because nothing outside the theme can emit an `fs-*` class.

**Pin a duplicate you cannot merge.** `css-dup` finds identical declaration bodies under
mutually exclusive guards — a shape no linter calls an error and the shape that drifts. Worse,
`css-dup` matches *identical* bodies, so it goes quiet exactly when the copies diverge. Every
duplicate body must be either merged or wrapped in `@mirror`, and `tools/mirror.mjs` then holds
the copies byte-identical. A `@mirror` group with one copy is a hard failure.

**A `display` rule on `.table`/`.thead`/`.tbody`/`.tfoot`/`.tr`/`.th`/`.td` needs a role to match.**
A `display` other than `table`/`table-row`/`table-cell`/… drops the implicit `table`/`row`/`cell`
role HTML-AAM derives from it (WCAG 1.3.1), and `fs-select.js`'s role map is what puts it back.
`tools/table-contract.mjs` holds both directions: it fails if the role map shrinks and it fails if a
theme selector sets `display` on one of these classes with no entry in the map to pair with it.

**A flex item's automatic minimum size defaults to its CONTENT size, and `overflow` is what zeroes
it.** Any flex item with no explicit `min-width` (row axis) or `min-height` (column axis) still has
one: the *automatic minimum size*, which resolves to the item's min-content box unless the item's
own `overflow` is something other than `visible`, in which case the automatic minimum drops to zero
(CSS Flexbox §4.5). One cause, four symptoms in one session, in both directions:

- `.cbi-checkbox` is `inline-flex` and its pill had no `flex-shrink: 0` — the automatic minimum let
  the pill compress below its declared `--sw-w` while the knob kept its literal size and a travel
  distance derived from the width the pill no longer had.
- Under 767px a form label is `flex: 1 1 100%` with no `min-width` on ssclash — its automatic
  minimum fell back to content width and it escaped its own section.
- A closed dropdown's `overflow: hidden; text-overflow: ellipsis` were already correct and inert:
  the automatic minimum held the `li` at content width, so there was nothing left to clip.
- The opposite fault, same rule: `overflow: hidden` on a row-action button zeroed *its* automatic
  minimum, so `flex-grow` divided the row by count instead of by need and every button converged on
  one width at every viewport — a desktop regression shipped as the fix for a phone one.

Before adding a declaration to a flex item, name which of the two behaviours it needs: a button that
must actually shrink wants `overflow: hidden` (or an explicit `min-width: 0`) to reach zero; a label
or a pill that must clip while holding its own width wants the overflow property paired with an
explicit `min-width`/`max-width` that is not `auto`, so the automatic minimum never gets a vote.
**No gate holds this rule in general.** `pseudo-loc` catches the first shape after the fact — a
caption that grew and then overflowed its shrunk pill reads as a finding — but not the third: an
inert `text-overflow: ellipsis` produces no overflow at all, because the box it sits on was never
given the room to shrink in the first place, and nothing measures a clip rule that never fires.

## Writing JS

**Never put a regex literal straight after `return` or `=>`.** `jsmin` (which `luci.mk` runs on
the buildbot) decides whether `/` opens a regex or divides by looking at one preceding
character, and neither `n` (from `return`) nor `>` (from `=>`) is in its list:

```js
return /^https?:\/\//i.test(a);      /* jsmin reads // as a comment, EATS THE REST OF THE FILE
                                        and exits 0 */
return (/^https?:\/\//i.test(a));    /* `(` is in the list — safe */
```

Upstream bugs: openwrt/luci#8299, #8020, #8021, #8256. **A zero exit code proves nothing** —
the corruption is silent. Two gates: eslint's `wrap-regex` forbids the shape, and
`tools/jsmin-verify.mjs` builds the same jsmin and fails unless the token stream of the minified
output matches the source. A backtick inside `${…}` in a template string is out too (jsmin loses
the string, but that one fails loudly).

**Comments are free on the router.** They are ~60% of the JS source and none of them ship:
release CI pre-minifies with terser, and a node-less build runs jsmin. What a comment says is
governed by "Comments" below.

**A required module is a singleton; there is no inheritance between modules.** `'require X'`
hands you a constructed instance, not a class, so `base.extend` from another module throws
`base.extend is not a function`, and returning a plain object throws `factory yields invalid
constructor`. Compose instead: `menu-footstrap-common.js` exports `init(renderMainMenu)` and
`menu-footstrap.js` injects its renderer as a parameter.

**Require a *stock* class through `window.L`.** The `L` a module factory receives and
`window.L` are different objects, and `ui` hangs its helpers (`itemlist`, `showModal`, …) on
`window.L` only. Worse, `require()` caches by class name, so the *first* requirer fixes the
class↔`L` binding — a theme module that beats the router to a stock class makes the page die on
`L.itemlist is not a function`, intermittently. Use `const RT = window.L; RT.require(name)`.

**`E()` cannot build SVG.** It goes through `document.createElement`, which is the HTML
namespace. SVG in the theme is assembled as a string with fixed markup, and user data goes in
separately via `textContent`. This is a namespace fact, not a style choice.

**All "does it fit?" logic goes in `fs-fit.js`.** One engine, one `ResizeObserver`, one
per-frame coalescer for the whole theme. Do not grow a second observer. Its three rules — measure
uncollapsed, re-fit synchronously on a mutation, coalesce on resize — are each a bug that was hit;
they are documented in the file header.

**Never answer "does it fit?" with a viewport breakpoint.** `matchMedia('(max-width: 767px)')`
used to decide this, and between 768 and 779 px the chrome drew as a bar while the menu still
behaved as an accordion. The sidebar gives way when the *content column* would be unreadable,
which depends on the slice (224 px expanded, 68 px rail) — one breakpoint gives both states the
same answer. `data-narrow` on `:root` is the single source of truth, read by both CSS and
`flyoutMode()`.

**Observer hygiene.** Watch the narrowest node, use `attributeFilter`, guard against your own
writes, coalesce into one frame, `disconnect()` on teardown. LuCI's poll rewrites content once a
second, so a loose observer on `document.body` runs a full scan every tick.

**Listener lifecycle: `AbortController` + `{ signal }`**, `abort()` on teardown. It is the only
pattern that reliably removes anonymous handlers.

## Comments

The reader is a model with this file open and no session history. It needs, per line it is about
to change: what must stay true, why, and where the proof is. Everything else costs it context and
gives nothing back. `CLAUDE.md` carries the short form; this is the full rule, with the example
behind each line.

### What a comment carries

| part | example | required |
|---|---|---|
| the invariant | `min-height` AND `height` are pinned to the same value for the whole pass | always |
| the reason, as a number | the bar walked 230 -> 123 px inside one pass, 107 px of growth | when one was measured |
| one pointer | `docs/anchoring.md`, "The corrections"; openwrt/luci#8981; issue #41 | when the proof is longer than a line |

One of each, in that order, in one sentence where it fits. A comment with no invariant is
deleted, not reworded: restating the line it sits on is what it did.

### What a comment does not carry

| cut | goes to | why |
|---|---|---|
| attempts and their order ("first shape … second shape …") | `docs/<area>.md`, one paragraph per attempt | the code is the survivor; the losers are history |
| a task or session name (`task refill2`) | nothing — cite the docs heading instead | names nothing the reader can open |
| a `../tmp/…` path | `docs/<area>.md` restates the finding | the file is not in the repository; the pointer is dead the next day |
| a CI run id | the changelog entry, once | the run expires; the number it produced does not |
| the same fact the docs already hold | one line and the pointer | two copies drift |
| CAPS for emphasis, a rhetorical question, a warning to a future maintainer | plain prose | an LLM weights capitals as shouting, not as priority |

### Size

| comment | limit |
|---|---|
| inline, on or above a statement | 1 line; 2 when the reason is a number |
| above a function or a rule block | 8 lines |
| module or file header | 15 lines: purpose, invariants, what the file does not own |
| comment share of a shipped file | under 40 % of the bytes |

Over the limit means the text is an explanation, and an explanation is a `docs/` section pointed at
from one line. `fs-fit.js` at 85 % comment bytes is the measurement this table comes from: the
rules it documents are sound, and no reader finds them.

### Rules that hold regardless of size

- **A number or a name is part of the contract.** 15 comments once said the poll re-renders
  "once a second" while `pollinterval` ships at 5 s. The comment changes in the edit that changes
  the code, or git preserves the lie.
- **A negative result stays, in one line, present tense.** `display: none` on a zeroed tab pane
  buys nothing: scrollHeight 1039 either way. Not how it was found, not which attempt it was.
- **References survive every compression pass**: issue numbers, spec text quoted verbatim, upstream
  commits, file paths inside the repository.
- **Some comments are code**: `@mirror name/tag` / `@endmirror` (`npm run mirror`), `/* fs:probe */`
  (`strip-probes.sh`), the eslint `'require …'` pragmas, the Makefile's buildroot signature line
  (`npm run marker`), the literal `dataset.fsFit` write (`tools/table-contract.mjs`). Reword one
  and a gate or the build breaks, silently in the Makefile's case.
- **Edit the comment that is there.** Never stack a second one on the first.
- **Formal English.** No exclamation, no addressing the reader.
- **A `#` line inside a quoted `ssh "$R" "…"` string is part of the string.** `sh -n` after the
  edit.

### Where the narrative goes

The measurement that justifies a rule is written once, in `docs/<area>.md`, under a heading the
code can cite: what was seen, what it was, the command that tells the two apart. `docs/anchoring.md`
(the reference) and `docs/anchoring-log.md` (the findings) are those files for `fs-fit.js`. A docs section may be as long as the finding needs; the comment
citing it may not.

### After a bulk comment pass

Prove the code did not move: a token-stream compare against HEAD for every JS file, a
comment-stripped and whitespace-normalised diff for CSS, `.ut`, shell and yaml. That is what caught
a deleted Makefile marker and a lost shell escape. The full-tree compare is T2 (`tools/bg.sh`); the
pass is finished when its output has been read.


## Templates and translation

**`msgid` is a GLOBAL name shared with every `luci-app` on the router.** `load_catalog` merges
*all* `*.<lang>.lmo` into one dictionary and returns the first archive with a matching hash, so
**readdir order decides whose translation wins**. The layout switch rendered "Максимум" on a
Russian router because somebody's catalogue translates `Top` that way — correct in a bandwidth
dialog, nonsense on a layout switch.

- Strings on the Footstrap tab: **use a context** — `_(str, 'footstrap')`.
- Chrome (Menu, Logout, Skip to content), login and warning strings: **deliberately no context**,
  so they inherit luci-base's translation in the ~40 languages the theme has no catalogue for.

Nothing here fails loudly: `_()` without a catalogue is just English text. `npm run i18n` fails
if the `.pot` is stale or any `msgstr` is empty.

**Set the custom property BEFORE the attribute.** Every appearance axis is implemented twice —
inline in `partials/head.ut` before first paint (no module loader exists yet) and live in
`fs-prefs.js` — and the order is load-bearing. Reversed, a reload paints exactly one frame in the
previous hue: a symptom nobody reports and no other test catches. `tools/axes.mjs` derives the
contract from the JS and checks the template against it.

## Package and registration

**One entry in `luci.themes`** — `Footstrap` → `/luci-static/footstrap`. Layout, mode, palette,
tint, accent and rounding are client axes (`localStorage` + attributes on `:root`), not theme
entries and not a server choice. Do not reintroduce `-dark`/`-light` symlink themes or
layout-specific entries.

**A fresh install may activate the theme; an upgrade must never change the active one.** What
tells the two apart is whether the registration was already there: `uci-defaults` writes
`mediaurlbase` only in the run that first added `luci.themes.Footstrap`, which is the idiom the
other themes in the tree use. `$PKG_UPGRADE` is checked as well and carries nothing on its own —
apk never exports it.

**`rpcd reload`, never `restart`.** rpcd holds sessions in memory; a restart logs out every LuCI
user including the admin who just clicked Update. `reload` re-reads `acl.d/*`, which is all this
package needs.

**One asset per package per format in a release.** Nothing on a router picks an asset any more —
the installer takes the feed — but a reader that does gets one candidate, not a guess: GitHub
returns assets **sorted by name**, and in v0.8.4 a `luci-i18n-…` package sorted ahead of
`luci-theme-…`, so the self-update script shipped at the time installed a 6 KB catalogue instead of
the theme,
reported success, and offered the same update forever (issue #6). Code already on somebody's router
cannot be fixed remotely; only the release can. CI fails unless each package resolves to exactly
one asset under its name-anchored regex.

**The translation catalogue lives in `po/`.** That is the directory `LUCI_LANGUAGES` globs, so
luci.mk bakes a `luci-i18n-footstrap-<lang>` package per language exactly as it does for every
luci-app — and it is the only directory Weblate, which CONTRIBUTING names as the way to translate
LuCI, can see. It was `i18n/` while a fielded self-update script resolved the theme by name and took
`head -1` (issue #6); that script is retired and owfeed builds the release as one artifact per
format regardless, so the rename no longer bought anything.

**No runtime dependency beyond `+luci-base`.** `curl` is not in OpenWrt's default set (the base
image ships `uclient-fetch`); fall back, do not depend. `jsonfilter`, `sha256sum` and `usign` are
in the base image.

## The trust chain

`install.sh` installs from the owfeed-packages feed, so **the package manager is what verifies the
bytes**: apk checks the index against `owfeed-packages.pem`, opkg against usign key
`9040356b214084da`, and both keys are pinned in the script itself — it runs from `wget | sh` before
any package of ours exists. The script's own fetch of those keys uses a verified TLS channel:
never `-k` / `--no-check-certificate`, and never as a retry, because a failed verification *is* the
MITM case.

The installer no longer downloads release assets, so it carries no sha256, no `usign -V` and no
`--allow-untrusted`. **The release still signs everything** — a `manifest.txt` plus a detached
`.sig` per asset, both verified in the `release` job — because that is what a by-hand install and
a mirror have to be checked against.

An ed25519 signature is the link that holds and a sha256 alone cannot: GitHub *computes* the asset
digest from the uploaded bytes, so whoever can swap an asset gets the digest recomputed for them.

## Changelog and release

Every substantive commit writes into `## [Unreleased]` **in the same commit as the code** — a
changelog written afterwards is written from the diff, and the diff is exactly what does not know
why. Format, categories and the release runbook: [releasing.md](releasing.md).

## The gates, and what each one holds

| Gate | Holds |
|---|---|
| `lint` | eslint over `htdocs/` and `ucode/`, stylelint over `styles/` — correctness only, not formatting |
| `audit` | `audit.py --strict`: undefined `var()`, shadowed declarations, export-tier reads, dead base declarations, stray `!important`, colour literals |
| `css-metrics` | ratchet: `!important` ≤ 27, max specificity `[1,7,0]`, 0 empty rules |
| `css-orphans` | dead `fs-*` selectors — it **gates** the forward direction (styled, emitted by nothing) and **reports** the reverse, where an unstyled class is often legitimate (a JS hook, an element riding on inherited styles). A new name in the reverse list wants a look or a line in `JUSTIFIED_UNSTYLED`; it does not fail the build |
| `acl` | every shipped `acl.d/*.json` parses **and** grants something — rpcd skips an unreadable file silently |
| `css-dup` | identical declaration bodies under different guards |
| `tables` | the table contract: where a cell may break (one allowlist, no viewport queries), the floor holds when a data table is squeezed, a carded cell prints its caption, and no `.cbi-dropdown` sits inside a scroll container |
| `mirror` | `@mirror`-pinned copies still byte-identical |
| `bang-ok` | every `!important` sits in an allowlisted file |
| `axes` | the pre-paint in `head.ut` agrees with the live appearance appliers, and `header.ut` reads every saved option back |
| `scroll-anchor` (live) | grows something above the reader and asserts the page does not move under them — twice, once with the engine's own scroll anchoring suppressed (the Safari path, forced on any engine with `localStorage.fsEngineAnchor='off'`) and once without, so a fallback that also runs where the engine already corrects is caught as well. Plus a scripted flick up and down: the theme may not correct WHILE the reader moves. Three page shapes (section bodies, a polled table's rows, a bare table under `#view`) across the two scrollers a layout and a width can produce; `--full` adds the axes measured not to change the answer, which is what CI crosses on a push |
| `table-tick` (live) | performs a poll tick on purpose — rows out, rows back in, marks stripped, then a forced layout — and fails if the replaced table was laid out before anything answered for it. The intermediate lasts a microtask, so no sampler can see it: with the stylesheet's gate removed this reports 613px on Обзор@390 and 817px on Processes, and nothing with it in place |
| `floor-contract` (live) | the poll floor: every `data-fs-floor` box is stripped and re-measured with `offsetHeight`, and the two must agree within 4px; a tab switch must leave no floor on the pane the reader left; and the tallest floor on the page is emptied and must be given back — judged against what the EMPTY box stands at, since a box with no children still has its padding (34px on /admin/network/network either way). All three faults shipped and none is visible in a file or on a page that is only loaded: 41px short on `.cbi-section-descr` (/admin/network/dhcp), 2432px left on `Initscripts` after a tab switch, 927px never taken off on Network → Interfaces. A box the poll refilled or replaced is not judged |
| `fit-quiet` (live) | the bar may not get shorter while it measures itself. `fitChrome()` strips the layout classes to ask whether the menu fits a row, and the bar is above the reader on every page: 33px of dip at 767px, 8px at 480px, which an engine with no scroll anchoring lays the page out against. The gate gives the bar a `classList` of its own and reads the height back at the instant the classes come off — the symptom does not reproduce headless, so the cause is what is watched |
| `page-modules` | the `data-page` → module map in `menu-footstrap-common.js` names the same page each mapped module tests for itself, every mapped module exports the `wire()` the loader calls, and no `'require'` pragma is left for one anywhere — one pragma puts the file back on every page and takes the saving with it |
| `chrome-fence` | the `[data-fs-chrome]` marker, fence and pin still match the chrome |
| `export-tier` | the `--*-color-*` contract: each level readable as text on three surfaces, each `--on-*` readable on its fill, and the ramp is not flat — measured with and without `prefers-contrast: more`, which re-states the inks |
| `css-i18n` | translatable strings emitted from CSS |
| `conffiles` | every shipped `/etc/config/*` is declared a conffile — `/etc/config/footstrap` is written at runtime by Save-as-default, and an undeclared one is replaced on upgrade |
| `changelog` | section set, order, dates, compare links, RU mirror parity, bold leads |
| `i18n` | `.pot` current, no empty `msgstr` |
| `shell` | every shell script in the source tree parses (`sh -n`) — including `release-notes.sh`, which otherwise fails inside the release job |
| `marker` | the `call BuildPackage` literal `include/scan.mk` greps for, without which the SDK does not see the package at all |
| `a11y` | axe-core WCAG 2.2 AA over `docs/gallery.html`, {light,dark} × {footstrap,hicontrast,bootstrap,2020,forum} × {untinted,60°,260°} |
| `placeholder-ink` | a hint may not read as a value the reader typed: every `placeholder` attribute and every `li[placeholder]` row on `docs/gallery.html`, across all eight palette/mode combinations, must have travelled ≥40% of the way from the field's own ink to its fill in light and ≥30% in dark (oklab lightness), and still measure 3:1 on that fill — SC 1.4.11, not AA's 4.5, which is the decision the token records: a dark palette has 6.45:1 of ink to spend against light's 14.84:1, and a hint that clears AA has not moved far enough to stop reading as a value. Every combination runs again under `prefers-contrast: more`, where the query hands the AA ink back and the thresholds swap (≥15%, 4.5:1). `a11y` is excluded from `li[placeholder]` for the same decision — axe measures that row as text and skips the attribute carrying the same ink. axe-core skips `::placeholder` entirely and the old ink was legal by every threshold the theme had — 11.12:1 on footstrap light, against the value's 14.84:1. It also caught a colour rule that had never applied: `li[placeholder]` (0,2,2) lost to the menu row's own `color` (0,3,2) |
| `test` | the unit suite (`node --test`, no browser): the shipped module is evaluated inside the same wrapper luci.js uses, and its pure logic is driven directly. For the cases a stand **cannot** produce — a luci-base with a surface missing, an alias loop in a foreign `menu.d`, a `firstchild` tie — not as a second opinion on what the stands already cover |
| `size` | ceiling on what the router SENDS, pinned once per release by `/release` (`--pin`, measured + 2 %) and never raised between releases: `cascade.css` after `build-css.sh` + the token mangle, and the shipped JS after terser — the package build's own asset half, reproduced. uhttpd serves `/www` uncompressed, so these are wire bytes |
| `icons` | the committed app-icon rasters still match `logo.svg` (per channel, with a tolerance) and still hold the maskable invariants — they are generated by `tools/build-icons.mjs` and cannot be rebuilt on the buildbot |

## The live gates, and why a file cannot answer for a page

`npm run live` — three gates that need a **running owlab router**, which is why they are not in
`npm run check`. Every gate above measures a file; every bug users have reported was about a page:
#11 a column shredded to one character per line, #22 a clipped submenu title, #14 an indicator that
did not fit, #10 phantom scroll from a hidden pane, #12 a doubled scrollbar in one engine, #8/#33/#36
a third-party app laid out wrong, and — reported on the upstream PR — two pages that came back empty
after a client navigation while every static gate stayed green.

| Gate | Holds |
|---|---|
| `upstream` | the coupling registry: every assumption fs-*.js makes about luci-base (`L.Poll`'s alias and queue, `uci.state.values`/`loaded`, `uci.load()` answering "what did THIS call fetch", `network.js` loading its three packages exactly once, `require()` publishing onto `L`, the modal contract, where `addNotification` puts a banner, an open dropdown being `position: absolute`) checked against the luci-base the router runs. Each failure names the module here that was written against it |
| `spa-parity` | every menu page opened BOTH ways — by click and by full load — compared on content, on uci's cache, on `network.getWifiDevices()` and on console errors. No baseline: a difference is always a bug |
| `install-check` | `install.sh` run twice on a stand — fresh, then over its own result — asserting the package is installed, `luci.main.mediaurlbase` points here and `cascade.css` is on disk. Three field reports (#16, #28, #30) were this script alone, all on the second-run path. It leaves the PUBLISHED release installed and re-syncs the working tree afterwards, so it runs last |
| `scroll-jank` | scrolls with a real wheel, long enough that a poll tick lands inside it, in BOTH layouts (they scroll different elements) and on every engine asked for: a table may not re-decide its remedy while the page moves, an element's document position may not change under the reader, and Chromium's layout-shift score for the window must stay under 0.02. The pass the theme defers to the stop is reported in a phase of its own, never failed. Chromium by default; `--engines chromium,firefox,webkit` needs the other two installed |
| `live-audit` | every menu page at 320/390/568/768/1024/1440, each resized into AND one (768 by default) ENTERED with a load of its own — a fault that only exists on arrival is invisible to a resize, which is how a table 65px past its column reached a user; the arrival records only what the resize at that width did not, because a fault both passes see is one fault: sideways document scroll, an element past the content column with no scroller, a clipped non-scrolling box, a sub-24px hit target with a neighbour, an operable element with no name, two stacked scrollports, a JS error. Ratcheted against `tools/baselines/live-audit.json` — a NEW signature fails, and `--update` (read the diff first) rewrites it. That file is a **union across platforms**: a handful of findings sit within a pixel of their threshold and text metrics differ between a maintainer's containers and CI's runner, so six signatures first appeared in CI |

`--engine firefox` and `--engine webkit` run the audit in the other two engines, keyed separately in
the baseline: #12 was Firefox-only, and a chromium run must not bless a finding it never saw.

Two more run in CI only. `tools/jsmin-verify.mjs` needs a jsmin built from the commit in
`luci-upstream.pin`. `ucode -T -c` over every template runs inside the `verify` containers, against
the installed theme with the router's own interpreter — which is also how you run it locally
(`owlab exec … ucode -T -c`), so nothing here has to build one.