affora 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 — 2026-09-24
+
+Initial public release.
+
+- Copy-in CLI with listing, dependency resolution, dry runs, collision safety,
+  custom destinations, and complete-registry installation.
+- Two native primitives: Action button and Text field.
+- Five compositions: Combobox, Dialog, Product card, Data table, and Settings
+  form.
+- Five flow patterns: Gated action, Error remedy, Confirm and undo, Flow form,
+  and Persistent feedback.
+- Sixteen token themes, executable substrate checks, and rewrite rules for
+  common component libraries.
+- Human-facing `design.md` and coding-agent-facing `agent.md` contracts.

package/CHECKS.md

@@ -0,0 +1,40 @@
+# The eight component checks
+
+Each check is a predicate over a rendered component. Each returns a verdict and
+the evidence it read, and each has an input that must fail it.
+
+| # | check | how it is decided |
+|---|---|---|
+| S1 | every interactive element is a real control or carries a role | every element that behaves as a control is an element with a role |
+| S2 | every control has a non-empty accessible name | name computation over each control |
+| S3 | every task-relevant fact is present as text | the task's facts occur in the rendered text |
+| S4 | selection or expansion state is exposed semantically | state is on the element, not in a class |
+| S5 | options are enumerable without interacting | the action space at rest holds at least the task's options, counting a native select, an ARIA listbox, and a radio or checkbox group |
+| S6 | the operable target coincides with the visible one | no control is sized to zero or transparent behind a proxy, and a hit test at the visible centre lands inside |
+| S7 | the committed value is readable back as text | after a commit, the value occurs in the rendered text |
+| S8 | meaning never rests on colour or position alone | no element is distinguished by appearance alone |
+
+Three verdicts, not two: a check that cannot be decided from what it was given
+returns **undecided**. S3, S5 and S7 need the task's facts, and given none they
+say so rather than passing.
+
+## Running them
+
+```bash
+node checks/cli.mjs <url> [selector] [fact,fact,...]
+```
+
+For example, against the demo:
+
+```bash
+npm run demo &
+node checks/cli.mjs http://localhost:5280/ "section:nth-of-type(1)" "Small,Medium,Large"
+```
+
+## The three page checks
+
+A rewrite of a page you did not author has to be checked in the other direction
+as well: it must not destroy what was there. C1 asks whether the page still says
+everything it said; C2 whether it still has every affordance; C3 whether using a
+control still causes the same effect outside the page. Two defects in the rules
+under `rules/` were found by C2 and C3 and one from an anomalous success rate.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Affora authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# Affora
+
+A component library for interfaces with two readers: a person, and an agent that
+operates the page by reading it.
+
+Affora is not a runtime. It is source you copy into your own repository, the way
+`shadcn/ui` is, plus a token vocabulary you own and a compliance test you can run
+in CI. One rule holds it together, at three scales:
+
+> **What an interface declares is fixed and checked. What it paints is free.**
+
+At component scale that reads *substrate invariant, skin variable*: a component
+is authored once, and every visual decision is a token.
+
+## What is here
+
+```
+src/primitives/   native actions and fields with names, constraints, and state
+src/components/   five compositions, authored once, every visual value a token
+src/patterns/     flow-pattern sources; publishable patterns are listed by the CLI
+src/tokens/       45 style tokens and 7 layout tokens, and 16 themes that set them
+checks/           the eight component checks, as a command
+rules/            rewrite rules that repair a page you did not author
+demo/             every component under every theme, in a browser
+design.md         the human-facing substrate and skin contract
+agent.md          the operating contract a coding agent reads before editing
+```
+
+## Using a component
+
+Use the copy-in CLI. A component has no Affora import and no runtime dependency
+beyond React; its token dependency is copied with it:
+
+```bash
+npx affora add product-card
+```
+
+This writes `src/components/affora/product-card.tsx` and
+`src/styles/affora/themes.css`. Run `npx affora list` to see the registry, use
+`--path <directory>` to choose another root, and use `--dry-run` to inspect a
+copy plan. Run `npx affora add --all` to install the complete registry. The CLI
+refuses to overwrite files unless you pass `--force`.
+
+Requires Node.js 18 or later. Copied React components support React 18 and later.
+
+Then set a theme by attribute, and the component follows:
+
+```html
+<html data-flagship="swiss" data-layout="saas">
+```
+
+A theme may redefine all 45 style tokens and all 7 layout tokens. It may not
+reach the component's markup, which is the point: the reader that enumerates
+sees the same document under every theme.
+
+## Running the checks
+
+The eight component checks (S1–S8) decide, from the rendered document, whether a
+component is legible to a reader that enumerates an action space:
+
+```bash
+npm run check -- https://example.test '#checkout' 'Cart total,Place order'
+```
+
+Arguments are the page URL, an optional component selector, and an optional
+comma-separated list of task-relevant facts. The runner launches Chromium and
+prints every verdict with the evidence it read.
+
+Each check reports a verdict and the evidence it read. A check that cannot be
+decided from what it was given returns *undecided* rather than *pass*. The CLI
+exits non-zero when a check fails; callers that require full conformance should
+also treat an *undecided* result as missing evidence.
+
+**What passing means.** The document contains, for every component on the page, a
+real control, an accessible name, state exposed as state, options enumerable
+without interacting, and an operable target where it visibly sits. That is a
+property of the artefact, decided without running a model. It is not a
+prediction that an agent will succeed: failures also come from transient
+feedback, portalled menus and flow state, which a component-scoped check does not
+see. Treat it the way you treat a type checker.
+
+## Repairing a page you did not author
+
+`rules/` holds the rewrite rules used in the paper's evaluation. They detect
+common library idioms — a combobox whose options mount only when open, an
+icon-only control, a radio group hidden by CSS behind styled labels — and
+re-express them so the options and names are in the document.
+
+The rule files are browser-evaluated rule objects consumed by Affora's rewrite
+harness; they are shipped as auditable source, not presented as a standalone
+command. A consumer must run the generic rules first, then the matching library
+adapter, and apply the page gates below around every rewrite.
+
+A rewrite can damage a page it did not author. Before measuring anything, run the
+three page gates: the page must still **say** everything (C1), still **have**
+every affordance (C2), and using it must still **cause** the same effect (C3).
+Two defects in these rules were found that way and one from an anomalous success
+rate; all three are described in the paper.
+
+## Licence
+
+MIT.
+
+## Reproducing the paper's figures from this library
+
+The five components here are the ones the paper measures, byte for byte, and the
+sixteen themes are the ones its theme axis varies. `npm run demo` renders every
+component under every theme and layout, with the committed value shown beside the
+controls, which is the probe every episode in the paper reads.
+
+## What is not here
+
+The measurement harness, the task sets and the episode traces are not part of the
+library; they are research code and they are described in the paper. What ships
+here is what a team would adopt: the components, the tokens, the patterns, the
+checks and the rewrite rules.

package/agent.md

@@ -0,0 +1,70 @@
+# Affora operating contract for coding agents
+
+Read this file before changing an interface that uses Affora.
+
+## Goal
+
+Preserve one semantic document for two readers: a person who sees the rendered
+page and an agent that enumerates its controls, names, relationships, and state.
+Visual design is free to change; the task-relevant substrate is not.
+
+## Required behaviour
+
+- Use native HTML controls before simulated controls.
+- Give every interactive element a stable accessible name. Prefer visible text.
+- Keep task-relevant options and facts in the DOM without requiring interaction.
+- Express selected, current, expanded, invalid, busy, and completed state with
+  native state, ARIA where appropriate, and persistent text when the fact matters
+  to the task.
+- State constraints before submission. A disabled action must name its blocker
+  and the action or control that removes it.
+- Keep action results and errors readable. An error states what failed, why, and
+  the named corrective action. Do not make a transient toast the only record.
+- Make every step self-describing. Restate facts and named progress needed after
+  navigation or context loss.
+- Keep visible and operable targets coincident. Do not place a tiny hidden input
+  behind a larger visual control unless the actual hit target covers that control.
+- Mark destructive consequences in text. Prefer undo for reversible operations.
+- Preserve semantic element order and relationships across themes and layouts.
+
+## Vocabulary
+
+- **primitive**: one native interaction
+- **composition**: primitives expressing one object
+- **flow pattern**: state and actions across time
+- **substrate**: semantic document and task-relevant state
+- **skin**: tokens, layout, typography, colour, motion, and effects
+
+Do not introduce alternate layer names or unexplained check identifiers into
+user-facing documentation.
+
+## Adding a registry component
+
+1. Add one self-contained React source file under `src/primitives/`,
+   `src/components/`, or `src/patterns/`.
+2. Depend only on React and Affora tokens. Do not import experiment shims or use
+   the `@/` alias.
+3. Export the component and its token-only CSS. Do not bake a theme into it.
+4. Add the item to `registry.json`; declare `themes` in `requires`.
+5. Add or update CLI tests when dependency or destination behaviour changes.
+6. Run `npm test`, then install the output of `npm pack` into a temporary project
+   and execute the installed `affora` binary.
+
+Never add a file to the registry while it imports control-condition shims,
+experiment types, or a transient-feedback dependency. Registry items are
+standalone reference implementations.
+
+## Safe changes
+
+Safe changes alter tokens, styling, or composition without changing controls,
+names, option presence, state exposure, or effects. A refactor is not safe merely
+because the pixels are unchanged.
+
+For any substrate change, compare before and after and answer:
+
+1. Does the page still say every relevant fact and state?
+2. Does it still have every named affordance?
+3. Does each affordance still cause the same effect?
+
+Run the executable checks after answering those questions. Treat `undecided` as
+missing evidence, not a pass.

package/checks/cli.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Run the eight component checks against a page.
+//
+//   node checks/cli.mjs <url> [selector] [fact,fact,...]
+//
+// The selector picks the component to check; it defaults to the whole document
+// body. Every verdict carries the evidence the check read, and a check that
+// cannot be decided from what it was given says so rather than passing.
+import { RUN } from "./substrate.mjs"
+
+// Two checks — every task-relevant fact present as text, and options
+// enumerable — need to know which facts the task depends on. Given none they
+// return undecided rather than pass, which is the point of the third verdict.
+const [url, selector = "body", factsArg = ""] = process.argv.slice(2)
+const facts = factsArg ? factsArg.split(",").map((f) => f.trim()).filter(Boolean) : []
+if (!url) {
+  console.error("usage: node checks/cli.mjs <url> [selector] [fact,fact,...]")
+  process.exit(2)
+}
+const { chromium } = await import("playwright")
+const browser = await chromium.launch()
+const page = await browser.newPage({ viewport: { width: 1280, height: 900 } })
+await page.goto(url, { waitUntil: "networkidle" })
+await page.waitForTimeout(1200)
+
+// RUN addresses its subject through a data attribute, so the page under test is
+// marked once rather than the predicate being rewritten per host.
+await page.evaluate((sel) => {
+  const el = document.querySelector(sel) || document.body
+  el.setAttribute("data-component", "subject")
+}, selector)
+
+const results = await page.evaluate(RUN, { comp: "subject", facts, expected: null, arm: "subject" })
+await browser.close()
+
+let failed = 0
+for (const r of results) {
+  const verdict = r.pass === true ? "pass" : r.pass === false ? "FAIL" : "undecided"
+  if (r.pass === false) failed += 1
+  console.log(`${r.id}  ${verdict.padEnd(9)} ${r.label}`)
+  if (r.evidence) console.log(`    ${String(r.evidence).replace(/\s+/g, " ").slice(0, 96)}`)
+}
+console.log(`\n${results.filter((r) => r.pass === true).length}/${results.length} pass, ${failed} fail`)
+process.exit(failed ? 1 : 0)

package/checks/substrate.mjs

@@ -0,0 +1,269 @@
+// The substrate checklist, S1-S8, as executable predicates.
+//
+// Extracted from the figure script so the checker is an artifact rather than
+// figure-generation code. The paper claims Affora's component checks are
+// executed rather than judged — that expert disagreement, which Brajnik et al.
+// measure for WCAG conformance, is not a variable for this layer because no
+// human adjudicates it. A claim like that has to be a module somebody can
+// import and run, not a paragraph.
+//
+// RUN is passed to page.evaluate(), so it must be self-contained: no imports,
+// no closure over module scope. It takes the component id, the task's facts and
+// its expected value, and returns one record per check carrying a verdict AND
+// the evidence the check read. A check that reports only a verdict cannot be
+// argued with; one that reports what it saw can.
+//
+// Scope, stated because the paper states it: these are the COMPONENT-level
+// checks. The flow checklist (L1-L8) needs a task path rather than a screen and
+// the site checklist (K1-K3) needs several routes; neither is here.
+
+// Each check is a predicate over the rendered component plus the task's own
+// facts, and each returns the evidence it read.
+export const RUN = ({ comp, facts, expected, arm }) => {
+  const cell = document.querySelector(`[data-component="${comp}"]`)
+  const SEL = "a,button,input,select,textarea,summary,[role]"
+  const vis = (e) => {
+    const r = e.getBoundingClientRect(), cs = getComputedStyle(e)
+    return r.width > 0 && r.height > 0 && cs.visibility !== "hidden" && cs.display !== "none"
+  }
+  const raw = [...cell.querySelectorAll(SEL)]
+  const els = raw.filter(vis)
+
+  // S6 has to look at the elements the visibility filter throws away, because
+  // the defect it names IS invisibility: a real control sized to zero or made
+  // transparent behind a styled proxy. Filtering first made the check blind to
+  // its only subject — the falsification case returned "no operable target"
+  // instead of failing.
+  const hidden = raw.filter((e) => {
+    if (vis(e)) return false
+    if (e.disabled || e.getAttribute("aria-hidden") === "true") return false
+    const r = e.getBoundingClientRect(), cs = getComputedStyle(e)
+    return cs.display !== "none" && (r.width < 2 || r.height < 2 || Number(cs.opacity) === 0)
+  })
+  const NATIVE = ["A", "BUTTON", "INPUT", "SELECT", "TEXTAREA", "SUMMARY", "OPTION"]
+  const nameOf = (e) => (e.getAttribute("aria-label") || e.textContent || e.getAttribute("placeholder") || e.value || "").trim().replace(/\s+/g, " ")
+  // A component with no real control at all is the strongest S1 failure there
+  // is, and the checker used to throw on it: els[0] was undefined and every
+  // check dereferenced it. Four components in our own corpus hit this, so the
+  // instrument was silently unable to score its worst cases.
+  if (els.length === 0 && hidden.length) {
+    // real controls exist and none of them is visible: that is S6's defect in
+    // its purest form, not an absence of controls
+    const R1 = (id, label, pass, evidence, wcag) => ({ id, label, pass, evidence, wcag })
+    return [
+      R1("S1", "every interactive element is a real control or carries a role", true,
+         `${hidden.length} real control(s) present`, "4.1.2"),
+      R1("S2", "every control has a non-empty accessible name", null, "no visible control to name", "4.1.2"),
+      R1("S3", "every task-relevant fact is present as text", null, "no visible control to scope to", null),
+      R1("S4", "selection or expansion state is exposed semantically", null, "no visible control", "4.1.2"),
+      R1("S5", "options are enumerable without interacting", null, "no visible control", null),
+      R1("S6", "the operable target coincides with the visible one", false,
+         `${hidden.length} operable control(s) sized to zero or transparent`, null),
+      R1("S7", "the committed value is readable back as text", null, "no visible control", null),
+      R1("S8", "meaning never rests on colour or position alone", null, "no visible control", "1.4.1"),
+    ]
+  }
+  if (els.length === 0) {
+    const R0 = (id, label, pass, evidence, wcag) => ({ id, label, pass, evidence, wcag })
+    return [
+      R0("S1", "every interactive element is a real control or carries a role", false,
+         "no real control and no role in the component", "4.1.2"),
+      R0("S2", "every control has a non-empty accessible name", null, "no control to name", "4.1.2"),
+      R0("S3", "every task-relevant fact is present as text", null, "no control to scope the text to", null),
+      R0("S4", "selection or expansion state is exposed semantically", null, "no control to carry state", "4.1.2"),
+      R0("S5", "options are enumerable without interacting", null, "no control to enumerate from", null),
+      R0("S6", "the operable target coincides with the visible one", null, "no operable target", null),
+      R0("S7", "the committed value is readable back as text", null, "no control to commit", null),
+      R0("S8", "meaning never rests on colour or position alone", null, "no control to judge", "1.4.1"),
+    ]
+  }
+  const ctl = els[0]
+  // Everything a reader can choose from without opening anything: a native
+  // select's options, an ARIA listbox's options, and a native radio or checkbox
+  // group, which is the form this system prescribes and which this check did
+  // not count — it failed the library's own compliant product card, whose sizes
+  // are three labelled radios.
+  const groupLabel = (e) => {
+    const byFor = e.id && cell.querySelector(`label[for="${CSS.escape(e.id)}"]`)
+    const wrap = e.closest("label")
+    return ((byFor && byFor.textContent) || (wrap && wrap.textContent) ||
+            e.getAttribute("aria-label") || e.value || "").replace(/\s+/g, " ").trim()
+  }
+  const options = [
+    ...[...cell.querySelectorAll("select")].flatMap((s) => [...s.options].map((o) => (o.label || "").trim())),
+    ...[...cell.querySelectorAll("[role=option]")].map((o) => o.textContent.trim()),
+    ...[...cell.querySelectorAll('input[type="radio"], input[type="checkbox"]')].map(groupLabel),
+  ].filter((o) => o && o !== "Select a country")
+  // The component's own text, and all of it.
+  //
+  // This was scoped to the control's field wrapper, to keep the gallery's arm
+  // label and harness probe out of the figure's evidence strings. That is the
+  // wrong scope for S7, which asks whether a committed value is readable back
+  // as DOCUMENT text: a value echoed in a sibling paragraph is readable, and
+  // the field-scoped version called it missing. Falsifying S7 is what surfaced
+  // it — the case built to make the check PASS failed instead.
+  //
+  // So the scope is the whole component minus the harness's own instrumentation:
+  // the `output[data-expected]` probe the runner reads, and the arm-label header
+  // the gallery draws. Both are ours, neither is the component.
+  // Walked in place rather than cloned: innerText needs layout, and a detached
+  // clone silently falls back to textContent, which runs block elements together
+  // ("CountrySelect a country") and made the figure's evidence look mangled.
+  const isChrome = (el) =>
+    el.matches?.("output[data-expected]") ||
+    (arm && (el.textContent || "").trim().toUpperCase().startsWith(arm.toUpperCase()))
+  const text = [...cell.children]
+    .filter((el) => !isChrome(el))
+    .map((el) => el.innerText || "")
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim()
+
+  const box = ctl.getBoundingClientRect()
+  // the element the browser would actually deliver a click on the control to
+  const hit = document.elementFromPoint(box.left + box.width / 2, box.top + box.height / 2)
+  // control kinds that HAVE a state a reader could need: everything else has
+  // nothing for S4 to ask about
+  const STATEFUL_ROLES = ["checkbox", "radio", "switch", "tab", "option", "slider",
+                          "combobox", "menuitemcheckbox", "menuitemradio", "treeitem", "spinbutton"]
+  const stateful = els.filter((e) =>
+    e.tagName === "SELECT" || e.tagName === "SUMMARY" ||
+    (e.tagName === "INPUT" && ["checkbox", "radio", "range"].includes(e.type)) ||
+    STATEFUL_ROLES.includes(e.getAttribute("role") || "") ||
+    e.hasAttribute("aria-expanded") || e.hasAttribute("aria-checked") ||
+    e.hasAttribute("aria-selected") || e.hasAttribute("aria-pressed"))
+  const hits = ctl.contains(hit) || hit === ctl || ctl.contains(hit?.parentElement)
+  const stateAttr = ["aria-expanded", "aria-checked", "aria-selected", "aria-valuenow", "aria-pressed"]
+    .find((a) => els.some((e) => e.hasAttribute(a)))
+  const stateEl = els.find((e) => stateAttr && e.hasAttribute(stateAttr))
+
+  // pass is true, false, or null for "this check cannot be decided from what it
+  // was given". Null is NOT a pass. Two checks need to know which facts the task
+  // involves, and called with an empty fact list they were vacuously true —
+  // `facts.every(...)` on nothing, `options.length >= 0` — so the standalone
+  // checker reported a clean bill of health for a component it had not examined.
+  // A gate that cannot fail is not a gate; this is the shape that failure takes
+  // in a checklist rather than in a benchmark.
+  // the value a control is currently holding, if any — what S7 looks for
+  const heldBy = (e) => {
+    if (e.tagName === "SELECT") { const o = e.selectedOptions[0]; return o && o.value ? (o.label || o.textContent || "").trim() : null }
+    if (e.tagName === "INPUT" && ["checkbox", "radio"].includes(e.type)) return e.checked ? (e.value || "on") : null
+    if (e.tagName === "INPUT" || e.tagName === "TEXTAREA") return e.value ? String(e.value).trim() : null
+    const sel = e.getAttribute("aria-checked") === "true" || e.getAttribute("aria-selected") === "true"
+    if (sel) return (e.textContent || "").trim() || null
+    const now = e.getAttribute("aria-valuenow")
+    return now != null ? String(now) : null
+  }
+  const held = els.map(heldBy).find((v) => v) ?? null
+
+  // elements distinguished by appearance with nothing a reader could read
+  const colourOnly = [...cell.querySelectorAll("span,div,i,b")].filter((e) => {
+    const r = e.getBoundingClientRect()
+    if (r.width <= 0 || r.height <= 0 || r.width > 64 || r.height > 64) return false
+    if (e.children.length) return false
+    if ((e.textContent || "").trim()) return false
+    if (e.getAttribute("aria-label") || e.getAttribute("title") || e.getAttribute("role")) return false
+    if (e.getAttribute("aria-hidden") === "true") return false
+    const cs = getComputedStyle(e)
+    const painted = (cs.backgroundColor && cs.backgroundColor !== "rgba(0, 0, 0, 0)") ||
+                    (cs.borderTopWidth !== "0px" && cs.borderTopStyle !== "none")
+    return painted
+  }).map((e) => `${e.tagName.toLowerCase()}.${(e.className || "").toString().split(" ")[0] || "-"}`)
+
+  const R = (id, label, pass, evidence, wcag) => ({ id, label, pass, evidence, wcag })
+  const needsFacts = facts.length === 0
+  return [
+    R("S1", "every interactive element is a real control or carries a role",
+      els.every((e) => NATIVE.includes(e.tagName) || e.getAttribute("role")),
+      `${ctl.tagName.toLowerCase()}${ctl.getAttribute("role") ? `[role=${ctl.getAttribute("role")}]` : ""}`,
+      "4.1.2"),
+    R("S2", "every control has a non-empty accessible name",
+      els.every((e) => nameOf(e)), `"${nameOf(ctl)}"`, "4.1.2"),
+    R("S3", "every task-relevant fact is present as text",
+      needsFacts ? null : facts.every((f) => text.includes(f)),
+      `rendered text: "${text.length > 46 ? text.slice(0, 46) + "\u2026" : text}"`,
+      // Not 1.3.1. That criterion governs how PRESENTED content is marked up so
+      // its structure is programmatically determinable; a collapsed control
+      // presents no options, so it does not engage the criterion at all. Mapping
+      // this row to 1.3.1 would have overstated what conformance asks for.
+      null),
+    // S4 asks whether state is exposed, and asked it of components that have no
+    // state to expose: run over 120 corpus cells it failed 55 of 60 native ones,
+    // because a plain button carries no aria-expanded and is not a select. A
+    // check that fires on components it does not apply to is a false-positive
+    // machine, and its correlation with success was partly noise. It is scoped
+    // to components that contain a stateful control kind; where none does, the
+    // check is undecidable rather than failing.
+    R("S4", "selection or expansion state is exposed semantically",
+      stateful.length === 0 ? null
+        : (Boolean(stateAttr) || stateful.some((e) =>
+            e.tagName === "SELECT" || e.tagName === "SUMMARY" ||
+            (e.tagName === "INPUT" && ["checkbox", "radio", "range"].includes(e.type)))),
+      stateful.length === 0 ? "no stateful control in this component"
+        : (!stateAttr && stateful.some((e) => ["SELECT", "SUMMARY", "INPUT"].includes(e.tagName)))
+          ? `${stateful[0].tagName.toLowerCase()} carries its state natively`
+        : stateAttr ? `${stateEl.tagName.toLowerCase()} ${stateAttr}="${stateEl.getAttribute(stateAttr)}"`
+                    : `${ctl.tagName.toLowerCase()} carries its own value`,
+      "4.1.2"),
+    R("S5", "options are enumerable without interacting",
+      needsFacts ? null : options.length >= facts.length,
+      needsFacts ? "needs the task's facts to decide"
+                 : options.length ? `action space: ${options.slice(0, 3).join(", ")}${options.length > 3 ? `, +${options.length - 3}` : ""}`
+                                  : "action space: the trigger only",
+      null),
+    R("S6", "the operable target coincides with the visible one",
+      hidden.length === 0 && hits,
+      // The evidence has to say WHICH condition decided it. This printed
+      // "hit test lands inside" on cells it had just marked failing, because the
+      // string was chosen by hidden.length alone — so a hit-test miss was
+      // reported with the words for a pass, and reading the corpus output nearly
+      // turned two of those into a claim about zero-sized controls.
+      hidden.length
+        ? `${hidden.length} operable control(s) sized to zero or transparent`
+        : hits
+          ? `${Math.round(box.width)}×${Math.round(box.height)} px, hit test lands inside`
+          : `${Math.round(box.width)}×${Math.round(box.height)} px, but the point at its centre belongs to <${(hit?.tagName || "nothing").toLowerCase()}>`,
+      null),
+    // S7 and S8 were both hardcoded `true` — literally `R("S7", ..., true, ...)`.
+    // They were written while building the figure, where both arms pass, so two
+    // constants sat in the middle of a checklist looking like checks. Run over
+    // 120 corpus cells neither ever fired, which is how they were caught. A gate
+    // that cannot fail is not a gate, and this project keeps relearning it.
+    //
+    // S7 now asks the question it names: does a value a control is holding
+    // appear in the component's rendered text? Undecidable when no control holds
+    // one yet, because a static snapshot of an untouched component has no
+    // committed value to look for.
+    // The failure this names is a value that lives in a control's `value`
+    // property and nowhere in the document — the case that moved a memoryless
+    // arm from 0% to 33% once the extractor was taught to read it. So the
+    // question is whether the committed value is in the rendered TEXT. It needs
+    // a value to have been committed: given one (the caller drives the
+    // component first) it is decidable, and a static snapshot of an untouched
+    // component honestly cannot decide it.
+    R("S7", "the committed value is readable back as text",
+      expected ? text.includes(expected) : (held === null ? null : text.includes(held)),
+      expected
+        ? `committed "${expected}"; rendered text ${text.includes(expected) ? "contains" : "does NOT contain"} it`
+        : held === null
+          ? "no value has been committed in this state"
+          : `control holds "${held}"; rendered text ${text.includes(held) ? "contains" : "does NOT contain"} it`,
+      null),
+    // S8's mechanical proxy: an element that is visually distinguished and
+    // carries no text, no accessible name and no ARIA state is conveying
+    // whatever it conveys by appearance alone. This is a proxy and not the
+    // principle — the principle needs judgement, which COMPLIANCE.md now says
+    // rather than claiming every line is mechanically decidable.
+    R("S8", "meaning never rests on colour or position alone",
+      colourOnly.length === 0,
+      colourOnly.length ? `${colourOnly.length} element(s) distinguished only by appearance: ${colourOnly.slice(0, 2).join(", ")}`
+                        : "no element is distinguished by appearance alone",
+      "1.4.1"),
+  ]
+}
+
+// Runnable on its own, so the checklist is something a team can point at a
+// component rather than something they read about:
+//
+// The library ships this predicate; checks/cli.mjs is the executable entry
+// point that runs it against a page and prints each verdict with its evidence.