zz-meridian 0.12.0 → 0.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "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,20 @@
 
 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.2] · 2026-10-09
+
+### Fixed
+
+- **A `navigationChecks` control inside a web component is pressable once its page has hydrated.** On a Next page the navigation check counted a control as ready only when the control itself carried React's marker; React never renders into a shadow root, so a control inside one (a design system's input or button) was never ready and the check failed `never-ready`. Readiness is now its rendering host's.
+
+## [0.12.1] · 2026-10-09
+
+### Fixed
+
+- **A web component's button named by its slotted text is no longer reported `unnamed:`.** The audit read a control's name from its own text, which for the native button inside a web component's shadow root leaves out the text slotted into its host, so a labelled design-system button was reported as unnamed. Names now count slotted text (`deepText` in `scripts/lib/deep.ts`), and the presses and the keyboard walk name such controls by it too.
+- **The browser checks wait up to 30 s for Chrome to start.** A cold Chrome on a busy machine or runner could take longer than the 12 s they allowed and fail a check with `Chrome did not start`; a Chrome that exits instead is now reported at once, with its exit code.
+- **A test may take 30 s.** On a loaded machine or a slow runner a correct jsdom case could pass vitest's default 5 s in the gate's parallel files; `vitest.config.ts` now allows 30 s. A project made before this keeps its own `vitest.config.ts`: add `testTimeout: 30_000` to its `test` block if its gate times out on correct cases.
+
 ## [0.12.0] · 2026-10-09
 
 ### Added

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "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

@@ -122,7 +122,7 @@ const MEASURE = `(() => {
     // 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 && !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 && el.getRootNode().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') || deepText(el).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.
@@ -165,7 +165,7 @@ const run = async (route: string, width: number, theme: string, embed: boolean)
   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');
+    if (!(await page.eval<boolean>(`${DEEP_SOURCE}\n;typeof deepAll === 'function' && typeof deepActive === 'function' && typeof deepParent === 'function' && typeof deepText === '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();

package/payload/scripts/interactions.ts

@@ -38,7 +38,7 @@ const LIST = `(() => {
   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); 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(' > ') + ')' : ''); }),
+    controls: all.map((b, i) => { b.setAttribute('data-press', i); const h = hosts(b); return (b.getAttribute('aria-label') || deepText(b) || 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')),
   };
 })()`;
@@ -82,7 +82,7 @@ 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');
+    if (!(await page.eval<boolean>(`${DEEP_SOURCE}\n;typeof deepAll === 'function' && typeof deepParent === 'function' && typeof deepQuery === 'function' && typeof deepText === '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();

package/payload/scripts/keyboard.ts

@@ -48,7 +48,7 @@ const TAG = `(() => {
   const all = every.filter((el) => el.matches('a[href], button:not(:disabled), input:not([type=hidden]):not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])'))
     .filter((el) => vis(el) && el.tabIndex >= 0);
   const hosts = (el) => { const out = []; for (let r = el.getRootNode(); r instanceof ShadowRoot; r = r.host.getRootNode()) out.unshift(r.host.localName); return out; };
-  window.__kbName = (el) => { const h = hosts(el); return (el.getAttribute('aria-label') || el.textContent || el.getAttribute('placeholder') || el.tagName).trim().replace(/\\s+/g, ' ').slice(0, 40) + (h.length ? ' (in ' + h.join(' > ') + ')' : ''); };
+  window.__kbName = (el) => { const h = hosts(el); return (el.getAttribute('aria-label') || deepText(el).trim() || el.getAttribute('placeholder') || el.tagName).trim().replace(/\\s+/g, ' ').slice(0, 40) + (h.length ? ' (in ' + h.join(' > ') + ')' : ''); };
   // A stop's identity: its tag, or, for a control the tagging did not list (a roving group hands the tab stop to a member that was
   // not tabbable when the page was tagged), a mark of its own, so a stop is the same stop forward and back.
   window.__kbN = 0; window.__kbId = (el) => el.getAttribute('data-kb') ?? (el.__kbU ??= 'u' + (++window.__kbN));
@@ -117,7 +117,7 @@ for (const route of ROUTES) {
   await page.open(base + route, { width: 1440, height: 900, theme: 'dark', wait: 2500 });
   // One implementation of the walk: the helper is injected, never copied. A page it cannot be injected into fails the suite.
   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');
+    if (!(await page.eval<boolean>(`${DEEP_SOURCE}\n;typeof deepAll === 'function' && typeof deepActive === 'function' && typeof deepParent === 'function' && typeof deepText === 'function'`))) throw new Error('the helper is not defined after injection');
   } catch (e) {
     console.error(`keyboard: cannot inject the deep-DOM helper into ${route}: ${(e as Error).message}`);
     page.close();

package/payload/scripts/lib/chrome.ts

@@ -49,13 +49,16 @@ export async function launch(): Promise<Page> {
 
 async function attach(proc: ChildProcess, dir: string, handle: { proc: ChildProcess; dir: string }): Promise<Page> {
   let list: any[] | undefined;
-  for (let i = 0; i < 80 && !list; i++) {
+  // A cold Chrome on a busy machine or runner can take well over ten seconds to open its debugging port; wait up to 30 s,
+  // and stop at once if it exited instead.
+  const deadline = Date.now() + 30_000;
+  while (!list && Date.now() < deadline && proc.exitCode === null && proc.signalCode === null) {
     try {
       const port = fs.readFileSync(path.join(dir, 'DevToolsActivePort'), 'utf8').split('\n')[0];
       list = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();
     } catch { await sleep(150); }
   }
-  if (!list) throw new Error('Chrome did not start');
+  if (!list) throw new Error(proc.exitCode !== null || proc.signalCode !== null ? `Chrome exited before it started (${proc.exitCode ?? proc.signalCode})` : 'Chrome did not start within 30 s');
   const ws = new WebSocket(list.find((t) => t.type === 'page').webSocketDebuggerUrl);
   await new Promise((r) => ws.addEventListener('open', r));
   let id = 0;

package/payload/scripts/lib/deep.ts

@@ -2,10 +2,10 @@
  * The deep-DOM helper: one implementation of "every element of the page", for the browser suites.
  *
  * `document.querySelectorAll('*')` stops at a shadow root, so a suite built on it never sees a custom element's own
- * content. These four functions walk through open shadow roots and slots instead. Every suite injects `DEEP_SOURCE`
+ * content. These five functions walk through open shadow roots and slots instead. Every suite injects `DEEP_SOURCE`
  * (the same code as a string) into the page, so there is one implementation, not a copy per suite:
  *
- *   await page.eval(DEEP_SOURCE);                       // once per page load, defines the four functions as globals
+ *   await page.eval(DEEP_SOURCE);                       // once per page load, defines the five functions as globals
  *   await page.eval(`deepAll().length`);                // then call them in any later expression
  *
  * Supported boundary:
@@ -70,5 +70,23 @@ export function deepParent(el: Element): Element | null {
   return top instanceof ShadowRoot ? top.host : null;
 }
 
-/** The four functions as page code, for `page.eval`: function declarations, so they become globals of the page. */
-export const DEEP_SOURCE: string = [deepAll, deepActive, deepQuery, deepParent].map((f) => f.toString()).join('\n');
+/**
+ * An element's text as rendered: a slot contributes the text of what is assigned to it, or its fallback content when
+ * nothing is. A web component's button is usually named by the text slotted into its host, which `textContent` of the
+ * button inside the root does not include.
+ */
+export function deepText(el: Element): string {
+  let out = '';
+  for (const n of el.childNodes) {
+    if (n.nodeType === 3) out += n.textContent ?? '';
+    else if (n instanceof HTMLSlotElement) {
+      const assigned = n.assignedNodes({ flatten: true });
+      if (!assigned.length) out += deepText(n);
+      else for (const a of assigned) out += a.nodeType === 3 ? (a.textContent ?? '') : a instanceof Element ? deepText(a) : '';
+    } else if (n instanceof Element) out += deepText(n);
+  }
+  return out;
+}
+
+/** The five functions as page code, for `page.eval`: function declarations, so they become globals of the page. */
+export const DEEP_SOURCE: string = [deepAll, deepActive, deepQuery, deepParent, deepText].map((f) => f.toString()).join('\n');

package/payload/scripts/navigate.ts

@@ -189,7 +189,10 @@ const INSTRUMENT = `${DEEP_SOURCE}\n${DEEP_MATCHES}\n(() => {
  * press before hydration does nothing. Null when there is none.
  */
 const pickable = (selector: string) => `(() => {
-  const hydrated = typeof self.__next_f === 'undefined' ? () => true : (el) => Object.keys(el).some((k) => k.startsWith('__reactProps$'));
+  // React marks what it rendered once it hydrates; it never renders into a shadow root, so a control inside one is ready
+  // when the host React rendered is.
+  const rendered = (el) => { let n = el; while (n.getRootNode() instanceof ShadowRoot) n = n.getRootNode().host; return n; };
+  const hydrated = typeof self.__next_f === 'undefined' ? () => true : (el) => Object.keys(rendered(el)).some((k) => k.startsWith('__reactProps$'));
   return deepMatches(${JSON.stringify(selector)}).find((el) => {
     const r = el.getBoundingClientRect();
     return r.width > 0 && r.height > 0 && getComputedStyle(el).visibility !== 'hidden' && hydrated(el);

package/payload/skills/zz-meridian/references/validation.md

@@ -89,7 +89,7 @@ and supply-chain check before a script runs; that is pnpm, not an install, and n
 |---|---|---|
 | `sideways: scroll region 1042 > 768` | Something wider than the window | A table with too many columns: `hideBelow` on low-value ones; a long id: `truncate` with a `title`; a fixed width: use `min-w-0` and fractions |
 | `clipped: … "text"` | Text cut without an ellipsis | Give the element `truncate`, or let it wrap; never shrink the type |
-| `unnamed: button…` | An icon-only control | `aria-label` on it (Icon button requires one) |
+| `unnamed: button…` | An icon-only control (a web component's button counts the text slotted into its host as its name) | `aria-label` on it (Icon button requires one) |
 | `scrollers: …` | A card scrolls on its own | Page the list (`DataTable` pages at 20) or cap it ("top 5"); only the page scrolls |
 | `contrast: 3.1:1 … "text"` | Text below 4.5:1 | Use `ink`, `ink-2` or `ink-3` on surfaces; status text uses `*-ink`, never the fill colour |
 | `no focus ring: …` | A control with `outline-none` and no ring, or one whose outline, shadow or border is the same with and without focus | Remove `outline-none`, or add `focus-visible:outline-2 focus-visible:outline-accent`. A ring painted permanently is not a focus ring; a specimen that depicts the focus state is drawn inert (`State` with `still`) |

package/payload/tests/assistant-settings.test.tsx

@@ -34,10 +34,11 @@ describe('the person\'s switch', () => {
     await settings(true);
     const toggle = screen.getByRole('switch', { name: /Show the assistant/ });
     expect(toggle).toBeChecked();
-    // The assistant's code loads on demand (next/dynamic), so the launcher and the panel arrive a moment later.
-    await waitFor(() => expect(launcher()).not.toBeNull());
+    // The assistant's code loads on demand (next/dynamic), so the launcher and the panel arrive a moment later; the
+    // first import of the panel is the slowest step of the suite under a busy gate, so these two waits allow 20 s.
+    await waitFor(() => expect(launcher()).not.toBeNull(), { timeout: 20_000 });
     fireEvent.click(launcher()!);
-    await waitFor(() => expect(document.querySelector('[data-assistant]')).not.toBeNull());
+    await waitFor(() => expect(document.querySelector('[data-assistant]')).not.toBeNull(), { timeout: 20_000 });
     fireEvent.click(toggle);
     await waitFor(() => expect(launcher()).toBeNull());
     expect(document.querySelector('[data-assistant]')).toBeNull();

package/payload/tests/chrome-cleanup.test.ts

@@ -23,4 +23,13 @@ describe('scripts/lib/chrome.ts launch', () => {
     expect(alive()).toBe(false);
     expect(fs.existsSync(fs.readFileSync(path.join(work, 'dir'), 'utf8').trim())).toBe(false);
   }, 60_000);
+
+  it('says at once that a browser which exited never started, without waiting out the start-up deadline', () => {
+    const fake = path.join(work, 'chrome-exits');
+    fs.writeFileSync(fake, '#!/bin/sh\nexit 3\n', { mode: 0o755 });
+    const started = Date.now();
+    const run = spawnSync(process.execPath, ['--input-type=module', '-e', `import { launch } from './scripts/lib/chrome.ts'; try { await launch(); } catch (e) { console.log(e.message); }`], { cwd: ROOT, env: { ...process.env, CHROME: fake }, encoding: 'utf8' });
+    expect(run.stdout).toContain('Chrome exited before it started (3)');
+    expect(Date.now() - started).toBeLessThan(15_000);
+  }, 60_000);
 });

package/payload/tests/members-optimistic.test.tsx

@@ -5,8 +5,6 @@ vi.mock('next/navigation', () => ({ usePathname: () => '/members', useRouter: ()
 const toasts = vi.hoisted(() => [] as { tone: string; title: string; description?: string }[]);
 vi.mock('@/components/ui/toast', () => ({ toast: (t: { tone: string; title: string; description?: string }) => { toasts.push(t); } }));
 vi.stubGlobal('IntersectionObserver', class { observe() {} unobserve() {} disconnect() {} });
-// Each case renders a whole view and drives its sheet: on a loaded 4-CPU runner one can pass the 5 s default.
-vi.setConfig({ testTimeout: 15_000 });
 
 import { KeysView } from '@/views/keys';
 import { MembersView, type Result } from '@/views/members';

package/payload/vitest.config.ts

@@ -5,5 +5,7 @@ import path from 'node:path';
 export default defineConfig({
   plugins: [react()],
   resolve: { alias: { '@': path.resolve(import.meta.dirname, 'src') } },
-  test: { environment: 'jsdom', setupFiles: ['./tests/setup.ts'], include: ['tests/**/*.test.{ts,tsx}'] },
+  // The gate runs the files in parallel; on a loaded machine or a slow runner a jsdom case that takes a second alone can
+  // pass vitest's default 5 s and fail a correct tree. The timeout says how long a case may take, not what it proves.
+  test: { environment: 'jsdom', setupFiles: ['./tests/setup.ts'], include: ['tests/**/*.test.{ts,tsx}'], testTimeout: 30_000 },
 });