zz-meridian 0.12.2 → 0.12.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "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,32 @@
 
 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.
 
+## [Unreleased]
+
+## [0.12.3] · 2026-10-10
+
+### Fixed
+
+- **The assistant and live-data walk-throughs, and the vitals' taps, reach controls inside web components.** `scripts/assistant.ts`, `scripts/live.ts` and `scripts/vitals.ts` looked for buttons, rows, menus and dialogs in the light DOM only, so on a product whose controls are web components the walk-throughs failed at their first press and vitals measured INP over no tap at all. They now search through open shadow roots with `scripts/lib/deep.ts`, which gains `deepQueryAll`; the live check also looks for a change every 50 ms, since a row a web component draws shows its text without a mutation the page's observer hears, so its timings are now the time to show rather than to the next mutation. Each vitals line ends with `taps: N`. `/deep-tap` pins the tap.
+- **A browser suite reads a page once it has loaded.** `open()` in `scripts/lib/chrome.ts` waited a fixed time and for fonts (at most 4 s), so on a busy machine a suite could read a page still loading; it now also waits for the load event, up to 25 s. `/slow-load` pins it.
+- **A preset whose values differ by theme holds in a nested scope.** Graphite (and jade in dark) set their lightness with ancestor selectors, which cannot say which theme scope is nearest, so a dark scope inside a light page drew graphite's light values: a dark tile on a dark ground. `tokens.css` now picks them with `@scope`, whose proximity rule makes the nearest theme win; the unscoped rules stay, at one attribute's specificity, for a browser without `@scope`. Regenerate with `pnpm tokens`; nothing to change in a product. `tests/deep-accent-scope.test.ts` renders the fourteen nestings in Chrome.
+- **The command palette's field shows that it has focus.** The search band's hairline takes `accent` and its icon `accent-ink` while focus is inside; the audit failed the card without it.
+- **A region or key name never breaks at its hyphen.** `keepHyphenated` moved from the Incident card into `@/components/base/text-roles`; the Banner and the Toast use it too, so "eu-central-1" no longer splits after "eu-central-". Tokens over 24 characters still wrap.
+- **A narrow table's lead column takes the space it is given.** Under 512px of table the `grow` column takes the slack instead of a third, so a phone no longer cuts a route beside empty space.
+- **A disabled Select option is disabled on both lines.** Its description takes `ink-disabled` with its label.
+- **The request timeline's first tick reads `0ms`**, through `formatDuration`, like the ticks after it.
+- **Every category in a column chart keeps its label**, cut to its column while a column is at least 36px wide; dates still thin out.
+- **The assistant says it is working before its first words**: a spinner and "Working on an answer" until text arrives.
+- **A narrow metric tile drops its comparison whole** instead of "vs previou…", and its finding wraps instead of being cut.
+- **The search pill folds by the top bar's own width** (under 40rem), so a canvas narrowed by the assistant folds it too. The top bar is now a container.
+- **A read-only form section keeps its values legible** in `ink-2` instead of `ink-disabled`.
+- **A phone's record card reads its facts as one sentence**: the DataTable card is a wrapping row instead of a six-column grid, so a separator dot never lands alone on a line and a fact is never cut to fit a third.
+- **Members shows the date its order follows**: Joined appears from 768px of table (Role now drops below 1024px and Team below 1152px), so the newest-first order is explained wherever the table has columns; on a phone the card reads "Joined 1 Oct".
+- **The Atlas home drops its numbered section labels** (01 to 05), a default Meridian's own register rules out.
+- **A figure is never cut.** In a Metric tile or a Featured metric a number longer than nine characters is set at a glance with `fitFigure` ("9.9B", "$1.2M") instead of being clipped by its card; `splitFigure` keeps a compact amount's decimal in the number ("$1.2M", not "$1" and ".2M").
+- **A day inside a sentence reads "1 Oct"**: `formatDay` in `src/lib/format-date.ts`; tables and axes keep `formatDate`'s "01 Oct".
+- **The colour parser reads `lab()`.** A production build may ship an authored `oklch()` as `lab()`, which `src/lib/color.ts` could not parse; the contrast pairs the gate checks now live in `scripts/lib/contrast-pairs.ts`, so the Atlas measures the same ones.
+
 ## [0.12.2] · 2026-10-09
 
 ### Fixed

package/payload/CONTRIBUTING.md

@@ -69,7 +69,7 @@ Write the status on the line under the title: `Status: beta`.
 ## Done means
 
 - Every state is specified and previewed: rest, hover, pressed, focus, selected, disabled, loading, empty, error.
-- It holds in both themes, all four accents and both densities, with contrast computed in each by `pnpm contrast`: text 4.5:1, focus rings, control outlines and chart marks 3:1. A new pair goes into `scripts/contrast.ts`.
+- It holds in both themes, all four accents and both densities, with contrast computed in each by `pnpm contrast`: text 4.5:1, focus rings, control outlines and chart marks 3:1. A new pair goes into `scripts/lib/contrast-pairs.ts`, which the gate and the Atlas colour page both read.
 - It holds at 390, 768, 1024, 1280 and 1440px, and in an embed at 360 and 720px inline and in fullscreen.
 - Nothing scrolls sideways, nothing clips, and no label shrinks to fit (cut words instead).
 - Under reduced motion it shows its final state with nothing moving.

package/payload/app/(dashboard)/members/README.md

@@ -9,7 +9,7 @@ Status: beta
 | Row | Pattern | Console | Mobile |
 |---|---|---|---|
 | Masthead | PageFrame: kicker, "Members", one sentence, Invite member (primary) | One band | Stacked |
-| 1 | Data table: Name (avatar and name, grow), Email (from 1024px), Role (from 768px), Team (from 1280px), Status, Joined (from 1280px), Last active, and a row action menu | Columns | Cards: name and the menu, then status, team and last active |
+| 1 | Data table: Name (avatar and name, grow), Email (from 1024px), Role (from 1024px), Team (from 1440px), Status, Joined (from 768px, so the order the table opens in is on screen wherever it has columns), Last active, and a row action menu | Columns | Cards: name and the menu, then status, when they joined (the order the list follows) and last active; a card holds three facts, so team is left to the record |
 | Sheet | Invite a member: Name and Email (required), Role, Team; Cancel and Send invitation | From the right, 440px | From the bottom |
 | Dialog | Remove: "Remove {name}?", the consequence, and the suspend alternative; Cancel and Remove member (danger) | Centred | Bottom sheet |
 
@@ -20,7 +20,7 @@ The row menu holds Suspend (Reactivate on a suspended member) and Remove.
 | State | What shows |
 |---|---|
 | Loading | `loading.tsx`: skeleton table rows; the members are read per request, so the prerendered shell holds none |
-| Default | Newest members first |
+| Default | Newest members first, as the Joined column beside them shows |
 | Invited | The status Badge in `accent`; Last active reads "Never" in `ink-3` |
 | Suspended | The status Badge in `warning` |
 | Name or email missing | The field's error under it; nothing is sent |

package/payload/app/system/(atlas)/page.tsx

@@ -66,13 +66,13 @@ export default function AtlasHome() {
 
       {/* Layers */}
       <section className="mt-28">
-        <SectionHead kicker="01" title={<>Five layers,<br />built from the bottom.</>} line="Each layer uses only the ones beneath it, so a change at the bottom moves everything above, and nothing above invents a value of its own." />
+        <SectionHead title={<>Five layers,<br />built from the bottom.</>} line="Each layer uses only the ones beneath it, so a change at the bottom moves everything above, and nothing above invents a value of its own." />
         <Strata sections={SECTIONS.filter((x) => x.num).map((x) => ({ ...x, count: all.filter((e) => e.section === x.id).length, href: all.find((e) => e.section === x.id)?.href ?? '/system' }))} />
       </section>
 
       {/* Surfaces and operators */}
       <section className="mt-28">
-        <SectionHead kicker="02" title={<>Three surfaces.<br />Two operators.</>} line="People point, tap and type; agents call tools. Both use the same views, on the console, on a phone and in an MCP host, under five rules." />
+        <SectionHead title={<>Three surfaces.<br />Two operators.</>} line="People point, tap and type; agents call tools. Both use the same views, on the console, on a phone and in an MCP host, under five rules." />
         <div className="grid gap-px overflow-hidden rounded-xl border border-line bg-line sm:grid-cols-2 lg:grid-cols-5">
           {[
             ['Addressable', 'Every view’s state is in its address: an agent opens exactly the view it means.'],
@@ -96,7 +96,7 @@ export default function AtlasHome() {
 
       {/* Principles */}
       <section className="mt-28">
-        <SectionHead kicker="03" title={<>The principles<br />every layer answers to.</>} line="When two choices both fit the specification, pick the one that serves these better." />
+        <SectionHead title={<>The principles<br />every layer answers to.</>} line="When two choices both fit the specification, pick the one that serves these better." />
         <div className="grid border-t border-line md:grid-cols-2">
           {principles.map((p, i) => (
             <div key={p.title} className={'border-b border-line py-7 md:pr-10 ' + (i % 2 ? 'md:border-l md:pl-10' : '')}>
@@ -109,7 +109,7 @@ export default function AtlasHome() {
 
       {/* Guides */}
       <section className="mt-28">
-        <SectionHead kicker="04" title="Guides." line="How the surfaces work, how agents fit, and how to start a dashboard from this one." />
+        <SectionHead title="Guides." line="How the surfaces work, how agents fit, and how to start a dashboard from this one." />
         <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-5">
           {all.filter((e) => e.section === 'start' && e.id !== 'overview').map((e) => (
             <Link key={e.href} href={e.href} className="group flex flex-col rounded-lg border border-line bg-surface/70 p-5 hover:border-line-strong">
@@ -123,7 +123,7 @@ export default function AtlasHome() {
 
       {/* What changed: the latest release in one line and its headlines; the whole log is one link away. */}
       <section className="mt-24">
-        <SectionHead kicker="05" title="What changed." line="Every release, with what breaks and what to do instead." />
+        <SectionHead title="What changed." line="Every release, with what breaks and what to do instead." />
         <div className="grid gap-8 rounded-xl border border-line bg-surface p-7 lg:grid-cols-[minmax(0,2fr)_minmax(0,3fr)]">
           <div>
             <p className="t-kicker">{release.version} · {release.date}</p>
@@ -150,11 +150,11 @@ export default function AtlasHome() {
   );
 }
 
-function SectionHead({ kicker, title, line, compact }: { kicker: string; title: React.ReactNode; line: string; compact?: boolean }) {
+function SectionHead({ title, line, compact }: { title: React.ReactNode; line: string; compact?: boolean }) {
   return (
     <div className={compact ? 'mb-6' : 'mb-10 grid items-end gap-6 lg:grid-cols-[minmax(0,1fr)_minmax(0,1fr)]'}>
       <div>
-        <p className="t-kicker mb-5">{kicker}</p>
+        {/* No number above it: the headline names the section, and a counter would only be decoration. */}
         <h2 className="text-[clamp(32px,3.6vw,48px)] leading-[1.02] font-semibold tracking-[-0.03em]">{title}</h2>
       </div>
       <p className={'t-small max-w-[52ch] text-ink-2 ' + (compact ? 'mt-3' : 'lg:pb-1.5')}>{line}</p>

package/payload/docs/benchmark.md

@@ -84,6 +84,14 @@ Those figures were measured before the suites looked inside open shadow roots. A
 
 - **Big screens.** The owner found that on a large monitor the dashboard was a 1560px strip with empty margins. No review had looked past 1440px. Dashboards now fill the canvas at every width (`data-width` is 100%; the gutter grows to 56px), standalone screens keep a `stage-width` of 1560px, and reading pages stay at 832px. The audit now runs at 2560px too, and fails a data page that does not fill its canvas.
 
+- **A layer-by-layer pass, 2026-10-09.** Every token page and every card preview was rendered at 1440 and 390px in both themes and read from the bottom up, before the pages. What the audits could not see:
+  - **Tokens:** the colour page measured every role on a card surface, so tooltip text and the accent wash showed failing ratios they never have in use; each chip now measures the pair the gate checks. Graphite in a dark scope inside a light page drew its light values (ancestor selectors cannot say which theme is nearest); the presets now use `@scope`, held by a browser test of fourteen nestings.
+  - **Components:** "eu-central-1" broke at its hyphen in a banner; durations were spelled three ways; a phone table cut "/v1/messa…" beside empty space; a disabled option's second line stayed lit.
+  - **Patterns:** a column chart left every other category unnamed; the assistant showed nothing between Send and its first words; narrow tiles read "vs previou…"; a read-only form drew its values at 1.5:1; three specimens contradicted their own captions.
+  - **Pages:** a phone's record card left separator dots alone on a line and cut dates; Members looked unsorted because the column that explains its order was hidden; the Atlas home numbered its sections 01 to 05, which Meridian's own register rules out.
+  - **Extreme values:** fed the largest figures the formatters print, a row of four tiles cut "9,876,543,210" to "9,876,54", a different number with no ellipsis, which no audit flags because the card clips it. A figure past nine characters now reads at a glance ("9.9B", "$1.2M"); the Extreme values specimens hold it. A probe that rewrote every name and figure in tables, lists and records to its longest also found nothing pushed sideways on any route.
+  - **Measured:** `verify --full` on the final commit passes every suite: 0 audit issues on 22 routes at five widths in both themes, 361 controls and 56 links pressed, the keyboard walk, live data, and 18 of 18 pages under LCP 2.5 s, INP 200 ms and CLS 0.1. Web Vitals depend on a quiet machine: with other work holding the load at 11 to 38 on ten cores the same build read 10 to 17 of 18, because the four-times CPU slowdown applies to a host that is already busy; an A/B of the one shell change (the top bar as a container) showed INP tracking the load, not the build. Under reduced motion nothing moves on any route at 1440 or 390px.
+
 ## Open
 
 Taste calls the critic raised that are not taken yet, kept in view on purpose:

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "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/assistant.ts

@@ -15,10 +15,15 @@
  * on (from /keys); and the Settings switch. A product that removed one of those pages has no such flow to walk: each
  * step says `n/a` with the reason, and the rest still runs. Whether a sample surface is there is decided from its files,
  * so Meridian's own repository, which has every one, always walks all of them.
+ *
+ * Controls are found through open shadow roots (scripts/lib/deep.ts), so a design system whose buttons, rows and menus are
+ * web components is walked the same way: a control is searched for under the light-DOM container that holds it (the panel,
+ * the page's scroll region, the rail's `nav`) and named by its rendered text.
  */
 import path from 'node:path';
 import { slug } from '../src/app.config.ts';
 import { launch } from './lib/chrome.ts';
+import { DEEP_SOURCE } from './lib/deep.ts';
 import { APP_DIR, discover, railRoutes } from './lib/routes.ts';
 import { sampleSurfaces } from './lib/sample.ts';
 
@@ -47,26 +52,31 @@ const until = async <T>(what: string, read: () => Promise<T>, done: (v: T) => bo
   return done(v) ? v : fail(`timed out waiting for ${what} (last: ${JSON.stringify(v)})`);
 };
 
-const page = await launch();
-const MESSAGE = 'aside[data-assistant] textarea[aria-label="Message"]';
-const SEND = 'aside[data-assistant] button[aria-label="Send"]';
-const PROPOSALS = 'aside[data-assistant] article[aria-label^="Proposal from Assistant"]';
+/** A browser whose every page defines the deep-DOM helpers. */
+const browser = async () => { const p = await launch(); await p.send('Page.addScriptToEvaluateOnNewDocument', { source: DEEP_SOURCE }); return p; };
+const page = await browser();
+/** Page expressions: the panel, the page's own content, and the controls in the panel. */
+const PANEL = `deepQuery('aside[data-assistant]')`;
+const CONTENT = `deepQuery('[data-scroll-region]')`;
+const MESSAGE = `deepQuery('textarea[aria-label="Message"]', ${PANEL})`;
+const SEND = `deepQuery('button[aria-label="Send"]', ${PANEL})`;
+const PROPOSALS = `deepQueryAll('article[aria-label^="Proposal from Assistant"]', ${PANEL})`;
 
 /** Type `text` into the panel and press Send. */
 async function ask(text: string) {
-  await page.eval(`document.querySelector('${MESSAGE}').focus()`);
+  await page.eval(`${MESSAGE}.focus()`);
   await page.send('Input.insertText', { text });
-  await until('Send to enable', () => page.eval<boolean>(`!document.querySelector('${SEND}').disabled`), Boolean);
-  await page.eval(`document.querySelector('${SEND}').click()`);
+  await until('Send to enable', () => page.eval<boolean>(`!${SEND}.disabled`), Boolean);
+  await page.eval(`${SEND}.click()`);
 }
 /** What the assistant's latest text says (a Proposal card's own text is not the assistant speaking).
  *  `data-assistant-text` is the reply block's own handle: a reply is markdown, so its text may be in a paragraph, a
  *  list item or a table cell, and a selector that assumed a paragraph would break the day a model answers with a list. */
-const said = () => page.eval<string>(`[...document.querySelectorAll('aside[data-assistant] [data-assistant-text]')].at(-1)?.textContent.trim() ?? ''`);
+const said = () => page.eval<string>(`deepQueryAll('[data-assistant-text]', ${PANEL}).at(-1)?.textContent.trim() ?? ''`);
 /** The titles of the Proposal cards in the panel. */
-const proposals = () => page.eval<string[]>(`[...document.querySelectorAll('${PROPOSALS}')].map((a) => a.getAttribute('aria-label'))`);
+const proposals = () => page.eval<string[]>(`${PROPOSALS}.map((a) => a.getAttribute('aria-label'))`);
 /** A table row's text: the member's name, role, team, status and activity. */
-const row = (name: string) => page.eval<string | null>(`[...document.querySelectorAll('tbody tr')].find((r) => r.textContent.includes(${JSON.stringify(name)}))?.textContent ?? null`);
+const row = (name: string) => page.eval<string | null>(`deepQueryAll('tr').map((r) => deepText(r)).find((t) => t.includes(${JSON.stringify(name)})) ?? null`);
 /** Press with the mouse, as a person does: menus open on the pointer, not on a synthetic click. */
 async function press(find: string) {
   const where = `(() => { const el = ${find}; if (!el) return null; el.scrollIntoView({ block: 'center' }); const r = el.getBoundingClientRect(); return { x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2) }; })()`;
@@ -82,7 +92,7 @@ async function press(find: string) {
   for (const type of ['mouseMoved', 'mousePressed', 'mouseReleased'] as const) await page.send('Input.dispatchMouseEvent', { type, x: at.x, y: at.y, button: 'left', clickCount: 1 });
 }
 /** Press the button named `label` in the open Proposal card. */
-const decide = (label: string) => press(`[...document.querySelectorAll('${PROPOSALS} button')].find((b) => b.textContent.trim() === ${JSON.stringify(label)})`);
+const decide = (label: string) => press(`${PROPOSALS}.flatMap((a) => deepQueryAll('button', a)).find((b) => deepText(b).trim() === ${JSON.stringify(label)})`);
 try {
   if (expect === 'off') {
     // Without an assistant, and outside any host, no agent control appears anywhere: no launcher, no panel, no Ask.
@@ -91,34 +101,35 @@ try {
     for (const route of ROUTES) {
       await page.open(`${base}${route}`, { width: 1440 });
       await sleep(400);
-      const found = await page.eval<number>(`document.querySelectorAll('[data-assistant], button[aria-label="Assistant"], button[aria-label^="Ask: "]').length`);
+      const found = await page.eval<number>(`deepQueryAll('[data-assistant], button[aria-label="Assistant"], button[aria-label^="Ask: "]').length`);
       if (found) fail(`${route} has ${found} agent control(s) with no assistant and no host`);
     }
     ok(`${ROUTES.length} pages and views have no panel, no launcher and no Ask`);
     // The person's own findings do not depend on any agent.
     if (SAMPLE.overview) {
       await page.open(`${base}/`, { width: 1440 });
-      await until('the Overview finding', () => page.eval<boolean>(`[...document.querySelectorAll('[data-scroll-region] button')].some((b) => /usual on/.test(b.textContent))`), Boolean);
+      await until('the Overview finding', () => page.eval<boolean>(`deepQueryAll('button', ${CONTENT}).some((b) => /usual on/.test(deepText(b)))`), Boolean);
       ok('the Overview shows its finding with no assistant');
     } else na('the Overview shows its finding with no assistant', 'the sample Overview is not in this product');
     const status = (await fetch(`${base}/api/assistant`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{"messages":[]}' })).status;
     if (status !== 404) fail(`POST /api/assistant answered ${status}, expected 404`);
     ok('POST /api/assistant answers 404');
   } else {
-    const LAUNCHER = 'button[aria-label="Assistant"]';
-    const LAUNCH = `document.querySelector('${LAUNCHER}').click()`;
-    const panelOpen = () => page.eval<boolean>(`!!document.querySelector('aside[data-assistant]')`);
+    const LAUNCHER = `deepQuery('button[aria-label="Assistant"]')`;
+    const LAUNCH = `${LAUNCHER}.click()`;
+    const panelOpen = () => page.eval<boolean>(`!!${PANEL}`);
     const openPanel = async () => { await page.eval(LAUNCH); await until('the panel to open', panelOpen, Boolean); };
     const stored = () => page.eval<string | null>(`localStorage.getItem(${JSON.stringify(`${slug}.assistant`)})`);
     const here = () => page.eval<string>(`location.pathname`);
-    const cards = () => page.eval<{ text: string; buttons: string[] }[]>(`[...document.querySelectorAll('${PROPOSALS}')].map((a) => ({ text: a.textContent, buttons: [...a.querySelectorAll('button')].map((b) => b.textContent.trim()) }))`);
-    const follow = async (href: string) => { await press(`document.querySelector('aside[aria-label="Primary"] a[href="${href}"]')`); await until(`the address to be ${href}`, here, (p) => p === href); };
+    const cards = () => page.eval<{ text: string; buttons: string[] }[]>(`${PROPOSALS}.map((a) => ({ text: a.textContent, buttons: deepQueryAll('button', a).map((b) => deepText(b).trim()) }))`);
+    // The rail's link, as navigate.ts finds it: a link inside a nav, the one on screen.
+    const follow = async (href: string) => { await press(`deepQueryAll('nav a[href="${href}"]').find((a) => a.getBoundingClientRect().width > 0)`); await until(`the address to be ${href}`, here, (p) => p === href); };
     const recorded = async () => (await (await fetch(`${llm}/requests`)).json()) as { messages?: { role: string; content: unknown }[] }[];
     const LOCAL = `${slug}.assistant`;
     const ABOUT_PAGE = /^This is the .+ page\.$/;
 
     await page.open(`${base}${landing}`, { width: 1440 });
-    if (!(await page.eval<boolean>(`!!document.querySelector('${LAUNCHER}')`))) fail(`no launcher on ${landing}`);
+    if (!(await page.eval<boolean>(`!!${LAUNCHER}`))) fail(`no launcher on ${landing}`);
     ok(`the launcher is on ${landing}`);
 
     // The panel is a SEPARATE CHUNK, and this is what says so. The page is measured with the panel closed, then again
@@ -155,12 +166,13 @@ try {
       ok(`the model was given the Overview's view context: ${viewContext.length} characters, with the error rate's definition, the spike against its median and what nothing recorded explains`);
 
       // Handoff: Ask on a card posts its question into the panel as the person's, with the page's view context.
-      const askLabel = await page.eval<string>(`document.querySelector('[data-scroll-region] button[aria-label^="Ask: "]')?.getAttribute('aria-label') ?? ''`);
+      const ASK = `deepQuery('button[aria-label^="Ask: "]', ${CONTENT})`;
+      const askLabel = await page.eval<string>(`${ASK}?.getAttribute('aria-label') ?? ''`);
       if (!askLabel) fail('the Overview has no Ask on its featured card while the assistant is on');
       const question = askLabel.replace(/^Ask: /, '');
       const beforeAsk = (await recorded()).length;
-      await press(`document.querySelector('[data-scroll-region] button[aria-label^="Ask: "]')`);
-      await until('the asked question in the thread', () => page.eval<string[]>(`[...document.querySelectorAll('aside[data-assistant] [data-role="user"]')].map((m) => m.textContent)`), (ms) => ms.some((m) => m.includes(question)));
+      await press(ASK);
+      await until('the asked question in the thread', () => page.eval<string[]>(`deepQueryAll('[data-role="user"]', ${PANEL}).map((m) => m.textContent)`), (ms) => ms.some((m) => m.includes(question)));
       const asked = await until('the request carrying the question', async () => (await recorded()).slice(beforeAsk), (rs) => rs.some((r) => JSON.stringify(r.messages?.at(-1)).includes(question.slice(0, 40))));
       const askedSystem = String(asked.find((r) => JSON.stringify(r.messages?.at(-1)).includes(question.slice(0, 40)))?.messages?.find((m) => m.role === 'system')?.content ?? '');
       if (!askedSystem.includes('<view-context>')) fail('the question Ask posted reached the model without the view context');
@@ -177,9 +189,9 @@ try {
     // ELEMENTS, and the characters that made them are gone from the panel's text.
     await ask('Show me a markdown summary');
     const md = await until('the markdown reply', () => page.eval<{ list: number; bold: number; table: number; text: string }>(
-      `(() => { const b = [...document.querySelectorAll('aside[data-assistant] [data-assistant-text]')].at(-1);
-                return b ? { list: b.querySelectorAll('li').length, bold: b.querySelectorAll('strong').length,
-                             table: b.querySelectorAll('table').length, text: b.textContent } : { list: 0, bold: 0, table: 0, text: '' }; })()`),
+      `(() => { const b = deepQueryAll('[data-assistant-text]', ${PANEL}).at(-1);
+                return b ? { list: deepQueryAll('li', b).length, bold: deepQueryAll('strong', b).length,
+                             table: deepQueryAll('table', b).length, text: b.textContent } : { list: 0, bold: 0, table: 0, text: '' }; })()`),
       (v) => v.table > 0);
     if (!md.list || !md.bold) fail(`the markdown reply rendered ${md.list} list items and ${md.bold} bold runs`);
     if (md.text.includes('**') || md.text.includes('|---') || md.text.includes('| ---')) fail(`the markdown reply still shows its markup: "${md.text}"`);
@@ -192,8 +204,8 @@ try {
       await openPanel();
 
       // The table is newest-joined first at 20 a page, so the long-tenured members are on page 2: show 50 to read them all.
-      await press(`[...document.querySelectorAll('nav[aria-label="Pagination"] button')].find((b) => b.textContent.includes('per page'))`);
-      await press(`[...document.querySelectorAll('[role="menuitem"]')].find((i) => i.textContent.includes('50 per page'))`);
+      await press(`deepQueryAll('button', deepQuery('nav[aria-label="Pagination"]')).find((b) => deepText(b).includes('per page'))`);
+      await press(`deepQueryAll('[role="menuitem"]').find((i) => deepText(i).includes('50 per page'))`);
       await until('every member to show', () => row('Alice Moreno'), Boolean);
 
       await ask('Which Support viewers have been inactive for more than 60 days?');
@@ -205,7 +217,7 @@ try {
       await ask('Suspend them');
       await until('a Proposal to change two members', proposals, (t) => t.some((l) => l?.startsWith('Proposal from Assistant: Change 2 members')));
       // A second tab holds the Overview open, as a teammate would: the Activity line must reach it without a reload.
-      const watcher = SAMPLE.overview ? await launch() : null;
+      const watcher = SAMPLE.overview ? await browser() : null;
       await watcher?.open(`${base}/`, { width: 1440 });
       await decide('Approve');
       const suspended = await until('both rows to read Suspended', async () => [await row('Alice Moreno'), await row('Ravi Patel')], (r) => r.every((t) => t?.includes('Suspended')));
@@ -215,7 +227,7 @@ try {
       if (watcher) {
         // Provenance: the approved change left an Activity line naming the agent and the person it acted for.
         const object = 'status to Suspended for Alice Moreno and Ravi Patel';
-        const line = await until('the Activity line on the open Overview', () => watcher.eval<string>(`[...document.querySelectorAll('[data-scroll-region] li')].map((l) => l.textContent).find((t) => t.includes(${JSON.stringify(object)})) ?? ''`), Boolean);
+        const line = await until('the Activity line on the open Overview', () => watcher.eval<string>(`deepQueryAll('li', ${CONTENT}).map((l) => l.textContent).find((t) => t.includes(${JSON.stringify(object)})) ?? ''`), Boolean);
         watcher.close();
         if (!/^Assistant ?changed/.test(line.trim()) || !line.includes('for Maya Chen')) fail(`the Activity line does not name the Assistant and the person it acted for: "${line}"`);
         ok(`the open Overview's Activity showed "${line.replace(/\s+/g, ' ').trim()}" without a reload`);
@@ -229,9 +241,9 @@ try {
       if (!kept) fail('the dismissed removal took Alice Moreno out of the table');
       ok('the dismissed removal left Alice Moreno in the table');
 
-      await press(`document.querySelector('button[aria-label="Actions for Amara Okafor"]')`);
-      await until('the row menu', () => page.eval<boolean>(`!!document.querySelector('[role="menu"]')`), Boolean);
-      await press(`[...document.querySelectorAll('[role="menuitem"]')].find((i) => i.textContent.trim() === 'Suspend')`);
+      await press(`deepQuery('button[aria-label="Actions for Amara Okafor"]')`);
+      await until('the row menu', () => page.eval<boolean>(`!!deepQuery('[role="menu"]')`), Boolean);
+      await press(`deepQueryAll('[role="menuitem"]').find((i) => deepText(i).trim() === 'Suspend')`);
       await until('Amara Okafor to read Suspended', () => row('Amara Okafor'), (t) => !!t?.includes('Suspended'));
       await ask('Who is suspended?');
       const found = await until('the answer to name Amara Okafor', said, (t) => t.includes('Amara Okafor'));
@@ -254,10 +266,10 @@ try {
     if (to) {
       await follow(to);
       if (!(await panelOpen())) fail(`following the rail to ${to} closed the panel`);
-      const labels = () => page.eval<string[]>(`[...document.querySelectorAll('aside[data-assistant] span')].map((s) => s.textContent.trim()).filter((t) => t.startsWith('On '))`);
+      const labels = () => page.eval<string[]>(`deepQueryAll('span', ${PANEL}).map((s) => s.textContent.trim()).filter((t) => t.startsWith('On '))`);
       const tagged = await labels();
       if (!tagged.includes(`On ${fromTitle}`)) fail(`${to} shows the labels ${JSON.stringify(tagged)}, none "On ${fromTitle}"`);
-      if (!(await page.eval<boolean>(`document.querySelector('aside[data-assistant]').textContent.includes('Show me a markdown summary')`))) fail(`${to} lost the earlier messages`);
+      if (!(await page.eval<boolean>(`${PANEL}.textContent.includes('Show me a markdown summary')`))) fail(`${to} lost the earlier messages`);
       ok(`following the rail to ${to} kept the panel open with the earlier messages and their "On ${fromTitle}" labels (${tagged.length} labels)`);
     } else na('the thread across navigation', 'the rail has one route');
 
@@ -286,8 +298,8 @@ try {
     } else na('a waiting Proposal expiring on reload and on moving on', 'the sample Members and API keys pages are not both in this product');
 
     // Clear: the panel and the stored thread are both emptied.
-    await press(`document.querySelector('aside[data-assistant] button[aria-label="Clear conversation"]')`);
-    await until('the panel to empty', () => page.eval<number>(`document.querySelectorAll('aside[data-assistant] [data-role]').length`), (n) => n === 0);
+    await press(`deepQuery('button[aria-label="Clear conversation"]', ${PANEL})`);
+    await until('the panel to empty', () => page.eval<number>(`deepQueryAll('[data-role]', ${PANEL}).length`), (n) => n === 0);
     await until('the stored thread to go', stored, (v) => v === null);
     ok(`Clear conversation empties the panel and removes ${LOCAL} from local storage`);
 
@@ -297,8 +309,8 @@ try {
       await until('the reply', said, (t) => ABOUT_PAGE.test(t));
       await until('the thread to be stored', stored, (v) => !!v?.includes('What is this page?'));
       await follow('/settings');
-      const SWITCH = `(() => { const l = [...document.querySelectorAll('label')].find((x) => x.textContent.includes('Show the assistant')); return l && document.getElementById(l.htmlFor); })()`;
-      const absent = () => page.eval<boolean>(`!document.querySelector('${LAUNCHER}') && !document.querySelector('aside[data-assistant]')`);
+      const SWITCH = `deepQueryAll('label').find((x) => deepText(x).includes('Show the assistant'))?.control`;
+      const absent = () => page.eval<boolean>(`!${LAUNCHER} && !${PANEL}`);
       await press(SWITCH);
       await until('the launcher and panel to go from /settings', absent, Boolean);
       const elsewhere = SAMPLE.members ? '/members' : rail.find((r) => r !== '/settings' && r !== '/' && !r.startsWith('/system')) ?? landing;
@@ -308,16 +320,16 @@ try {
       // Switched off, the pages work as they would without any agent: no Ask anywhere, and the person's findings still there.
       if (SAMPLE.overview) {
         await page.open(`${base}/`, { width: 1440 });
-        await until('the Overview to render its finding', () => page.eval<boolean>(`[...document.querySelectorAll('[data-scroll-region] button')].some((b) => /usual on/.test(b.textContent))`), Boolean);
-        if (await page.eval<boolean>(`!!document.querySelector('button[aria-label^="Ask: "]')`)) fail('the Overview shows Ask with the assistant switched off');
+        await until('the Overview to render its finding', () => page.eval<boolean>(`deepQueryAll('button', ${CONTENT}).some((b) => /usual on/.test(deepText(b)))`), Boolean);
+        if (await page.eval<boolean>(`!!deepQuery('button[aria-label^="Ask: "]')`)) fail('the Overview shows Ask with the assistant switched off');
         if (!(await absent())) fail('/ still shows the assistant with the switch off');
       }
       await page.open(`${base}/settings`, { width: 1440 });
       if (!(await absent())) fail('/settings still shows the assistant with the switch off');
       await press(SWITCH);
-      await until('the launcher to return', () => page.eval<boolean>(`!!document.querySelector('${LAUNCHER}')`), Boolean);
+      await until('the launcher to return', () => page.eval<boolean>(`!!${LAUNCHER}`), Boolean);
       await openPanel();
-      await until('the thread to return', () => page.eval<boolean>(`document.querySelector('aside[data-assistant]').textContent.includes('What is this page?')`), Boolean);
+      await until('the thread to return', () => page.eval<boolean>(`${PANEL}.textContent.includes('What is this page?')`), Boolean);
       ok(`Show the assistant off hides the launcher on /settings and ${elsewhere}${SAMPLE.overview ? ' and / and every Ask, keeps the Overview\'s finding' : ''} and the thread; on brings the launcher and the thread back`);
     } else {
       na('the Settings switch', 'the sample Settings page, which holds "Show the assistant", is not in this product');
@@ -325,14 +337,14 @@ try {
 
     // Layout: a column beside the page at 1440px, over it at 390px; Escape closes it.
     if (!(await panelOpen())) await openPanel();
-    const geometry = () => page.eval<{ position: string; main: number; panel: number; width: number }>(`(() => { const a = document.querySelector('aside[data-assistant]'); return { position: getComputedStyle(a).position, main: Math.round(document.querySelector('main').getBoundingClientRect().right), panel: Math.round(a.getBoundingClientRect().left), width: innerWidth }; })()`);
+    const geometry = () => page.eval<{ position: string; main: number; panel: number; width: number }>(`(() => { const a = ${PANEL}; return { position: getComputedStyle(a).position, main: Math.round(document.querySelector('main').getBoundingClientRect().right), panel: Math.round(a.getBoundingClientRect().left), width: innerWidth }; })()`);
     const wide = await geometry();
     if (wide.position === 'fixed' || Math.abs(wide.main - wide.panel) > 1) fail(`at 1440px the panel is ${wide.position} with the page ending at ${wide.main}px and the panel starting at ${wide.panel}px`);
     await page.open(`${base}${landing}`, { width: 390 });
     await openPanel();
     const narrow = await geometry();
     if (narrow.position !== 'fixed' || narrow.main !== narrow.width || narrow.panel >= narrow.main) fail(`at 390px the panel is ${narrow.position}, the page ends at ${narrow.main}px and the panel starts at ${narrow.panel}px`);
-    await page.eval(`document.querySelector('${MESSAGE}').focus()`);
+    await page.eval(`${MESSAGE}.focus()`);
     for (const type of ['keyDown', 'keyUp'] as const) await page.send('Input.dispatchKeyEvent', { type, key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 });
     await until('Escape to close the panel', panelOpen, (v) => !v);
     ok(`at 1440px the panel is a column (page ends at ${wide.main}px, panel starts at ${wide.panel}px); at 390px it is fixed over the page; Escape closes it`);
@@ -342,9 +354,9 @@ try {
     await page.eval(`(() => { window.__api = []; const f = window.fetch; window.fetch = async (...a) => { const r = await f(...a); if (String(a[0]).includes('/api/assistant')) r.clone().text().then((t) => window.__api.push(t)); return r; }; })()`);
     await openPanel();
     await ask('Please fail now');
-    const panelText = () => page.eval<string>(`document.querySelector('aside[data-assistant]').textContent`);
+    const panelText = () => page.eval<string>(`${PANEL}.textContent`);
     await until('the failure to show', panelText, (t) => t.includes('The assistant is not set up correctly'));
-    if (!(await page.eval<boolean>(`[...document.querySelectorAll('aside[data-assistant] button')].some((b) => b.textContent.trim() === 'Retry')`))) fail('the failure offers no Retry');
+    if (!(await page.eval<boolean>(`deepQueryAll('button', ${PANEL}).some((b) => deepText(b).trim() === 'Retry')`))) fail('the failure offers no Retry');
     if ((await panelText()).includes(key!)) fail('the panel shows the key');
     ok('a refused key shows "The assistant is not set up correctly" with Retry');
     const seen = await page.eval<string[]>(`window.__api`);

package/payload/scripts/contrast.ts

@@ -9,55 +9,7 @@
  */
 import { load, resolver, tokensOf, cssValue, NS } from './tokens.ts';
 import { parse, over, ratio, simulate, deltaE, oklchOf, hex } from '../src/lib/color.ts';
-
-const TEXT = 4.5, UI = 3;
-type Pair = [fg: string, bg: string | string[], min: number, what: string];
-
-const PAIRS: Pair[] = [
-  ['ink', 'ground', TEXT, 'body text on the page'],
-  ['ink', 'surface', TEXT, 'body text in a card'],
-  ['ink', 'surface-raised', TEXT, 'text in a menu or dialog'],
-  ['ink-2', 'ground', TEXT, 'secondary copy on the page'],
-  ['ink-2', 'surface', TEXT, 'secondary copy and inactive navigation'],
-  ['ink-2', 'surface-sunk', TEXT, 'a segmented option at rest'],
-  ['ink-2', ['frame'], TEXT, 'inactive navigation in the rail'],
-  ['ink-3', ['frame'], TEXT, 'a group label in the rail'],
-  ['accent-ink', ['frame', 'accent-tint'], TEXT, 'the active navigation label in the rail'],
-  ['ink-3', 'ground', TEXT, 'captions on the page'],
-  ['ink-3', 'surface', TEXT, 'axis ticks, captions and placeholders in a card'],
-  ['ink-3', 'surface-sunk', TEXT, 'a table head'],
-  ['ink-3', 'surface-raised', TEXT, 'a shortcut hint in a menu'],
-  ['ink', ['surface', 'fill-hover'], TEXT, 'a row under the pointer'],
-  ['ink-inverse', 'surface-inverse', TEXT, 'tooltip text'],
-  ['on-accent', 'accent', TEXT, 'primary button label'],
-  ['on-accent', 'accent-hover', TEXT, 'primary button label on hover'],
-  ['accent-ink', 'surface', TEXT, 'an inline link in a card'],
-  ['accent-ink', 'ground', TEXT, 'an inline link on the page'],
-  ['accent-ink', ['surface', 'accent-tint'], TEXT, 'the active navigation label'],
-  ['ink', ['surface', 'accent-tint'], TEXT, 'a selected row'],
-  ['ink-2', ['surface', 'accent-tint'], TEXT, 'muted text in a selected row or on an accent wash (ink-3 is not enough there)'],
-  ['ink-2', ['surface', 'fill-track'], TEXT, 'a count on an inactive tab'],
-  ['positive-ink', 'surface', TEXT, 'an improving delta'],
-  ['positive-ink', ['surface', 'positive-tint'], TEXT, 'a positive badge'],
-  ['warning-ink', 'surface', TEXT, 'a warning message'],
-  ['warning-ink', ['surface', 'warning-tint'], TEXT, 'a warning badge'],
-  ['critical-ink', 'surface', TEXT, 'an error message'],
-  ['critical-ink', 'ground', TEXT, 'an error under a field on the page'],
-  ['critical-ink', ['surface', 'critical-tint'], TEXT, 'a critical badge'],
-  ['on-critical', 'critical-fill', TEXT, 'the destructive button label'],
-  ['accent', 'surface', UI, 'focus ring, active marker and the highlighted mark in a card'],
-  ['accent', 'ground', UI, 'focus ring on the page'],
-  ['line-control', 'surface', UI, 'a checkbox or radio at rest'],
-  ['positive', 'surface', UI, 'a positive status dot'],
-  ['warning', 'surface', UI, 'a warning status dot'],
-  ['critical', 'surface', UI, 'a critical status dot'],
-  ['chart-neutral-strong', 'surface', UI, 'a neutral comparison line'],
-  ['series-1', 'surface', UI, 'chart slot 1'],
-  ['series-2', 'surface', UI, 'chart slot 2'],
-  ['series-3', 'surface', UI, 'chart slot 3'],
-  ['series-4', 'surface', UI, 'chart slot 4'],
-  ['series-6', 'surface', UI, 'chart slot 6'],
-];
+import { PAIRS } from './lib/contrast-pairs.ts';
 
 /** Every custom property of one context, as raw CSS strings. */
 function context(theme: string, accent: string): Record<string, string> {

package/payload/scripts/lib/chrome.ts

@@ -102,6 +102,9 @@ async function attach(proc: ChildProcess, dir: string, handle: { proc: ChildProc
       await send('Emulation.setTouchEmulationEnabled', width < 600 ? { enabled: true, maxTouchPoints: 5 } : { enabled: false });
       await send('Page.navigate', { url });
       await sleep(wait);
+      // Then its load event: on a busy machine a page can still be loading after any fixed wait, and a suite reading it then
+      // reads a page that is not all there. Bounded, so a page whose load never ends still opens.
+      await page.eval('new Promise((r) => { if (document.readyState === "complete") return r(true); addEventListener("load", () => r(true), { once: true }); setTimeout(() => r(false), 25000); })');
       await page.eval('Promise.race([document.fonts.ready.then(() => true), new Promise((r) => setTimeout(() => r(false), 4000))])');
     },
     async shot(file, { full = false, width, height } = {}) {

package/payload/scripts/lib/contrast-pairs.ts

@@ -0,0 +1,53 @@
+/**
+ * Every foreground the specifications put on a background, with the contrast it needs: text 4.5:1; focus rings,
+ * control outlines and chart marks 3:1 (WCAG 1.4.11). A background given as a list is composited in order over the
+ * ground. Pure data, so the contrast gate and the Atlas's colour page measure the same pairs.
+ */
+export const TEXT = 4.5, UI = 3;
+export type Pair = [fg: string, bg: string | string[], min: number, what: string];
+
+export const PAIRS: Pair[] = [
+  ['ink', 'ground', TEXT, 'body text on the page'],
+  ['ink', 'surface', TEXT, 'body text in a card'],
+  ['ink', 'surface-raised', TEXT, 'text in a menu or dialog'],
+  ['ink-2', 'ground', TEXT, 'secondary copy on the page'],
+  ['ink-2', 'surface', TEXT, 'secondary copy and inactive navigation'],
+  ['ink-2', 'surface-sunk', TEXT, 'a segmented option at rest'],
+  ['ink-2', ['frame'], TEXT, 'inactive navigation in the rail'],
+  ['ink-3', ['frame'], TEXT, 'a group label in the rail'],
+  ['accent-ink', ['frame', 'accent-tint'], TEXT, 'the active navigation label in the rail'],
+  ['ink-3', 'ground', TEXT, 'captions on the page'],
+  ['ink-3', 'surface', TEXT, 'axis ticks, captions and placeholders in a card'],
+  ['ink-3', 'surface-sunk', TEXT, 'a table head'],
+  ['ink-3', 'surface-raised', TEXT, 'a shortcut hint in a menu'],
+  ['ink', ['surface', 'fill-hover'], TEXT, 'a row under the pointer'],
+  ['ink-inverse', 'surface-inverse', TEXT, 'tooltip text'],
+  ['on-accent', 'accent', TEXT, 'primary button label'],
+  ['on-accent', 'accent-hover', TEXT, 'primary button label on hover'],
+  ['accent-ink', 'surface', TEXT, 'an inline link in a card'],
+  ['accent-ink', 'ground', TEXT, 'an inline link on the page'],
+  ['accent-ink', ['surface', 'accent-tint'], TEXT, 'the active navigation label'],
+  ['ink', ['surface', 'accent-tint'], TEXT, 'a selected row'],
+  ['ink-2', ['surface', 'accent-tint'], TEXT, 'muted text in a selected row or on an accent wash (ink-3 is not enough there)'],
+  ['ink-2', ['surface', 'fill-track'], TEXT, 'a count on an inactive tab'],
+  ['positive-ink', 'surface', TEXT, 'an improving delta'],
+  ['positive-ink', ['surface', 'positive-tint'], TEXT, 'a positive badge'],
+  ['warning-ink', 'surface', TEXT, 'a warning message'],
+  ['warning-ink', ['surface', 'warning-tint'], TEXT, 'a warning badge'],
+  ['critical-ink', 'surface', TEXT, 'an error message'],
+  ['critical-ink', 'ground', TEXT, 'an error under a field on the page'],
+  ['critical-ink', ['surface', 'critical-tint'], TEXT, 'a critical badge'],
+  ['on-critical', 'critical-fill', TEXT, 'the destructive button label'],
+  ['accent', 'surface', UI, 'focus ring, active marker and the highlighted mark in a card'],
+  ['accent', 'ground', UI, 'focus ring on the page'],
+  ['line-control', 'surface', UI, 'a checkbox or radio at rest'],
+  ['positive', 'surface', UI, 'a positive status dot'],
+  ['warning', 'surface', UI, 'a warning status dot'],
+  ['critical', 'surface', UI, 'a critical status dot'],
+  ['chart-neutral-strong', 'surface', UI, 'a neutral comparison line'],
+  ['series-1', 'surface', UI, 'chart slot 1'],
+  ['series-2', 'surface', UI, 'chart slot 2'],
+  ['series-3', 'surface', UI, 'chart slot 3'],
+  ['series-4', 'surface', UI, 'chart slot 4'],
+  ['series-6', 'surface', UI, 'chart slot 6'],
+];