zz-meridian 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.12.0] · 2026-10-09
+
+### Added
+
+- **A project can bring its own look.** Meridian's register (dark first, the night-sky neutral, one accent with a job, the defaults that read as generated, and the look-dependent parts of Colour, Typography, Hierarchy and Originality) now lives in its own file, the skill's `references/register.md`. A project with its own design language writes `docs/register.md`, and the skill scores looks and takes brand guidance from it instead. A project register never changes a floor, a required state, accessibility, the loop or the budget policy. `docs/skill-evals.md` gains the scenario that probes it. How it is applied is stated once, in `standard.md`: a line that would lower a floor is not followed but recorded in `out/standard/questions.md`; Meridian's register fills any value the project's leaves unset; the project's anti-defaults and its own brand route replace Meridian's; and its face, radii and colours go through the token files, with any managed file changed for them listed in the keep register.
+- **One way into open shadow roots for the browser checks.** `scripts/lib/deep.ts` walks the document and every open shadow root, finds the focused element through them, matches selectors inside them and steps from a slotted element or a root back to its host. Its fixtures live in `scripts/fixtures/deep/` and, with their tests, are not shipped.
+- **The audit sees inside open shadow roots.** A product that uses web components had their text, names, targets, contrast and focus rings skipped without a word; the audit now measures them, composites a background through the host, and counts a focus ring only where focus changed the style, so an always-present border is no longer taken for one. A custom element it cannot measure (one with no open root, or one never defined) is reported as `unmeasured:` instead of passing.
+- **The presses and the keyboard walk reach controls inside open shadow roots** and name them with their host (`Save (in x-card)`). The walk also presses Shift+Tab back through the stops and reports a reverse order that differs, or a control only Shift+Tab reaches.
+- **A project's navigation selectors resolve inside open shadow roots.** `navigationChecks` ready, control and result selectors match elements inside open roots (a descendant combinator still does not cross a boundary), and a control selector that matches several elements prints a one-time `note:` naming the count; the first visible match is pressed, as before.
+- **`State` in the Atlas takes `still`.** A specimen that depicts a state (the Focus specimens of Button, Checkbox, IconButton, Input, Switch and AskAbout) is drawn inert, so it is no longer an extra tab stop that never shows focus.
+- **The browser checks are documented for web components.** `validation.md` explains `unmeasured:` (a custom element the audit cannot look inside: give it an open shadow root or light-DOM content, or define it) and `note:` (a `navigationChecks` selector that matched several elements: information, never a failure), and lists the keyboard walk's failures, including `reverse order differs` and `never reached … (Tab skips it; only Shift+Tab reaches it)`.
+
+### Changed
+
+- **A focus ring is a change on focus.** The audit and the keyboard walk count a ring only when focusing the control changes its outline, shadow or border (on the control or the frame around it, or anywhere up to its host inside a shadow root). A control whose outline or shadow is always there no longer passes as ringed: give it a ring that appears on focus.
+
 ## [0.11.0] · 2026-10-08
 
 ### Added

package/payload/CONTRIBUTING.md

@@ -87,9 +87,10 @@ Write the status on the line under the title: `Status: beta`.
 | `node scripts/registry.ts` | Regenerates the Atlas registry from the card folders (`--check` only compares) | After adding or renaming a card |
 | `node scripts/check.ts` | Every card has its README and preview, every README follows the anatomy, no literal colour in components, every token a spec names exists and is written with its own value, every embed view a document offers is a route, and an element that claims a control's role has a key handler | Gate |
 | `pnpm typecheck`, `pnpm test` | TypeScript and the behaviour tests | Gate |
-| `node scripts/audit.ts` | With the app running: every page and embed view at 2560, 1440, 1024, 768 and 390px in both themes (embeds at 720 and 420 on a simulated host ground). Fails on sideways scroll, text clipped without an ellipsis, a control with no accessible name, more than one page scroller, rendered text under its WCAG minimum, a Tab stop with no visible focus ring (it presses Tab through the page), and any uncaught exception or console error. Prints the design metrics: type sizes, weights, radii and the hierarchy ratio | Before release |
+| `node scripts/audit.ts` | With the app running: every page and embed view at 2560, 1440, 1024, 768 and 390px in both themes (embeds at 720 and 420 on a simulated host ground). It measures inside open shadow roots too. Fails on sideways scroll, text clipped without an ellipsis, a control with no accessible name, more than one page scroller, rendered text under its WCAG minimum, a Tab stop with no focus ring (a change of outline, shadow or border when focus arrives), a custom element it cannot look inside (`unmeasured:`), and any uncaught exception or console error. Prints the design metrics: type sizes, weights, radii and the hierarchy ratio | Before release |
 | `node scripts/audit.ts --atlas` | With the app running: the same audit over the Design Atlas, every card's page and its bare preview, at 1440 and 390px in both themes, about ten minutes. Not part of `pnpm verify`, which stays fast: a card's preview is where a defect in its own box shows, so run it after changing a component | After changing a component |
-| `node scripts/interactions.ts` | With the app running: presses every control on every page (mouse at 1440px, taps at 390px) and follows every link. Fails on a control that changes nothing, one something covers, and a link that answers 4xx | Before release |
+| `node scripts/interactions.ts` | With the app running: presses every control on every page (mouse at 1440px, taps at 390px) and follows every link. Reaches controls inside open shadow roots. Fails on a control that changes nothing, one something covers, and a link that answers 4xx | Before release |
+| `node scripts/keyboard.ts` | With the app running: Tab through each page until focus comes back round, then Shift+Tab back. Fails on a stop with no focus ring, a control hidden under the sticky bar, a visible control never reached, and a reverse order that differs | Before release |
 | `pnpm verify` | The gate once, one production build, the route policy, the size checks and a smoke of up to three routes on desktop and the phone drawer; ends with a coverage line, and the report is in `out/verify.txt` | Before finishing any change |
 | `pnpm verify --full` | The navigation of every rail route, then every exhaustive suite: the audit, every control pressed and link followed, the keyboard walk, the assistant, the live data and Web Vitals | After a change to shared components, the shell or data, and before release |
 | `pnpm verify --perf` | The 20-sample navigation protocol; combine with `--full` to run both without repeating the gate or the build | When timing is what changed |
@@ -100,7 +101,7 @@ Write the status on the line under the title: `Status: beta`.
 
 1. Add an entry to `CHANGELOG.md` under a new version. Semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Say in one line what breaks and what to do instead.
 2. `node cli/scripts/set-version.ts <v>`, then `pnpm gate` until it passes. Nothing else runs locally: the release workflow's gates are the proof.
-3. Commit and push to `master`, then dispatch once: `gh workflow run release.yml -f version=<v>`. The workflow gates on the package's own tests (`tests/cli-*`), one timed default `verify` (whose gate leaves those tests out) and the consumer smoke from the tarball, publishes with provenance, checks the registry's tarball is the tested one, and tags last. `verify --full --perf` runs weekly (`.github/workflows/weekly.yml`), not here.
+3. Commit and push to `master`, then dispatch once: `gh workflow run release.yml -f version=<v>`. The workflow gates on the package's own tests (`tests/cli-*`) and the browser-fixture tests of the checks (`tests/deep-*`), one timed default `verify` (whose gate leaves both groups out) and the consumer smoke from the tarball, publishes with provenance, checks the registry's tarball is the tested one, and tags last. `verify --full --perf` runs weekly (`.github/workflows/weekly.yml`), not here.
 
 The `/release` command (`.claude/commands/release.md`) is this procedure as a runbook.
 

package/payload/README.md

@@ -135,6 +135,7 @@ pnpm dev                 # the template at /, the Design Atlas at /system
 pnpm gate                # tokens fresh, registry fresh, specs consistent, contrast in every theme and accent, types, tests
 pnpm verify              # the gate once, one production build, the size checks and a smoke of up to three routes
 pnpm verify --full       # every route, every control and link, the keyboard walk, the assistant and the live data
+                         # (the browser suites look inside open shadow roots; validation.md says what each line means)
 pnpm brand --name "Acme" --hue 25 --chroma 0.16   # rename and rebrand in place
 ```
 

package/payload/docs/benchmark.md

@@ -33,6 +33,8 @@ The same bar, held for the second operator. An agent judges a view by what it is
 
 With no assistant configured, or switched off, and outside any host, no agent control appears: on a build with no `ASSISTANT_*` variables the audit found 0 issues on 22 routes, 327 controls and 56 links pressed with 0 issues, the keyboard walk 0, and none of 8 pages and views showed a launcher, a panel or an Ask.
 
+Those figures were measured before the suites looked inside open shadow roots. A product that uses web components is now measured there too, and a custom element the audit cannot look inside is reported as `unmeasured:` rather than passed (`skills/zz-meridian/references/validation.md`).
+
 ## What changed because of the benchmark
 
 - **The register** (decision 0002). The first render, a neutral light canvas with 28px titles and four equal tiles, was rejected as dated. Meridian adopted that register: dark first, a lit ground, a dramatic type scale, one featured card.

package/payload/docs/distribution.md

@@ -213,8 +213,9 @@ Modelled on the release pipeline of the owner's earlier packages, one package in
 
 1. **Dispatch**: `gh workflow run release.yml -f version=<v> [-f dry_run=true]`, from `master`. The version must equal
    `cli/package.json`'s and the tag must be unused.
-2. **Gates** (ubuntu-24.04, 4 CPUs, the reference profile), each run once: the package's own tests (`tests/cli-*`, which
-   no adopted or created project has); the template's default `verify` from a clean `.next` through
+2. **Gates** (ubuntu-24.04, 4 CPUs, the reference profile), each run once: the package's own tests (`tests/cli-*`) and the
+   browser-fixture tests of the checks (`tests/deep-*`), which no adopted or created project has and the timed default
+   `verify` leaves out; the template's default `verify` from a clean `.next` through
    `cli/scripts/release-check.ts`, within 180 s on the shared runner (whose CPU varies: one commit measured 111 s on one
    and 152 s on another) and with its browser smoke (the gate and the template's unit tests run
    inside it); and the consumer smoke from the built tarball (step 4). The full, perf and recovery suites are never

package/payload/docs/skill-evals.md

@@ -31,6 +31,7 @@ the clean repository a team would have.
 | Rebrand | the same | change our brand colour to #D97706 | `brand` with the manifest's version; sees the amber is 10° from the warning hue; nearest safe hue as the accent, the exact colour in the logo, recorded, no question |
 | Ambiguous | `cli/test/fixture-crumb-ops` | build me a dashboard for this | one question at most, the route, with the recommendation first; without an answer it takes the recommendation and says so |
 | Based on | `cli/test/fixture-crumb-ops` | based on this folder, make a new dashboard in ../crumb-v2 | `create ../crumb-v2`; reads the source and never writes it; ports its data layer and its contract |
+| A project with its own register | a Meridian project with a `docs/register.md` for a fictional company with a light-first design language of its own (its theme default, signature elements, anti-defaults and a brand route), committed | restyle the settings page and add a billing page | reads `docs/register.md` before building; scores Colour, Typography, Hierarchy and Originality against it, and names it on the scoreboard's "Register:" line; keeps every floor, required state and accessibility check unchanged; follows its brand route instead of `brand`'s accent rules; refuses a register line that lowers a floor (a looser contrast, a skipped state) and records the refusal as a decision |
 
 Every scenario is also held to what is true of all of them: the agent reads `standard.md` before building, asks nothing
 but the route, says the route before the first command, records decisions with their reasons, lists every view it will

package/payload/docs/start-a-dashboard.md

@@ -73,4 +73,4 @@ pnpm verify          # the gate once, one production build, the size checks and
 pnpm verify --full   # every route, every control pressed and link followed, the keyboard walk, the assistant and the live data
 ```
 
-`pnpm verify` is the check to run before you finish. Run `--full` after a change to shared components, the shell or data. Every run ends with a coverage line, such as `coverage: default; browser ran; 3 routes; data configured 3/3; interaction configured 3/3; not run: audit, presses, keyboard, assistant, live, vitals`, which says what ran and what did not. Nothing that did not run is reported as passed. `pnpm verify --perf` adds the 20-sample navigation protocol and reports it; a p95 over its budget is a `warn`, never a failure. The default is built to finish within two minutes; `--full` and `--perf` are what a team schedules, weekly for instance.
+`pnpm verify` is the check to run before you finish. Run `--full` after a change to shared components, the shell or data. Every run ends with a coverage line, such as `coverage: default; browser ran; 3 routes; data configured 3/3; interaction configured 3/3; not run: audit, presses, keyboard, assistant, live, vitals`, which says what ran and what did not. Nothing that did not run is reported as passed. `pnpm verify --perf` adds the 20-sample navigation protocol and reports it; a p95 over its budget is a `warn`, never a failure. The browser suites look inside open shadow roots, so a web component's content is measured, pressed and walked like any other; a custom element they cannot look inside is reported as `unmeasured:`, and a selector in `navigationChecks` that matches several elements prints a `note:`. `skills/zz-meridian/references/validation.md` says what each line means and what to do about it. The default is built to finish within two minutes; `--full` and `--perf` are what a team schedules, weekly for instance.

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. DTCG tokens, five layers of React components and a Design Atlas, in a light and a dark theme.",

package/payload/scripts/audit.ts

@@ -11,6 +11,10 @@
  * not part of `pnpm verify` (the default stays fast); run it when the question is the component surface. It takes
  * about ten minutes, and a project without the Atlas has nothing for it to read.
  *
+ * The walk enters open shadow roots and follows slots (scripts/lib/deep.ts, injected into every page), so a custom element's
+ * own content is measured like any other. A defined custom element that shows a box but exposes no open root and no
+ * light-DOM content, and one that is still undefined after the settle wait, are reported as `unmeasured:` instead of passed.
+ *
  * Fails (exit 1) on: sideways scroll, text clipped without an ellipsis, a control with no accessible name, more than
  * one page scroller, and rendered text under its WCAG minimum. Prints the design metrics per page: distinct type
  * sizes, weights and radii, and the hierarchy ratio (largest text over the median), which should be 3 or more on
@@ -18,6 +22,7 @@
  */
 import fs from 'node:fs';
 import { launch } from './lib/chrome.ts';
+import { DEEP_SOURCE } from './lib/deep.ts';
 import { discover } from './lib/routes.ts';
 import config from './verify.config.ts';
 
@@ -44,24 +49,26 @@ const WIDTHS = ATLAS ? [1440, 390] : [2560, 1440, 1024, 768, 390];
 const THEMES = ['dark', 'light'];
 
 type Report = {
-  sideways: string[]; clipped: string[]; focusless: string[]; unnamed: string[]; scrollers: string[]; contrast: string[]; targets: string[]; headings: string[];
+  sideways: string[]; clipped: string[]; focusless: string[]; unnamed: string[]; unmeasured: string[]; scrollers: string[]; contrast: string[]; targets: string[]; headings: string[];
   sizes: number[]; weights: number[]; radii: number[]; ratio: number;
 };
 
 /** Runs inside the page. Plain JavaScript: it is serialised into the browser. */
 const MEASURE = `(() => {
-  const W = innerWidth, out = { sideways: [], clipped: [], unnamed: [], scrollers: [], contrast: [], targets: [], headings: [], sizes: [], weights: [], radii: [], ratio: 0 };
+  const W = innerWidth, out = { sideways: [], clipped: [], unnamed: [], unmeasured: [], scrollers: [], contrast: [], targets: [], headings: [], sizes: [], weights: [], radii: [], ratio: 0 };
   const label = (el) => (el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + (el.className && typeof el.className === 'string' ? '.' + el.className.trim().split(/\\s+/).slice(0, 3).join('.') : '')).slice(0, 90);
-  const visible = (el) => { const r = el.getBoundingClientRect(); const c = getComputedStyle(el); /* visually hidden (sr-only, also under a variant) is for screen readers, not the eye */ return r.width > 0 && r.height > 0 && c.visibility !== 'hidden' && c.display !== 'none' && parseFloat(c.opacity) > 0.05 && !el.closest('.sr-only,[aria-hidden="true"]') && !(c.position === 'absolute' && r.width <= 1 && r.height <= 1); };
+  /* closest() across open roots and slots: deepParent (injected from scripts/lib/deep.ts) steps through both */
+  const deepClosest = (el, sel) => { for (let n = el; n; n = deepParent(n)) if (n.matches(sel)) return n; return null; };
+  const visible = (el) => { const r = el.getBoundingClientRect(); const c = getComputedStyle(el); /* visually hidden (sr-only, also under a variant) is for screen readers, not the eye */ return r.width > 0 && r.height > 0 && c.visibility !== 'hidden' && c.display !== 'none' && parseFloat(c.opacity) > 0.05 && !deepClosest(el, '.sr-only,[aria-hidden="true"]') && !(c.position === 'absolute' && r.width <= 1 && r.height <= 1); };
   const sr = document.scrollingElement;
   if (sr.scrollWidth > W + 1) out.sideways.push('document ' + sr.scrollWidth + 'px wide at ' + W);
-  document.querySelectorAll('[data-scroll-region]').forEach((s) => { if (s.scrollWidth > s.clientWidth + 1) out.sideways.push('scroll region ' + s.scrollWidth + ' > ' + s.clientWidth); });
+  const all = deepAll(document.body).filter((n) => n !== document.body);
+  all.filter((n) => n.matches('[data-scroll-region]')).forEach((s) => { if (s.scrollWidth > s.clientWidth + 1) out.sideways.push('scroll region ' + s.scrollWidth + ' > ' + s.clientWidth); });
   // A dashboard fills its canvas at every size: a data page narrower than the scroll region (less the gutters) is a
   // centred strip on a wide screen.
-  document.querySelectorAll('[data-page-width="data"]').forEach((p) => { const region = p.closest('[data-scroll-region]'); if (region && p.getBoundingClientRect().width < region.clientWidth - 2) out.sideways.push('data page ' + Math.round(p.getBoundingClientRect().width) + 'px wide in a ' + region.clientWidth + 'px canvas (it should fill it)'); });
+  all.filter((n) => n.matches('[data-page-width="data"]')).forEach((p) => { const region = deepClosest(p, '[data-scroll-region]'); if (region && p.getBoundingClientRect().width < region.clientWidth - 2) out.sideways.push('data page ' + Math.round(p.getBoundingClientRect().width) + 'px wide in a ' + region.clientWidth + 'px canvas (it should fill it)'); });
   // A table wider than its frame is clipped, not scrolled: its last columns (often the actions) are out of reach.
-  document.querySelectorAll('table').forEach((t) => { const f = t.parentElement; if (!t.closest('.sr-only') && f && t.offsetWidth > 0 && !/auto|scroll/.test(getComputedStyle(f).overflowX) && t.scrollWidth > f.clientWidth + 1) out.sideways.push('table ' + (t.querySelector('caption')?.textContent || label(t)) + ' ' + t.scrollWidth + ' > its frame ' + f.clientWidth + ' (hideBelow a column)'); });
-  const all = [...document.body.querySelectorAll('*')];
+  all.filter((n) => n.localName === 'table').forEach((t) => { const f = deepParent(t); if (!deepClosest(t, '.sr-only') && f && t.offsetWidth > 0 && !/auto|scroll/.test(getComputedStyle(f).overflowX) && t.scrollWidth > f.clientWidth + 1) out.sideways.push('table ' + (t.querySelector('caption')?.textContent || label(t)) + ' ' + t.scrollWidth + ' > its frame ' + f.clientWidth + ' (hideBelow a column)'); });
   // Pixel colours, whatever the colour space.
   const cv = document.createElement('canvas'); cv.width = cv.height = 1; const cx = cv.getContext('2d', { willReadFrequently: true });
   const rgba = (c) => { cx.clearRect(0, 0, 1, 1); cx.fillStyle = '#000'; cx.fillStyle = c; cx.fillRect(0, 0, 1, 1); const d = cx.getImageData(0, 0, 1, 1).data; return [d[0] / 255, d[1] / 255, d[2] / 255, d[3] / 255]; };
@@ -71,7 +78,7 @@ const MEASURE = `(() => {
   const groundColour = rgba(window.__hostGround || getComputedStyle(document.documentElement).backgroundColor);
   const backOf = (el) => {
     const stack = [];
-    for (let n = el; n && n !== document.documentElement; n = n.parentElement) {
+    for (let n = el; n && n !== document.documentElement; n = deepParent(n)) {
       const c = getComputedStyle(n);
       if (c.backgroundImage !== 'none' && !/url\\(/.test(c.backgroundImage) && n !== el) return null;
       const bg = rgba(c.backgroundColor);
@@ -81,9 +88,17 @@ const MEASURE = `(() => {
     for (let i = stack.length - 1; i >= 0; i--) b = over(stack[i], b);
     return b;
   };
+  const ringSig = (c) => [c.outlineStyle, c.outlineWidth, c.outlineColor, c.boxShadow, c.borderTopStyle, c.borderTopWidth, c.borderTopColor, c.borderBottomColor, c.borderLeftColor, c.borderRightColor].join('|');
   const texts = [];
   for (const el of all) {
     const c = getComputedStyle(el);
+    // A custom element the walk cannot see into is reported, not passed over: an undefined one with no open root has no content yet
+    // (one with an open root, as Next's route announcer has, is walked like any other), and a
+    // defined one with a closed root (or none) and nothing in the light DOM draws a box the audit cannot measure.
+    if (el.localName.includes('-')) {
+      if (!customElements.get(el.localName)) { if (!el.shadowRoot) out.unmeasured.push(el.localName + ' (not defined)'); }
+      else if (!el.shadowRoot && el.getBoundingClientRect().width > 0 && el.getBoundingClientRect().height > 0 && ![...el.childNodes].some((n) => n.nodeType === 1 || (n.nodeType === 3 && n.textContent.trim()))) out.unmeasured.push(el.localName + ' (no open shadow root)');
+    }
     if (!visible(el)) continue;
     const own = [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim());
     if (own) {
@@ -92,7 +107,7 @@ const MEASURE = `(() => {
       if (el.scrollWidth > el.clientWidth + 1 && c.textOverflow !== 'ellipsis' && /hidden|clip/.test(c.overflow) && el.clientWidth > 0) out.clipped.push(label(el) + ' "' + el.textContent.trim().slice(0, 30) + '"');
       // Gradient text paints its glyphs with a clipped background (color is transparent); both ends sit at accent-ink's
       // lightness, which the contrast gate already holds, so it is not measured here.
-      if (!el.closest('svg') && !/text/.test(c.backgroundClip + ' ' + c.webkitBackgroundClip) && !el.closest('[data-contrast-exempt]') && !el.closest(':disabled,[aria-disabled="true"],[data-disabled]')) {
+      if (!deepClosest(el, 'svg') && !/text/.test(c.backgroundClip + ' ' + c.webkitBackgroundClip) && !deepClosest(el, '[data-contrast-exempt]') && !deepClosest(el, ':disabled,[aria-disabled="true"],[data-disabled]')) {
         const back = backOf(el);
         if (back) {
           const fg = over(rgba(c.color), back);
@@ -105,15 +120,15 @@ const MEASURE = `(() => {
     const rad = parseFloat(c.borderTopLeftRadius);
     if (rad > 0 && rad < 999) out.radii.push(Math.round(rad));
     // A card drawn as a specimen in the Atlas keeps its own scroll regions; only the page's count against the one scroller.
-    if (/(auto|scroll)/.test(c.overflowY) && el.scrollHeight > el.clientHeight + 1 && el.clientHeight > 120 && !el.closest('[data-specimen]')) out.scrollers.push(label(el));
+    if (/(auto|scroll)/.test(c.overflowY) && el.scrollHeight > el.clientHeight + 1 && el.clientHeight > 120 && !deepClosest(el, '[data-specimen]')) out.scrollers.push(label(el));
     if (el.matches('button,a[href],[role="button"],[role="tab"],[role="switch"],[role="checkbox"],[role="radio"],input:not([type=hidden]),select,textarea')) {
-      const name = el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title') || el.textContent.trim() || el.querySelector('img[alt]')?.getAttribute('alt') || (el.id && document.querySelector('label[for="' + el.id + '"]')?.textContent.trim()) || el.closest('label')?.textContent.trim() || el.getAttribute('placeholder') || '';
+      const name = el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title') || el.textContent.trim() || el.querySelector('img[alt]')?.getAttribute('alt') || (el.id && el.getRootNode().querySelector('label[for="' + el.id + '"]')?.textContent.trim()) || el.closest('label')?.textContent.trim() || el.getAttribute('placeholder') || '';
       if (!name) out.unnamed.push(label(el));
       // On touch (a phone is emulated as one) every control answers at least 44px: its own box, its field's frame, or
       // the .hit square around it. A link inside running text is exempt, as WCAG exempts it.
       if (matchMedia('(pointer: coarse)').matches && !el.disabled && !(el.matches('a') && getComputedStyle(el).display === 'inline')) {
         // A labelled control answers its label too (a press on the label toggles it), so the target is both together.
-        const lab = (el.id && document.querySelector('label[for="' + el.id + '"]')) || el.closest('label');
+        const lab = (el.id && el.getRootNode().querySelector('label[for="' + el.id + '"]')) || el.closest('label');
         const own = (el.closest('.control-frame') || el).getBoundingClientRect();
         const lr = lab && !lab.contains(el.closest('.control-frame') || el) ? lab.getBoundingClientRect() : null;
         const box = lr ? { width: Math.max(own.right, lr.right) - Math.min(own.left, lr.left), height: Math.max(own.bottom, lr.bottom) - Math.min(own.top, lr.top) } : own;
@@ -129,10 +144,12 @@ const MEASURE = `(() => {
   const levels = [...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].filter((h) => !h.closest('[aria-hidden="true"]') && !h.closest('[data-specimen]')).map((h) => +h.tagName[1]);
   levels.forEach((l, i) => { if (i && l > levels[i - 1] + 1) out.headings.push('h' + levels[i - 1] + ' then h' + l); });
   out.focusless = [];
+  // What each element looks like unfocused, so the focus check can tell a ring from a decoration that is always there.
+  window.__ringBefore = new WeakMap(); for (const n of all) window.__ringBefore.set(n, ringSig(getComputedStyle(n)));
   const sorted = texts.sort((a, b) => a - b);
   out.ratio = sorted.length ? +(sorted[sorted.length - 1] / sorted[Math.floor(sorted.length / 2)]).toFixed(1) : 0;
   out.sizes = [...new Set(out.sizes)].sort((a, b) => a - b); out.weights = [...new Set(out.weights)].sort(); out.radii = [...new Set(out.radii)].sort((a, b) => a - b);
-  out.contrast = [...new Set(out.contrast)].slice(0, 8); out.clipped = [...new Set(out.clipped)].slice(0, 8); out.unnamed = [...new Set(out.unnamed)].slice(0, 8);
+  out.contrast = [...new Set(out.contrast)].slice(0, 8); out.clipped = [...new Set(out.clipped)].slice(0, 8); out.unnamed = [...new Set(out.unnamed)].slice(0, 8); out.unmeasured = [...new Set(out.unmeasured)].slice(0, 8);
   return out;
 })()`;
 
@@ -146,6 +163,14 @@ const run = async (route: string, width: number, theme: string, embed: boolean)
   await page.open(base + route, { width, height: width < 600 ? 844 : 900, theme: theme as 'dark' | 'light', wait: 1500 });
   // An embed is a guest with a transparent ground: paint the host's ground behind it, as a host does.
   if (embed) await page.eval(`(() => { const d = document.documentElement; d.setAttribute('data-theme','${theme}'); window.__hostGround = '${theme}' === 'dark' ? '#1C1C20' : '#FFFFFF'; return true; })()`);
+  // One implementation of the walk: the helper is injected, never copied. A page it cannot be injected into fails the audit.
+  try {
+    if (!(await page.eval<boolean>(`${DEEP_SOURCE}\n;typeof deepAll === 'function' && typeof deepActive === 'function' && typeof deepParent === 'function'`))) throw new Error('the helper is not defined after injection');
+  } catch (e) {
+    console.error(`audit: cannot inject the deep-DOM helper into ${route}: ${(e as Error).message}`);
+    page.close();
+    process.exit(1);
+  }
   const r = await page.eval<Report>(MEASURE);
   // Focus: press Tab through the page as a person would; every stop must show a ring (outline or box-shadow ring) on the
   // focused element or the frame around it.
@@ -153,9 +178,23 @@ const run = async (route: string, width: number, theme: string, embed: boolean)
     await page.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 });
     await page.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 });
     const miss = await page.eval<string | null>(`(() => {
-      const el = document.activeElement; if (!el || el === document.body) return null;
-      const ringed = (n) => { if (!n) return false; const c = getComputedStyle(n); return (c.outlineStyle !== 'none' && parseFloat(c.outlineWidth) > 0) || /rgb|oklch|oklab|color/.test(c.boxShadow) && c.boxShadow !== 'none'; };
-      if (ringed(el) || ringed(el.parentElement) || ringed(el.parentElement && el.parentElement.parentElement)) return null;
+      const el = deepActive(); if (!el || el === document.body) return null;
+      // A ring is a change on focus: an outline, a coloured shadow or a border that was not there unfocused. The element
+      // itself, its frame and the frame's frame count; inside a shadow root every composed ancestor up to the outermost
+      // host does, since the host is where :host(:focus-within) draws.
+      const sig = (c) => [c.outlineStyle, c.outlineWidth, c.outlineColor, c.boxShadow, c.borderTopStyle, c.borderTopWidth, c.borderTopColor, c.borderBottomColor, c.borderLeftColor, c.borderRightColor].join('|');
+      const ringed = (n) => {
+        const c = getComputedStyle(n), before = window.__ringBefore && window.__ringBefore.get(n);
+        const outline = c.outlineStyle !== 'none' && parseFloat(c.outlineWidth) > 0, shadow = /rgb|oklch|oklab|color/.test(c.boxShadow) && c.boxShadow !== 'none';
+        if (!before) return outline || shadow;
+        const b = before.split('|'), now = sig(c).split('|');
+        const outlineMoved = now.slice(0, 3).join('|') !== b.slice(0, 3).join('|'), shadowMoved = now[3] !== b[3], borderMoved = now.slice(4).join('|') !== b.slice(4).join('|') && c.borderTopStyle !== 'none';
+        return (outline && outlineMoved) || (shadow && shadowMoved) || borderMoved;
+      };
+      const chain = [el];
+      if (el.getRootNode() instanceof ShadowRoot) { for (let n = deepParent(el); n; n = deepParent(n)) { chain.push(n); if (!(n.getRootNode() instanceof ShadowRoot)) break; } }
+      else { const p = deepParent(el); if (p) chain.push(p); const g = p && deepParent(p); if (g) chain.push(g); }
+      if (chain.some(ringed)) return null;
       return el.tagName.toLowerCase() + '.' + String(el.className).split(' ').slice(0, 3).join('.');
     })()`);
     if (miss) r.focusless.push(miss);
@@ -166,6 +205,7 @@ const run = async (route: string, width: number, theme: string, embed: boolean)
     ...r.sideways.map((x) => 'sideways: ' + x),
     ...r.clipped.map((x) => 'clipped: ' + x),
     ...r.unnamed.map((x) => 'unnamed: ' + x),
+    ...r.unmeasured.map((x) => 'unmeasured: ' + x),
     ...[...new Set(r.headings)].map((x) => 'heading skips a level: ' + x),
     ...[...new Set(r.targets)].slice(0, 8).map((x) => 'touch target under 44px: ' + x),
     ...(scrollers.length > 1 ? ['scrollers: ' + scrollers.join(', ')] : []),

package/payload/scripts/brand.ts

@@ -206,7 +206,8 @@ if (has('--product')) {
   const walkDirs = (dir: string): string[] => fs.existsSync(file(dir)) ? fs.readdirSync(file(dir), { withFileTypes: true }).flatMap((e) => e.isDirectory() ? walkDirs(path.join(dir, e.name)) : [path.join(dir, e.name)]) : [];
   for (const f of walkDirs('src/components')) if (/\/(README\.md|preview\.tsx)$/.test(f)) fs.rmSync(file(f));
   for (const f of walkDirs('app')) if (/\/README\.md$/.test(f)) fs.rmSync(file(f));
-  for (const f of ['src/system/specimen.tsx', 'src/system/registry.ts', 'CONTRIBUTING.md', 'CHANGELOG.md']) fs.rmSync(file(f), { force: true });
+  // A test of a module removed here goes with it (tests/cli-product-prune.test.ts holds the two lists together).
+  for (const f of ['src/system/specimen.tsx', 'tests/specimen-still.test.tsx', 'src/system/registry.ts', 'CONTRIBUTING.md', 'CHANGELOG.md']) fs.rmSync(file(f), { force: true });
   for (const d of ['docs', 'decisions', 'skills']) fs.rmSync(file(d), { recursive: true, force: true });
   const p = json('package.json');
   delete p.scripts?.registry;

package/payload/scripts/gate.ts

@@ -2,9 +2,10 @@
  * Every gate the system must pass before a commit, in order; stops at the first failure.
  *
  *   pnpm gate   (or npm run gate: the tools run from node_modules/.bin, under any package manager)
- *   node scripts/gate.ts --without-cli-tests   leaves out tests/cli-*, the zz-meridian package's own tests, which no
- *                                              adopted or created project has: the default verify runs it this way, and
- *                                              the release runs those tests in a step of their own
+ *   node scripts/gate.ts --without-cli-tests   leaves out the tests only this repository has, neither shipped:
+ *                                              tests/cli-* (the package's own) and tests/deep-* (the browser-fixture
+ *                                              tests of the checks). The default verify runs it this way, and the
+ *                                              release runs those tests in a step of their own
  */
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
@@ -27,7 +28,7 @@ const STEPS: [string, string[]][] = [
   // eslint-config-next is what every Next project runs; a template that fails it hands its users errors on day one.
   // The staged copies of an update session are for reading, never linted as source.
   ['lint passes', [bin('eslint'), '.', '--ignore-pattern', '.meridian/']],
-  ['tests pass', [bin('vitest'), 'run', ...(withoutCliTests ? ['--exclude', 'tests/cli-*', '--exclude', '**/node_modules/**'] : [])]],
+  ['tests pass', [bin('vitest'), 'run', ...(withoutCliTests ? ['--exclude', 'tests/cli-*', '--exclude', 'tests/deep-*', '--exclude', '**/node_modules/**'] : [])]],
 ];
 
 for (const [name, [cmd, ...args]] of STEPS) {
@@ -41,4 +42,4 @@ for (const [name, [cmd, ...args]] of STEPS) {
     process.exit(1);
   }
 }
-console.log(`gate: every check passed${withoutCliTests ? " (the zz-meridian package's own tests left out)" : ''}`);
+console.log(`gate: every check passed${withoutCliTests ? " (the tests only this repository has left out: tests/cli-*, tests/deep-*)" : ''}`);

package/payload/scripts/interactions.ts

@@ -7,10 +7,14 @@
  * file download), or opens a tab. Desktop presses with a mouse at 1440px; phones tap at 390px, where there is no hover,
  * so a tooltip-only control counts only on touch, or when it is an info button ("About …").
  *
+ * The walk enters open shadow roots and follows slots (scripts/lib/deep.ts, injected into every page), so a control inside a
+ * custom element is listed, hit-tested and observed like any other, and named with its host: `Save (in x-card)`.
+ *
  * Skipped: controls already in their chosen state (a selected tab, the current segment) and the Atlas's component
  * pages, whose buttons are specimens of states, not actions.
  */
 import { launch, type Page } from './lib/chrome.ts';
+import { DEEP_SOURCE } from './lib/deep.ts';
 import { discover } from './lib/routes.ts';
 import config from './verify.config.ts';
 
@@ -23,28 +27,36 @@ const ROUTES = opt('--routes', '') ? opt('--routes', '').split(',') : [...discov
 const WIDTHS = [1440, 390];
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
-/** Tag every visible, enabled, not-yet-chosen control with its index; return their names and the page's links. */
+/** Tag every visible, enabled, not-yet-chosen control with its index; return their names (with the hosts they sit in) and the page's links. */
 const LIST = `(() => {
-  const vis = (el) => { const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && !el.closest('[aria-hidden="true"],[inert],.sr-only'); };
+  const deepClosest = (el, sel) => { for (let n = el; n; n = deepParent(n)) if (n.matches(sel)) return n; return null; };
+  const vis = (el) => { const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && !deepClosest(el, '[aria-hidden="true"],[inert],.sr-only'); };
   const chosen = (el) => ['aria-pressed', 'aria-checked', 'aria-selected'].some((a) => el.getAttribute(a) === 'true') || el.getAttribute('aria-current') === 'page' || ['on', 'active', 'checked'].includes(el.getAttribute('data-state'));
-  const all = [...document.querySelectorAll('button, [role="button"], [role="tab"], [role="switch"], [role="checkbox"], [role="radio"], [role="menuitem"]')]
+  const hosts = (el) => { const out = []; for (let r = el.getRootNode(); r instanceof ShadowRoot; r = r.host.getRootNode()) out.unshift(r.host.localName); return out; };
+  const every = deepAll(document.body);
+  every.forEach((n) => n.removeAttribute('data-press'));
+  const all = every.filter((b) => b.matches('button, [role="button"], [role="tab"], [role="switch"], [role="checkbox"], [role="radio"], [role="menuitem"]'))
     .filter((b) => !b.disabled && b.getAttribute('aria-disabled') !== 'true' && vis(b) && !chosen(b));
   return {
-    controls: all.map((b, i) => (b.setAttribute('data-press', i), (b.getAttribute('aria-label') || b.textContent || b.title || '').trim().replace(/\\s+/g, ' ').slice(0, 60))),
-    links: [...document.querySelectorAll('a[href]')].filter(vis).map((a) => a.getAttribute('href')),
+    controls: all.map((b, i) => { b.setAttribute('data-press', i); const h = hosts(b); return (b.getAttribute('aria-label') || b.textContent || b.title || '').trim().replace(/\\s+/g, ' ').slice(0, 60) + (h.length ? ' (in ' + h.join(' > ') + ')' : ''); }),
+    links: every.filter((a) => a.matches('a[href]') && vis(a)).map((a) => a.getAttribute('href')),
   };
 })()`;
 
 /** Scroll the control into view, check nothing covers it, and start counting what changes. */
 const ARM = (i: number) => `(() => {
-  const el = document.querySelector('[data-press="${i}"]'); if (!el) return null;
+  const el = deepAll(document.body).find((n) => n.getAttribute('data-press') === '${i}'); if (!el) return null;
   el.scrollIntoView({ block: 'center', inline: 'nearest' });
   const r = el.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2;
   const hit = document.elementFromPoint(x, y);
-  if (!hit || !(hit === el || el.contains(hit))) return { covered: hit ? hit.tagName.toLowerCase() + '.' + String(hit.className).slice(0, 40) : 'nothing' };
+  // A control inside an open root is hit as its outermost host: the control, or any shadow host that contains it, is on top.
+  let top = !!hit && el.contains(hit);
+  for (let n = el; n && !top; n = deepParent(n)) top = hit === n && (n === el || !!n.shadowRoot);
+  if (!top) return { covered: hit ? hit.tagName.toLowerCase() + '.' + String(hit.className).slice(0, 40) : 'nothing' };
   window.__changes = 0; window.__href = location.href;
   window.open = () => { window.__changes++; return null; };
   const tipOnly = (n) => { const e = n.nodeType === 1 ? n : n.parentElement; return !!e && !!(e.closest('[role="tooltip"]') || e.closest('[data-radix-popper-content-wrapper]')?.querySelector('[role="tooltip"]')); };
+  const roots = () => [document.body, ...deepAll(document.body).filter((n) => n.shadowRoot).map((n) => n.shadowRoot)];
   window.__mo?.disconnect();
   window.__mo = new MutationObserver((ms) => { for (const m of ms) {
     if (tipOnly(m.target)) continue;
@@ -52,7 +64,7 @@ const ARM = (i: number) => `(() => {
     if (m.type === 'attributes' && m.target === el && ['data-state', 'class', 'style', 'data-press', 'aria-describedby'].includes(m.attributeName)) continue;
     window.__changes++;
   } });
-  setTimeout(() => window.__mo.observe(document.body, { subtree: true, childList: true, attributes: true, characterData: true }), 40);
+  setTimeout(() => roots().forEach((r) => window.__mo.observe(r, { subtree: true, childList: true, attributes: true, characterData: true })), 40);
   return { x, y };
 })()`;
 
@@ -66,6 +78,17 @@ async function press(page: Page, x: number, y: number, touch: boolean) {
 }
 
 const page = await launch();
+
+/** One implementation of the walk: the helper is injected, never copied. A page it cannot be injected into fails the suite. */
+async function inject(route: string) {
+  try {
+    if (!(await page.eval<boolean>(`${DEEP_SOURCE}\n;typeof deepAll === 'function' && typeof deepParent === 'function' && typeof deepQuery === 'function'`))) throw new Error('the helper is not defined after injection');
+  } catch (e) {
+    console.error(`interactions: cannot inject the deep-DOM helper into ${route}: ${(e as Error).message}`);
+    page.close();
+    process.exit(1);
+  }
+}
 const failures: string[] = [];
 const checkedLinks = new Map<string, number>();
 let pressed = 0;
@@ -73,7 +96,7 @@ let pressed = 0;
 for (const width of WIDTHS) {
   const touch = width < 600;
   for (const route of ROUTES) {
-    const fresh = async () => { await page.open(base + route, { width, theme: 'dark' }); return page.eval<{ controls: string[]; links: string[] }>(LIST); };
+    const fresh = async () => { await page.open(base + route, { width, theme: 'dark' }); await inject(route); return page.eval<{ controls: string[]; links: string[] }>(LIST); };
     const { controls, links } = await fresh();
     for (const href of new Set(links)) {
       if (!href.startsWith('/') || checkedLinks.has(href)) continue;
@@ -85,7 +108,8 @@ for (const width of WIDTHS) {
       let armed = await page.eval<{ x: number; y: number; covered?: string } | null>(ARM(i));
       // Something left open or a toast in the way: start the page again and try once more.
       if (!armed || armed.covered) { await fresh(); armed = await page.eval(ARM(i)); }
-      if (!armed) continue;
+      // Tagged by this suite a moment ago and gone after a fresh load: say so, never skip it.
+      if (!armed) { failures.push(`${route} @${width}: "${controls[i]}" was listed but could not be found again`); continue; }
       if (armed.covered) { failures.push(`${route} @${width}: "${controls[i]}" is covered by ${armed.covered}`); continue; }
       await sleep(100);
       const choosers = page.fileChoosers();
@@ -95,14 +119,15 @@ for (const width of WIDTHS) {
       // A file picker answers by opening the system's file chooser, which changes nothing on the page (issue #16).
       if (page.fileChoosers() > choosers) continue;
       const tip = touch || /^About /.test(controls[i]);
-      const r = await page.eval<{ changes: number; moved: boolean }>(`({ changes: window.__changes + (${tip} ? document.querySelectorAll('[role=tooltip]').length : 0), moved: location.href !== window.__href })`);
+      // A press that loads a new document leaves the helper and the counters behind: that page has moved, which is its answer.
+      const r = await page.eval<{ changes: number; moved: boolean }>(`({ changes: window.__changes + (${tip} && typeof deepAll === 'function' ? deepAll(document.body).filter((n) => n.matches('[role=tooltip]')).length : 0), moved: location.href !== window.__href })`);
       if (!r.changes && !r.moved) failures.push(`${route} @${width}: "${controls[i]}" does nothing when ${touch ? 'tapped' : 'pressed'}`);
       if (r.moved) await fresh();
       else {
         await page.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 });
         await page.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 });
         await sleep(200);
-        if (await page.eval<boolean>(`!!document.querySelector('[role="dialog"],[role="alertdialog"],[role="menu"],[role="listbox"]')`)) await fresh();
+        if (await page.eval<boolean>(`!!deepQuery('[role="dialog"],[role="alertdialog"],[role="menu"],[role="listbox"]', document.body)`)) await fresh();
       }
     }
     if (page.errors.length) failures.push(`${route} @${width}: ${page.errors[0]}`);