diff --git a/VISION.md b/VISION.md index 9e88f13..c3325dc 100644 --- a/VISION.md +++ b/VISION.md @@ -583,6 +583,18 @@ All nine slices are merged and the acceptance re-run passed. The phase is closed _Full spec-driven breakdown in [`docs/specs/PHASE-31-SPEC.md`](docs/specs/PHASE-31-SPEC.md). Deliberately out of scope: porting the viewer's code, anchored overlay rendering, keyboard behaviour, narrow-window collapse, the command palette and bulk-selection variants, importer work, and desktop-app rules on web._ +### Phase 32 — Follow-ups (v2.5) + +Phases 30 and 31 closed with seven follow-ups open, and five of them are quiet false passes: evaluate says READY on a disabled button that renders undimmed inside a component, on a misspelt `$token` the renderer drops, on a `select` border at 1.46:1, and on a phone screen whose links, text inputs and dialogs are never measured. Reproducing them found more: contrast and spacing never look inside a component instance at all, and seeded dark tints and `danger` survive a light preset. This phase clears every follow-up, and first moves the 140 root-level tests into folders that set their tier, so the fixes land in the new layout. + +- [ ] Slice A — tests in folders: `test/unit`, `test/browser`, `test/e2e` and `test/manual` set the tier, a Chrome guard on `test/unit` proves it at run time, tests are type-checked under `strict`, and files are named by subject, not phase or issue +- [ ] Slice B — one tree: instances expanded and resolved once, so the renderer and every rule (contrast, spacing and cliché included) see the same thing inside a component, and findings there name the instance +- [ ] Slice C — tokens: an `unknown-token` warning for any `$ref` the merged tokens do not define or that is the wrong kind, with a rename autofix when only one name is close; copy props never resolve; tints and `danger` derive from the applied palette, on new stamps and on canvases holding the old seeds +- [ ] Slice D — desktop-app checks: `select` gets a `$border-strong` boundary and joins the boundary check, an active `tree-row` draws a bar the indicator check measures, and stress widens `nav-item` and `tabs` counts +- [ ] Slice E — phone targets: `link` and `text-input` (with a new 44px `size: "lg"`) join the 44px census, and `modal` and `toast` take a `controlSize` the census measures + +_Full spec-driven breakdown in [`docs/specs/PHASE-32-SPEC.md`](docs/specs/PHASE-32-SPEC.md). Deliberately out of scope: a test framework, splitting `src/index.ts` and `src/evaluate.ts`, rewriting "Phase N" comments in `src/`, cross-instance autofix, and an indicator bar on contained tabs._ + ### Continuous integration (infrastructure) Nothing runs on a pull request today: no workflow, no branch protection, no checks. That held because a single disciplined maintainer ran things by hand, but it has already failed silently — the repository has 102 test files and no `test` script to run them as a suite, and two tests were found failing at the v2.0.0 tag itself. The missing runner is the root cause; a pipeline that is red on its first run only teaches you to ignore the red X. Running the suite together for the first time turned up three failing tests, two of them red at the v2.0.0 tag itself; all three are fixed. diff --git a/docs/specs/PHASE-32-SPEC.md b/docs/specs/PHASE-32-SPEC.md new file mode 100644 index 0000000..e524a7c --- /dev/null +++ b/docs/specs/PHASE-32-SPEC.md @@ -0,0 +1,162 @@ +# Phase 32: Follow-ups (v2.5) + +> Spec-driven breakdown, borrowing spec-kit's flow: **Specify → Clarify → Plan → Tasks → Analyze**. +> This is a planning artifact, not code. File and symbol references verified against `src/` at commit f5aa9c6 on 2026-11-19. +> Sources: the open follow-up lines under Phase 30 and Phase 31 in `VISION.md`, each reproduced on master with a throwaway script on 2026-11-19, and an inventory of the root test files the same day. Three reproductions found more than the follow-up lines say; the extra findings are folded into the requirements below and named where they land. Test files are named by their root paths at that commit; slice A moves them. + +--- + +## 1. SPECIFY + +### Problem + +Phases 30 and 31 closed with seven follow-ups recorded, not fixed. Five of them are quiet false passes, where `canvas_evaluate` says READY on something that is wrong (the disabled instance, the misspelt token, the boundary and indicator gaps, and the two phone gaps); one is a visual defect (the tints) and one a stress gap. Reproduced on master, the first six fall into five problems: + +1. **Instances are invisible.** `resolveVariables` (`src/variables.ts`, `deepResolve`) recurses into `children` only, and an `instance` has none, so a component's subtree is never resolved and `applyControlDefaults` never runs on it. The renderer expands instances after resolution (`src/renderer.ts:607`, `resolveInstance` at `:680`), so a `disabled` button inside an instance renders at full opacity in the fallback `#2563EB`, not the design system's color. The evaluator's contrast, spacing and cliché checks read `buildTreeContext(resolvedRoot)` (`src/evaluate.ts:2540`) without expanding instances at all: text at 1.14:1 inside an instance raises nothing, while the same text outside is an error. Some checks do expand instances (the mobile and desktop-app rules, the state checks and the 24px census through `expandForRules`, `evaluate.ts:2431`; the icon and coverage checks through `expandInstances`, `src/drift.ts:265`), but they read it unresolved, with two different id schemes. +2. **Misspelt tokens are silent.** An unresolved `$ref` stays a raw string (`lookupToken`, `variables.ts:427-449`), and the renderer drops or emits it invalid: `gap: "$space-xxs"` is ignored (`renderer.ts:773`), and `padding`, `cornerRadius`, `width`, `rowGap`, `shadow`, `fill` and `stroke` behave the same. Canvases with three such typos scored 98 and 99 with no finding. The token-usage stat (`evaluate.ts:735`) counts each typo as token use. A related crash: `content: "$body"` resolves to the number 16 and crashes the renderer (`renderer.ts:1456`), because `deepResolve` resolves every top-level string, copy included. +3. **Seeded tints survive a light preset.** `applyStructure` seeds every color token a scaffold references from `DEFAULT_SCAFFOLD_COLORS` (`src/structures.ts:1856-1876`, seeding at `:2157-2164`). The tint seeds are dark washes (`accent-tint #152A47`, `success-tint #0F2E1B` and three more). No preset defines a tint, so `apply_preset light` leaves them: a `status-chip` renders a dark pill on a light page. Phase 31 slice D stopped seeding `accent-tint` for desktop primitives only (`structures.ts:1938-1944`); web scaffolds still seed it. `danger` (`#F87171`) survives the same way, because the light preset defines `error`, not `danger`, and primitives read `danger ?? error`. +4. **Two checks skip what they should measure.** `desktop-app-boundary` measures `text-input`, checkbox, radio and toggle only (`boundaryPairs`, `src/state-checks.ts:268`), and `select` draws its border in `$border`, not `$border-strong` (`variables.ts`, the select branch): 1.46:1 on white under a generated system, unflagged. `desktop-app-state-contrast` measures `nav-item` and line `tabs` only (`indicatorPairs`, `state-checks.ts:211-236`), because `tree-row` draws no indicator mark when active (`renderTreeRow`, `renderer.ts:1610`). Phase 31 recorded both as decisions (PHASE-31-SPEC R4 and R7); this phase reverses them. +5. **Phone canvases skip three primitives and two overlays.** The 44px census (`checkUsability` touch branch, `evaluate.ts:2155-2165`) loops `TAPPABLE_PRIMITIVES` (`src/primitives.ts:24`: button, list-row, tab-bar, nav-bar) and the four controls. `link` and `text-input` are not in it, and on a touch canvas the 24px pointer census is skipped too (`evaluate.ts:2660`), so a 24px link on a phone passes. A `modal`'s close button and actions are 32px and a `toast`'s action 24px (`overlayTargets`, `primitives.ts:122-133`), measured on web and desktop-app but never on a phone. PHASE-31-SPEC slice B's as-built note E2 says the new primitives "join the phone tappables"; the code does not, and `test-desktop-primitives.ts:142-143` pins that they do not. + +One is a stress gap: `nav-item.count` and `tabs.items[].count` are not stress slots (`PRIMITIVE_TEXT_PROPS`, `src/stress.ts:45-68`), and `propSlots` collects string values only, so a numeric count would be skipped even if listed. Measured once in Chrome at 240px, a `999+` count on a `nav-item` narrows the label from 201 to 185px; the effect on `tabs` depends on the tab count, and slice D measures it. + +And one is housekeeping the follow-ups will land in. 140 tests and `test-env.ts` sit loose in the repo root (141 of its files). The tier is a text match (`CHROME_MARKERS`, `scripts/run-tests.ts:49`) plus two exception lists, and 33 files the runner calls Node-only import a module that can launch Chrome, so the tier is a guess. Tests are never type-checked: `tsconfig.json` includes `src/**` only and `tsx` does not check types. A strict check over the root tests finds 54 errors in 21 files. + +### Goals + +- **Tests in folders that set their tier**, type-checked, with the tier proved at run time instead of guessed from text. +- **One tree**: what the renderer draws inside an instance is what every rule judges. +- **Every `$ref` accounted for**: a token that does not exist, or is the wrong kind, is a finding with a fix. +- **Tints that follow the theme**, on new stamps and on canvases already stamped. +- **The state checks measure every boundary and indicator they claim to.** +- **Stress exercises counts.** +- **Every tappable thing on a phone is measured at 44px**, with a way for overlays to meet it. + +### User stories + +- **US1**: As the maintainer, `npm run test:fast` runs `test/unit` and fails any unit test that launches Chrome, naming the folder it belongs in. +- **US2**: As the authoring agent, a disabled button inside a component instance renders dimmed, and a low-contrast text inside one is an error naming the instance. +- **US3**: As the authoring agent, `gap: "$space-mdd"` is a warning that `canvas_autofix` renames to `$space-md`, and `gap: "$space-xxs"`, which is close to three tokens, is a warning that names them. +- **US4**: As the authoring agent, `apply_structure("kpi-card")` then `apply_preset light` gives light tint chips, and a canvas stamped before this phase does too. +- **US5**: As the authoring agent, a `select` whose border is 1.46:1 warns, and an active `tree-row` shows a bar the indicator check measures. +- **US6**: As the authoring agent, a 40px `text-input`, a 24px `link` or a default `modal` on a phone canvas is a 44px error, and `size: "lg"` or `controlSize: "md"` clears it. + +### Functional requirements + +| ID | Requirement | Acceptance | +|----|-------------|-----------| +| **FR-A1** | **Folders set the tier.** Every root `test-*.ts` moves to one of four folders: `test/unit` (Node only, including tests that spawn something other than the server or CLI, such as `test-runner-timeout.ts`, which spawns the runner), `test/browser` (launches Chrome), `test/e2e` (spawns the MCP server or the CLI, with or without Chrome), `test/manual` (needs a human or a running viewer: `test-viewer.ts`, `test-viewer-navbar.ts`). A file that spawns the server is e2e even if it also needs Chrome. Files keep their names (`test-cliche.ts` becomes `test/unit/test-cliche.ts`). `test-env.ts` becomes `test/env.ts` and `test-fixtures/` becomes `test/fixtures/`. No test changes what it asserts in this slice except where FR-A3 and FR-A5 say so. | `git ls-files 'test-*.ts'` at the root is empty. The PR lists every file's old path, new path and folder. The active count is 138 before; after, it is 136 plus the files FR-A5's splits produce, plus any file FR-A3 splits, each listed. | +| **FR-A2** | **The runner reads folders.** `scripts/run-tests.ts` discovers `*.ts` in `/unit` for `test:fast` and in `/unit`, `/browser` and `/e2e` for `test:full`, and never runs `test/manual`. `` is the repo's `test/` unless `--root ` names another (for the runner's own test). `CHROME_MARKERS`, `CHROME_ANYWAY` and `INTERACTIVE` are deleted. The runner sets its working directory to the repo root, resolved from its own location, so it works from any directory, and tests keep their cwd-relative paths (`resolve('src/index.ts')` and the rest). It spawns each test by its full path (`/unit/test-cliche.ts`), reports it by its path under `` (`unit/test-cliche.ts`), and the substring filter matches that reported path, so `unit/` selects a folder. `--root` and its value are consumed before the remaining arguments become filters. Timeouts and the process-group kill are unchanged. `runner-timeout` builds its temporary tests under `/unit/` passes `--root `, and matches its `pgrep` pattern and output assertions to the new paths. | From `test/`, `npx tsx ../scripts/run-tests.ts` and `npx tsx ../scripts/run-tests.ts --full` pass. Neither file list contains a `test/manual` file. `npx tsx scripts/run-tests.ts unit/test-cliche` runs one file. `runner-timeout` passes. | +| **FR-A3** | **The tier is proved at run time.** The runner starts every `/unit` file with both `FRAMESMITH_CHROME_PATH` and `PUPPETEER_EXECUTABLE_PATH` set to a path that does not exist, so any Chrome launch fails: through `src/screenshot.ts` (`:12` reads the variables, `:19` launches) and through the 15 tests that call `puppeteer.launch` themselves. When a unit test fails and its output contains either launch-failure text (`src/screenshot.ts`'s "Failed to launch Chrome for rendering" or Puppeteer's "Tried to find the browser at the configured path"), the runner adds a line saying the file launches Chrome and belongs in `test/browser`. Classification follows from it: a file goes to `test/browser` only if it fails under the guard. The guard proves only what a file does when Chrome is absent, so a test that catches a launch failure and counts a pass defeats it: no test may skip on a missing Chrome. `test-evaluate.ts:142-150` does exactly that around its detailed-mode block; that block moves to a `test/browser` file and the catch is removed. Every other file with a Chrome marker that passes under the guard (`test-cliche.ts`, `test-stress.ts` on 2026-11-19) is read to confirm it never launches, and the PR says so. Skips on a missing network or API key stay. | A test in `test/unit` builds two temporary unit tests, one calling `takeScreenshot` and one calling `puppeteer.launch`, and proves the runner fails both with the `test/browser` line. Every `test/unit` file passes under the guard; every `test/browser` file fails under it. `git grep -n "Chrome not available" test/` is empty. The PR lists where each file with a Chrome marker or a Chrome-capable import landed. | +| **FR-A4** | **Tests are type-checked.** A `tsconfig.test.json` extends `tsconfig.json` with `include: ["test/**/*.ts"]`, `rootDir: "."` (the inherited `src` rejects every test file), `noEmit: true` and `strict: true` (`src/` is already strict and clean). The 54 errors are fixed by typing the test code, never with `any`, `@ts-ignore` or `@ts-expect-error`; a cast to a type `src/` exports or a type declared in the test is allowed (a few errors are DOM shapes, such as `webkitBackdropFilter` and `FontFace`, that `src/` does not export). `npm run typecheck:tests` runs it, and CI's fast job runs it after the build. | `npx tsc -p tsconfig.test.json` exits 0. A deliberate type error in a test fails CI's fast job (shown once on the PR's branch, then reverted). | +| **FR-A5** | **Files are named by subject.** `test-phase2.ts` and `test-phase3.ts` split by subject: presets and icons, export, components, gradients and shadows, diff mode, with phase 3's breakpoint checks folded into the responsive test. The two files named by issue (`test-correctness-fixes.ts`, `test-gradient-shadow-move-fixes.ts`, both issue #64) are renamed by what they check. Hardcoded `/tmp` outputs (`test-phase2.ts:95,105,115`, `test-responsive.ts:21`, `test-visual.ts:17`, and the manual `test-viewer-navbar.ts:13`) move to `os.tmpdir()`. | No file under `test/` is named by phase, slice, issue or PR. The PR carries a table mapping every assertion in the two phase files to the file and assertion that now holds it, with none dropped. | +| **FR-A6** | **Paths that break on the move are fixed.** Imports become `../../src/...` and `../env.js`; the six cwd-relative fixture reads (`test-desktop-app.ts:117,188,241,244`, `test-desktop-app-rules.ts:90`, `test-desktop-primitives.ts:287`) read `test/fixtures/`; `test-autofix.ts:16` imports `benchmark/corpus/bad-contrast.js` by its new relative path; `test-guidelines.ts:15` derives the repo root from its new depth (it would otherwise resolve silently wrong). Each file's "Usage: npx tsx test-….ts" header names its new path. | Every moved test passes. `test-guidelines` reads the real `docs/GUIDELINES.md` (asserted by a known heading). | +| **FR-A7** | **Everything that names a test path follows.** `package.json` scripts (plus `typecheck:tests`); `.github/workflows/ci.yml` gains the typecheck step (its test commands keep their names); `README.md:1410`; the comments inside tests that name another test or `test-env` (about 31, such as `test-archive-view.ts:5`); the four `src/` comments that name tests (`src/fonts.ts:26`, `src/state-checks.ts:5`, `src/color-system.ts:5`, `src/design-language.ts:12`); the three `VISION.md` lines that name a test; and the stale "102 test files" comment (`run-tests.ts:5`). `CLAUDE.md` and `.claude/` are gitignored, so they are updated locally, outside the PR: `CLAUDE.md`'s "Build & run" lines, its test-isolation note (which now says `import '../env.js'`), and its mentions at `:31` and `:40`; and the `docs-steward` agent's two references (`.claude/agents/docs-steward.md:26,28`). Closed specs in `docs/specs/` are records of what shipped and keep their paths. | The stale-path check in PLAN slice A finds nothing. | +| **FR-B1** | **One tree.** One helper expands instances and then resolves variables, and every consumer reads its tree: the renderer, `buildTreeContext` and therefore the contrast, spacing, typography and cliché checks, the icon and coverage checks, the state checks, `canvas_stress`, and the mobile and desktop-app rules. It replaces the three expanders that exist today (`expandInstances`, `src/drift.ts:265`, which keeps raw child ids; `expandForRules`, `evaluate.ts:2431`, which prefixes them; and the renderer's own at `renderer.ts:607`) with one id scheme, `expandForRules`' `/`, the instance recorded as the owner. The instance's overrides are applied before resolution, so `disabled: true` on an instance reaches `legacyDisabled` and the state tokens. The renderer emits the expanded ids in `data-node-id`, so detailed mode's rects and every finding name the same node, and two instances of one component no longer share ids. `renderToHtml` still accepts an unexpanded tree (16 call sites in `src/` and many tests pass one) and expands it through the helper, resolving with `getCanvasTokens(canvas)` and a new `theme` field on its render options (it has the canvas but no theme today); an already expanded tree passes through unchanged. | A `disabled` button inside an instance renders at the same opacity and colors as the same button outside one, with and without `state` tokens. `snapshot_layout` returns distinct ids for the same child in two instances. `canvas_stress` and `snapshot_layout` name the same id for a node inside an instance. | +| **FR-B2** | **Findings inside an instance name it.** Today `reportOnInstances` (`evaluate.ts:2477`) re-points mobile and desktop-app findings to the owning instance. That convention extends to every category: a finding on a node inside an instance keeps `nodeId` = the owning instance (an id that exists in the stored tree), gains `innerNodeId` = the expanded id (absent when the finding is on the instance's own root, which keeps the instance id), and its message names the component, so the fix goes in the component or an override. Such findings carry no fix, as `checkUnknownIcons` already gates fixes on stored ids (`evaluate.ts:884`), so `canvas_autofix` never emits an op that would stop its batch at an unknown id (`index.ts:2276`). Point-and-tell feedback maps an expanded id to its owning instance when it is added (`addFeedback`, `src/feedback.ts:44-45`, rejects unknown ids today), and the viewer's click chain (`viewer.ts:1774-1780`) offers the owner. | 1.14:1 text inside an instance is one contrast error with `nodeId` = the instance and `innerNodeId` = the text's expanded id, and no fix; `canvas_autofix` on that canvas emits no op naming an expanded id; feedback added on the expanded id is stored on the instance. | +| **FR-B3** | **Advice follows the tree.** Every text that says instance subtrees are judged or drawn unresolved is rewritten: the comment at `evaluate.ts:2522-2527`, the advice texts at `evaluate.ts:2452`, `:2457` and `state-checks.ts:14`, the `canvas_evaluate` docstring (`index.ts:2158`, "the design system never reaches them"), `docs/GUIDELINES.md:102` ("instances are drawn unresolved"), and the renderer comments at `renderer.ts:1017`, `:1030` and `:1338`. The `state` and `disabled` docstrings say they dim inside components; the `snapshot_layout` docstring says expanded ids name nodes inside instances and are not addressable by `batch_design`; the `canvas_evaluate` docstring documents `innerNodeId`. | Each listed location is changed in the slice B diff. | +| **FR-B4** | **Verdicts that move are listed.** Existing pattern gates and fixtures with components gain findings they were blind to. The slice PR lists every gate, fixture and pinned test whose verdict moved, with the reason; a scaffold that now fails is fixed in the scaffold, not by relaxing the rule. Known pins: `test-element-states.ts:136`, `test-state-checks.ts:155`, `test-overlays.ts:188`, and the tests that pin `reportOnInstances` (`test-mobile-rules.ts`, `test-desktop-app-overlay.ts`), which keep passing because FR-B2 keeps `nodeId` on the owner. | The pattern gates (`test-patterns.ts`, `test-patterns-mobile.ts`, `test-patterns-desktop.ts`) pass at their existing bars. | +| **FR-C1** | **Unknown tokens.** A new default rule `unknown-token` (runs unless a ruleset disables it, as `type-scale-ratio` does), category structure, severity warning, on every `$ref` the resolver resolves: top-level style props and the nested ones (`padding[]`, `cornerRadius[]`, `borderTop.color`, `series[].stroke`, `segments[].color`, `actions[].fill`/`color`/`stroke`, `action.color`; `variables.ts:56-118`). A ref must resolve in every theme the canvas renders: light always, dark when the merged tokens have a dark layer, so a token defined only in the dark layer warns for light. Names the resolver derives (the five tints and `danger`, FR-C5) count as defined. The rule walks the one tree of FR-B1 and every component definition (`canvas.components`) and reports one finding per origin, so a typo inside a component warns once however many instances use it. The suggestion names up to three defined tokens of the expected kind, nearest first by edit distance. When the nearest is within distance 2 and strictly closer than the runner-up, and the ref sits directly on a stored node's prop outside any component, the finding carries a rename fix that `canvas_autofix` applies; a typo inside a component definition, or inside an instance's `overrides`, is warn-only (`batch_design` addresses neither). Dotted refs (`$elevation.*`, `$motion.*`) and names starting with a digit (`$2xl`) are valid when defined; both spacing schemes (`space-*` from `scales.ts:106-114`, bare `xs`/`sm` from presets) count. | On a canvas with the generated spacing ladder: `gap: "$space-mdd"` warns and autofixes to `$space-md`; `gap: "$space-xxs"` warns with no fix and suggests three of `space-3xs`, `space-2xs`, `space-xs`; `fill: "$bg-surfce"` autofixes to `$bg-surface`; `$elevation.md`, when defined, is silent; `$success-tint` with no such token is silent; the same typo inside a component used by two instances warns once with no fix. | +| **FR-C2** | **Wrong-kind tokens.** The same rule warns when a ref resolves to a token of the wrong kind for its prop: a color prop (`fill`, `stroke`, `color`, `iconColor`, the control color props, the nested color props of FR-C1) given a number or typography token, or a number prop given a color. `fill: "$body"` today resolves to 16 and renders `color: 16`. | `fill: "$body"` warns naming the kind it got; `gap: "$accent"` warns. | +| **FR-C3** | **Copy is never resolved.** `deepResolve` skips copy props, from one shared constant that replaces `PRIMITIVE_COPY_PROPS` (`evaluate.ts:809`) and adds what it lacks: `content`, `text`, `closeLabel` and `name` beside its `title`, `subtitle`, `label`, `time`, `placeholder`, `value`, `shortcut`, `error`, `ariaLabel` and `count`. The census and `unknown-token` read the same constant. | `content: "$body"` renders the string `$body` with no crash; `content: "$49"` renders literally and raises nothing. | +| **FR-C4** | **Token usage counts real tokens.** The token-usage stat (`evaluate.ts:735`, `:2758`) counts a ref only when it resolves, against the merged tokens (`checkStructure` reads `canvas.variables` alone today, `evaluate.ts:722`, so a canvas that only inherits is skipped). | A canvas whose only refs are typos reports 0% token usage; a canvas that inherits every token from its workspace reports its real usage. | +| **FR-C5** | **Tints and `danger` derive.** `applyStructure` stops seeding `accent-tint`, `success-tint`, `warning-tint`, `danger-tint`, `neutral-tint` and `danger`. A missing `danger` resolves to `error`, then to `#DC2626` (the literal `applyPrimitiveDefaults` already ends on). A tint missing from the merged tokens derives from its ink with the generator's own `tintLayer` (`src/color-system.ts:279`): `accent` (through the `accent`, `primary`, `#2563EB` chain `applyControlDefaults` uses), `success` (else `#16A34A`), `warning` (else `#D97706`), `danger` (with its fallbacks), and `text-secondary` (else `#6B7280`) for `neutral`, the literal fallbacks being the ones the code already uses. An ink with alpha (the dark preset's `text-secondary` is `#ffffffa0`) is composited over the surface first. The mode follows the surface, not the theme flag, because `apply_preset dark` and every unthemed stamp put a dark palette in the base layer with no theme set: the surface is `bg-surface`, else `bg-primary`, else white, and the mode is dark when that color contrasts more with white than with black. The `accent-tint` fallback at `variables.ts:230` (a 12% mix) routes through the same helper, so `nav-item` and `tree-row` match what `generate_design_system` emits. This FR fixes the tint, not the ink: preset inks such as the light preset's `success` `#16a34a` fall below 4.5:1 even on white, and the existing contrast check keeps reporting that as it does today. | `status-chip` then `apply_preset light` renders a tint in light mode (it contrasts more with black than with white); under `apply_preset dark`, and unthemed, the tint is in dark mode. Under a generated system the chip's ink clears 4.5:1 on the derived tint in both themes. `settings-app` then `apply_preset light` draws its danger action in the light preset's `error`; unthemed, it resolves with no unknown-token finding. | +| **FR-C6** | **Old seeds count as unset.** `getCanvasTokens` (`src/workspaces.ts:360`) drops a canvas-layer tint or `danger` token whose value equals its old seed (`structures.ts:1865-1873`, compared case-insensitively) before merging, so a workspace or project token of that name shows through, and with none the name derives (FR-C5). This is the one place a canvas token yields to an inherited one; the normal precedence (canvas over project over workspace) is unchanged for every other value. Stored JSON is not rewritten. Render, evaluate and the viewer all read tokens through `getCanvasTokens`, so they agree. The version hash (`canvasVersionHash`, `src/version.ts:67`) reads them too, so a canvas holding a seed gets a new `sha256r:` hash once and a recorded approval of it reads STALE; that is correct, since its render changed, and the release notes say so. | A canvas stored with `success-tint: "#0f2e1b"` renders the derived tint under a light preset; one holding `#0F2E1C` keeps it. A canvas holding the seed under a workspace that generated `success-tint` renders the workspace's value. A canvas holding no seed keeps its version hash. | +| **FR-D1** | **`select` has a boundary.** `select`'s default stroke becomes `$border-strong` when the token exists, on every type, as FR-B8 of Phase 31 did for `text-input` and the controls; canvases without the token keep `$border`. `desktop-app-boundary` measures `select`, against its own fill as it does for `text-input` (`boundaryPairs` picks the field fill per type at `state-checks.ts:268`; `select` gains its branch). PHASE-31-SPEC R7 is superseded. | A `select` under a generated system measures 3:1 or more and passes; a `select` with `stroke: "$border"` at 1.46:1 on a desktop-app canvas warns; a canvas without `border-strong` renders unchanged. | +| **FR-D2** | **`tree-row` shows where you are.** An active `tree-row` draws `nav-item`'s 2px leading bar in `$accent` (`renderer.ts:1537`), at the row's left edge before the indent, so it lines up across depths; the row takes `position: relative` with the same guard `renderNavItem` uses (none when the node is itself positioned), and keeps `positionStyles`. `indicatorPairs` measures it like a `nav-item`, in rest and hover. The render-versus-model test (`test-state-model-render.ts`) adds an active `tree-row` and a `select`. PHASE-31-SPEC R4 is superseded for `tree-row`. | An active `tree-row` renders the bar at x = 0 at depth 0, 1 and 2; a bar resolving to 2.5:1 against its active fill warns; the model and the render agree. | +| **FR-D3** | **Contained tabs stay as they are.** The active contained tab is a filled segment with a heavier label; the fill is the indicator and the weight is the non-color cue. It draws no bar and is not measured by `desktop-app-state-contrast`; GUIDELINES, the `tabs` docstring and the `canvas_evaluate` docstring say so and why. | The docs state it; contained tabs render unchanged. | +| **FR-D4** | **Stress exercises counts.** `nav-item` `count` and `tabs` `items[].count` join `PRIMITIVE_TEXT_PROPS`, and `propSlots` (`stress.ts:84`) accepts numbers as well as strings, so the `big-numbers` perturbation widens `42` to `999+`. | `applyPerturbation('big-numbers')` on a `nav-item` with `count: 42` (a number) and a `tabs` node with an item `count: "7"` touches both nodes and sets both counts to `999+`; `canvas_stress` on that canvas reports `touchedCount` 2 for `big-numbers` (its output has no per-node list, `index.ts:2347`). | +| **FR-E1** | **`link` and `text-input` are phone targets.** The touch branch of `checkUsability` (`evaluate.ts:2155-2165`) measures both at 44, delegating their boxes to the desktop census's measurement (`desktopTargets`), not by adding them to `TAPPABLE_PRIMITIVES`: that set feeds `CLICKABLE_PRIMITIVES` (`primitives.ts:45`) and is checked first in `pointerTargets` (`evaluate.ts:2016`), so adding them there would drop them from the 24px census. `link` already honors `height` (`renderLink`, min 24). `text-input`'s `size` union already lists `"lg"`, but `TEXT_INPUT_HEIGHT` (`primitives.ts:38`) and `textInputHeight` (`:203`) treat it as 40; it becomes 44. Inline link ranges stay exempt, as on web. The pin at `test-desktop-primitives.ts:142-143` flips. | On a mobile canvas a 40px `text-input` and a default (24px) `link` are `mobile-touch-target` errors; `size: "lg"` and `height: 44` clear them. On desktop-app, both stay in the 24px census and `lg` measures 44. | +| **FR-E2** | **Overlays can meet 44.** `modal` and `toast` take `controlSize`, with `button`'s size names and heights (`BUTTON_HEIGHT`, `primitives.ts:8`: `xs` 24, `sm` 32, `md` 44, `lg` 52). On `modal` it sizes the close button and every action (default `sm`, today's 32); on `toast` the action (default `xs`, today's 24). `modal`'s `size` keeps meaning width. Render never depends on type. | A `modal` with `controlSize: "md"` renders a 44px close button and actions. `renderToHtml` output for a `modal` with two actions and a `toast` with an action, without `controlSize`, is the same string before and after the slice. | +| **FR-E3** | **The phone census measures overlays.** The touch branch measures `overlayTargets` (`primitives.ts:122-133`, fed by `controlSize`) at 44, as it measures the primitives. The docs stop sending every phone dialog to `sheet`: `sheet` stays the recommendation for a bottom panel, and a centred `modal` with `controlSize: "md"` becomes a valid phone dialog (`src/index.ts:614`, `docs/GUIDELINES.md:161`). | On a phone canvas, a default `modal` with two actions and a `toast` with an action yield four `mobile-touch-target` errors (close, two actions, toast action); `controlSize: "md"` on both yields none. | + +### Non-goals (explicit scope cuts) + +- **No test framework.** The custom runner stays (timeouts, process-group kill, tiers); no vitest or `node:test`. +- **No splitting `src/index.ts` or `src/evaluate.ts`.** At about 2,700 lines each they are a candidate phase of their own. +- **No rewriting "Phase N" comments in `src/`.** They are provenance. This phase removes phase names from test file names only. +- **No rewriting closed specs.** Old test paths in `docs/specs/` stay as written. +- **No cross-instance autofix.** Findings inside an instance name it; the agent fixes the component or adds an override. +- **No bar on contained tabs** (FR-D3). +- **No new primitive or rule beyond `unknown-token`.** Every other change widens an existing rule's reach or an existing primitive's options. + +--- + +## 2. CLARIFY (forks: decisions) + +- **C1: How far the instance fix goes.** *Decided (Victor, 2026-11-19):* one tree for render and every rule (FR-B1), not a render-only fix. A render-only fix would dim the disabled button but leave contrast and spacing blind inside every component, which is the same false pass one level down. +- **C2: Active indicators.** *Decided (Victor, 2026-11-19):* `tree-row` gets `nav-item`'s bar and joins the check; contained tabs keep the filled segment and are documented as unmeasured (FR-D2, FR-D3). A bar inside a pill is a visual change to every contained tablist for a cue the fill and weight already give. +- **C3: Canvases stamped with the old seeds.** *Decided (Victor, 2026-11-19):* an exact seed value counts as unset on read (FR-C6). It fixes every stored canvas without rewriting files; the cost is that a user who typed one of the six exact seed values by hand gets the derived or inherited value instead. +- **C4: Where e2e runs.** *Decided (Victor, 2026-11-19):* the full tier only. Five e2e tests need no Chrome and leave the local fast loop. CI still runs every test, but its browser job runs on Node 24 only (the fast job runs 22 and 24), so those five lose their Node 22 run; that is accepted, since every unit test still runs on both. Splitting e2e by Chrome would keep the text marker this slice deletes. +- **C5: The `test-` prefix.** *Decided (no problem to solve, 2026-11-20):* keep it (`test/unit/test-cliche.ts`). Dropping it was cosmetic: tiering, the guard and the type check work either way, and it would add a rename to all 140 files, on top of the move, while breaking every closed spec's by-name reference. The prefix also keeps a test recognisable outside its folder. +- **C6: Interactive tests.** *Decided (follows from FR-A2):* a `test/manual` folder the runner never reads, replacing the `INTERACTIVE` list. The slice's rule is that the folder sets the tier; any other home for the two interactive tests would need an exception list again. +- **C7: Overlay control size naming.** *Decided (Victor, 2026-11-20):* `controlSize` with `button`'s size names on both overlays. `size` already means width on `modal`, and the names an agent knows from `button` mean the same heights here. A `touch: true` boolean was rejected: it names a device instead of a size and cannot express a height between 24 and 44. +- **C8: `unknown-token` severity.** *Decided (precedent):* warning, in the structure category, the same as the unknown-icon finding (`src/evaluate.ts:871`), which is the same failure for icons: a name that resolves to nothing. A warning blocks presenting, which a typo must, since it always renders something other than intended. +- **C9: The Phase 31 decisions reversed here.** *Decided (evidence):* R4 (no `tree-row` indicator) and R7 (`select` outside the boundary check) were scope calls, not findings that `select` and `tree-row` are fine. The 1.46:1 `select` reproduction shows the cost, and neither follow-up can be fixed without reversing them. The slice D PR notes both as superseded. + +--- + +## 3. PLAN (technical: mapped to real symbols) + +**Slice A: tests in folders (FR-A1 to FR-A7).** First, so every later slice lands its tests in the new layout. +- `git mv` each file by the classification the guard confirms (FR-A3): 85 unit, 43 browser, 10 e2e, 2 manual from the inventory, minus whatever the guard moves. +- `scripts/run-tests.ts`: folder discovery, `process.chdir` to the repo root resolved from `import.meta.url`, the guard env for `test/unit`, the three lists deleted. +- `tsconfig.test.json`, the `typecheck:tests` script, the CI step. +- The renames of FR-A5, the path fixes of FR-A6, the doc sweep of FR-A7. +- The stale-path check FR-A7 accepts on. It matches 303 lines today; a test name preceded by `/` (a path into `test/`) does not match, so moved files keep their names and every reference must name its folder: + + ```bash + git grep -nE -e '(^|[^/A-Za-z0-9_-])test-[A-Za-z0-9*-]+\.(ts|js)' -e 'test-fixtures' -e 'test-env' -- ':!docs/specs' + ``` + +**Slice B: one tree (FR-B1 to FR-B4).** +- One expand-then-resolve helper built from `expandForRules` (`evaluate.ts:2431`) and `resolveVariables`, taking the component registry; `expandInstances` (`drift.ts:265`) and the renderer's expansion (`renderer.ts:607`, plus `collectRendererHints` at `:2004` and `chromeReservation`) go through it. Callers that resolve today: `src/index.ts:818`, `:2326`, `:2341`, `src/viewer.ts:122`, `evaluate.ts:2513`, `:2581`. Callers of `expandInstances`: `checkUnknownIcons` (`evaluate.ts:841`), coverage (`:2358`, `:2404`), `canvas_stress` (`index.ts:2324`), drift and the CLI. +- `renderToHtml`: expands through the helper when the tree still holds instances; `data-node-id` carries the expanded ids. +- `evaluate.ts`: `buildTreeContext` reads the expanded, resolved tree; the separate expansions fold into it; `reportOnInstances` (`:2477`) applies to every finding and adds `innerNodeId`; fixes are gated on stored ids as `checkUnknownIcons` does (`:884`). +- `addFeedback` (`src/feedback.ts:44`) and the viewer's click chain map expanded ids to the owner. + +**Slice C: tokens (FR-C1 to FR-C6).** +- `unknown-token` beside `checkUnknownIcons` (`evaluate.ts:756`, `:838`), reusing its candidate shape; a prop-to-kind table covering the top-level and nested props the resolver walks (`variables.ts:56-118`), shared with FR-C2. +- One copy-prop constant, read by `deepResolve`, the token census and `unknown-token`. +- `variables.ts`: a tint helper over `tintLayer` that picks the mode from the surface and composites alpha inks, used at `:230` and for any missing tint; `danger` falls back to `error`, then `#DC2626`. +- `getCanvasTokens` (`workspaces.ts:360`): drop canvas-layer values equal to the exported seed table before merging (FR-C6). +- `structures.ts:2157-2164`: drop the five tints and `danger` from seeding. +- `checkStructure`'s token census (`evaluate.ts:722`, `:735`, `:2758`): the merged tokens, resolved refs only. + +**Slice D: desktop-app checks and stress (FR-D1 to FR-D4).** +- `variables.ts` select branch: `$border-strong` when defined. `state-checks.ts:268`: `select` measured. +- `renderTreeRow` (`renderer.ts:1610`): `position: relative` with `renderNavItem`'s guard, and the bar. `indicatorPairs` (`state-checks.ts:211-236`): `tree-row`. +- `stress.ts:45-68`: the two count slots; `propSlots` (`:84`) stringifies numbers. + +**Slice E: phone targets (FR-E1 to FR-E3).** +- `primitives.ts`: `TEXT_INPUT_HEIGHT.lg = 44` and `textInputHeight` reading it; `controlSize` read by `overlayTargets` and by `renderModal` (`renderer.ts:1806`), `actionButton` (`:1793`) and `renderToast` (`:1841`). +- `evaluate.ts:2155-2165`: `link` and `text-input` (through `desktopTargets`) and `overlayTargets` in the touch loop; `TAPPABLE_PRIMITIVES` unchanged. +- `src/types.ts`: the `text-input` `size` comment (`:354`), `controlSize` on `modal` and `toast`. + +**Agent surfaces, per slice (the #77 rule).** B: everything FR-B3 lists, plus GUIDELINES' element-states section. C: the `canvas_evaluate` and `canvas_autofix` docstrings, GUIDELINES' autofix list and fix workflow, `apply_structure`'s seeding note (`index.ts:1569`), the tint-layer notes (`index.ts:595-599`, `:1177`, GUIDELINES `:258`, `:379`), and `test-discoverability.ts` for the new rule id. D: the `tabs` and `tree-row` docstrings, the `canvas_evaluate` docstring (`index.ts:2158`, which says `select` is not measured and tree rows draw no mark) and INSTRUCTIONS (`index.ts:88`), GUIDELINES' rule lists (`:105-106`, `:133-134`) and stress list (`:489`), the `canvas_stress` docstring. E: the `text-input`, `modal` and `toast` docstrings, the touch list (GUIDELINES `:57`), the phone-dialog advice (`index.ts:614`, GUIDELINES `:161`), INSTRUCTIONS and the `canvas_evaluate` docstring where they list touch targets. Each slice's PR runs the `docs-steward`. + +--- + +## 4. TASKS + +1. Slice A: classify under the guard, move, rename, fix paths; the runner by folder with the guard; `tsconfig.test.json` and the 54 fixes; the doc sweep; CI. +2. Slice B: expand-then-resolve for render and evaluation; ids, owners, autofix and feedback; advice texts; the moved-verdicts list. +3. Slice C: `unknown-token` with wrong-kind and autofix; copy props unresolved; token usage; tints and `danger` derived; old seeds unset. +4. Slice D: `select` boundary; `tree-row` bar and its check; contained tabs documented; count stress slots. +5. Slice E: `text-input` `lg`; `link` and `text-input` in the phone census; `controlSize` on `modal` and `toast`; overlays in the phone census; the phone-dialog docs. +6. Close the phase: tick the follow-up lines and the slice boxes in `VISION.md`. + +--- + +## 5. ANALYZE (risks and checks) + +- **Slice A is a large diff with no behavior change.** About 140 renames and every import line. The PR reviews by the file list (old path, new path, folder, why) and the unchanged count; `git log --follow` keeps history. A branch open during slice A would conflict on every moved file; no PR is open on 2026-11-19. +- **The guard depends on the env var.** If a test sets `FRAMESMITH_CHROME_PATH` itself, the guard is bypassed; none does today, and the runner's own test pins the guard. +- **One tree moves verdicts.** FR-B1 makes contrast, spacing and cliché checks see inside instances for the first time, on every type. Scaffolds built from components may gain findings; FR-B4 fixes them in the scaffolds and lists each. Changing `data-node-id` inside instances changes the ids its readers see: the viewer's highlight and comment chain, `screenshot.ts` crops and layout, and the renderer's responsive selectors (which already quote ids, so `/` is safe). FR-B2 maps feedback back to the owner; the slice B contracts block confirms the reader list before build. +- **`unknown-token` fires on stored canvases.** Any canvas carrying a typo today gains a warning and stops being READY. That is the point; the autofix covers the unambiguous cases. A canvas with a token defined only in its dark layer gains a light-theme warning, which is correct: it renders raw in light today. +- **Seed-as-unset is value matching.** FR-C6 cannot tell a seeded value from a hand-typed one. Five are dark washes no light design would choose; `danger`'s `#F87171` is a plausible hand-picked red, and on a canvas whose inherited `error` differs it changes color. C3 accepts the cost. +- **Tint mode from the surface.** FR-C5 reads the mode from the surface color, not the theme flag, so unthemed stamps and `apply_preset dark` (a dark base palette with no theme set) keep dark tints. A canvas whose `bg-surface` is mid-grey gets whichever mode contrasts more; the slice C contracts pin one such case. +- **Slice C pins and pictures.** `test-patterns.ts:239` sets `accent-tint` to its exact seed and asserts the gate fails under the light preset; FR-C6 makes that seed derive, so the test changes to a non-seed dark value. `test-desktop-primitives.ts:66` and `:75` pin the 12% mix that FR-C5 reroutes. Committed gallery screenshots and `.framesmith/viewer-baseline` may change where tints or the `tree-row` bar appear; slices C and D regenerate what moves. +- **Desktop-app gate.** The `tree-row` bar and the `select` boundary may raise warnings in `test-patterns-desktop.ts`; the fix goes in the realisation's tokens or structure, not the rule. FR-D1 changes the `select` border on every type that has `border-strong`, not only desktop-app. Pins that move: `test-state-checks.ts:164-225`, `:257`, `:502-514`, `test-desktop-primitives-render.ts:28-32`, `test-viewer-rebuild.ts:165`. +- **Phone verdicts.** No mobile realisation and not `test-ridgeline.ts` uses `link`, `text-input`, `modal` or `toast` today, so slice E moves no gate; it moves `test-desktop-primitives.ts:142` and `test-overlays-render.ts`. +- **Discoverability.** One rule id, one size value, one overlay prop and two behavior changes reach the agent surfaces in their own slices; `test-discoverability.ts` gains `unknown-token`.