@fasl-work/caos-app-shell 0.6.13 → 0.7.0

package/dist/keys-CnvqkckF.d.ts

@@ -0,0 +1,135 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { B as BiText } from './text-BlY47nIt.js';
+
+interface ArchTab {
+    id: string;
+    /** tab label. */
+    en: string;
+    es: string;
+    /** the explanation body (paragraphs separated by a blank line). */
+    body_en: string;
+    body_es: string;
+    /**
+     * an inline '<svg…>…</svg>' string (import it with `?raw`); a URL is refused, because an `<img>` or a fetched
+     * file cannot read the page's theme tokens and a path goes stale (S11).
+     *
+     * ONE file carries BOTH languages (ADR-0058). Tag each translatable `<text>` twice at the same
+     * coordinates, `class="… l-en"` and `class="… l-es"`; the modal wrapper sets `data-arch-lang`
+     * and the shell stylesheet shows exactly one. Two files would be two things to keep in step, and
+     * the one that is not on screen is the one that goes stale. Anything language-neutral (a number,
+     * a file name, an identifier) needs no pair.
+     */
+    svg: string;
+}
+interface ArchitectureConfig {
+    /** modal title override (defaults to "Architecture / How it works"). */
+    title_en?: string;
+    title_es?: string;
+    tabs: ArchTab[];
+}
+/**
+ * Problems with an architecture configuration, one string each (ADR-0058, ADR-0078). The diagram must be an INLINE
+ * SVG string (a fetched or `<img>` file cannot be checked against the theme tokens before it is shown, failure class
+ * 14); every `var(--x)` it names must be a shell token (an undefined token renders as nothing, silently, failure
+ * class 25); a hex colour does not follow the theme; both languages are required; at least five tabs.
+ */
+declare function validateArchitectureConfig(config: ArchitectureConfig): string[];
+declare function ArchitectureModal({ config, onClose }: {
+    config: ArchitectureConfig;
+    onClose: () => void;
+}): react.JSX.Element | null;
+
+interface ShellRoute {
+    path: string;
+    en: string;
+    es: string;
+}
+interface ShellConfig {
+    /** Brand: product name + optional lucide icon element (defaults to a generic mark). */
+    product: {
+        name: string;
+        mark?: ReactNode;
+    };
+    /** Top-level routes for the header nav (use `STANDARD_ROUTES`). 0 or 1 entries hide the nav (a hub). */
+    routes?: ShellRoute[];
+    /** External links. personal/portfolio default to Felipe's canonical URLs (kept identical app-to-app). */
+    links: {
+        github: string;
+        personal?: string;
+        portfolio?: string;
+    };
+    /** Display version `X.XX.XXX`, read from the repo's VERSION (ADR-0068); a semver form is reported. */
+    version: string;
+    /** Short commit SHA of the build, printed after the version so the deployed build is identifiable. */
+    build?: string;
+    /** The product's licence as the footer shows it. Required: the shell's own licence is not inherited, and a
+     * default "MIT · open source" once appeared on private products (failure class 16). */
+    license: BiText;
+    /** Repository visibility. A private product shows no source link in the header or the footer. */
+    visibility: 'public' | 'private';
+    /** In-app Architecture / "How it works" modal (ADR-0058). When present, an info button appears in the header. */
+    architecture?: ArchitectureConfig;
+    /** Footer provenance + honesty (ADR-0016 s2): the real data/engine source with citation + licence, and the
+     * one-line honest disclaimer of how the app runs. */
+    footer?: {
+        /** Explicit product attribution, or false when the product excludes personal attribution. */
+        attribution?: {
+            en: string;
+            es: string;
+        } | false;
+        /** @deprecated use `ShellConfig.license`. */
+        license?: {
+            en: string;
+            es: string;
+        };
+        provenance?: {
+            en: string;
+            es: string;
+        };
+        disclaimer?: {
+            en: string;
+            es: string;
+        };
+    };
+    /** Routes whose surface IS the viewport (ADR-0071 rule 1), matched exactly or by prefix for a non-root path. */
+    fixedRoutes?: string[];
+    /** Every route fixed: a single-surface app (a hub, a one-page tool). */
+    fixed?: boolean;
+    /**
+     * Every route is the viewport (ADR-0071 rule 1, as amended 2026-10-04): the workbench (`WorkbenchLayout`) fills
+     * it, and a documentation route scrolls INSIDE the main container, so the header and footer stay in view and the
+     * document itself never scrolls. The configuration the product template uses.
+     */
+    contain?: boolean;
+}
+/** The shared CAOS/Faena app shell: sticky header (brand + nav + icon-links + lang/theme) + footer.
+ * Wrap your <Routes> (or single landing) in it, inside a Router. */
+declare function AppShell({ config, children }: {
+    config: ShellConfig;
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * The six routes every CAOS product carries, in this order (ADR-0016 s3, ADR-0069 s7, the product quality bar):
+ * the App (the tool, landing) and the five documentation routes. One definition, so the header, the router and the
+ * gate read the same list and no product retypes it.
+ */
+declare const STANDARD_ROUTES: ShellRoute[];
+
+/**
+ * The storage keys the shell reads and writes. Exported (and built as their own entry, `dist/keys.js`) so the
+ * measured gate sets the theme and the language exactly the way the shell reads them, instead of guessing the
+ * key names (failure class 10 of the 2026-10-04 history: gates that measured the wrong mode).
+ */
+declare const THEME_STORAGE_KEY = "caos.theme";
+declare const LANG_STORAGE_KEY = "caos.lang";
+/**
+ * The pre-paint script for index.html (inline, before the bundle): applies the stored or preferred theme and the
+ * stored language before the first frame, so a light-theme user never sees a dark flash and the document language
+ * is right from the start (ADR-0011, ADR-0012). Built from the keys above, so the two cannot drift; exported from
+ * this React-free entry so a build config can inline it.
+ */
+declare const THEME_BOOT_SCRIPT: string;
+
+export { AppShell as A, LANG_STORAGE_KEY as L, STANDARD_ROUTES as S, THEME_BOOT_SCRIPT as T, type ArchTab as a, type ArchitectureConfig as b, ArchitectureModal as c, type ShellConfig as d, type ShellRoute as e, THEME_STORAGE_KEY as f, validateArchitectureConfig as v };

package/dist/keys.d.ts

@@ -0,0 +1,4 @@
+export { L as LANG_STORAGE_KEY, S as STANDARD_ROUTES, T as THEME_BOOT_SCRIPT, f as THEME_STORAGE_KEY } from './keys-CnvqkckF.js';
+import 'react';
+import './text-BlY47nIt.js';
+import 'zustand';

package/dist/keys.js

@@ -0,0 +1 @@
+export { LANG_STORAGE_KEY, STANDARD_ROUTES, THEME_BOOT_SCRIPT, THEME_STORAGE_KEY } from './chunk-X6Y5CDUD.js';

package/dist/text-BlY47nIt.d.ts

@@ -0,0 +1,21 @@
+import * as zustand from 'zustand';
+
+type Lang = 'en' | 'es';
+interface LangState {
+    lang: Lang;
+    setLang: (l: Lang) => void;
+    toggle: () => void;
+}
+declare const useLangStore: zustand.UseBoundStore<zustand.StoreApi<LangState>>;
+/** Current language, for app pages that render language-branched long-form content. */
+declare const useShellLang: () => Lang;
+
+/** A string shown to users: one language-neutral string (a number, a code, a name) or both languages. */
+type BiText = string | {
+    en: string;
+    es: string;
+};
+/** The text for the current language. English is the canonical fallback (ADR-0011). */
+declare function pick(text: BiText | undefined, lang: Lang): string;
+
+export { type BiText as B, type Lang as L, useShellLang as a, pick as p, useLangStore as u };

package/dist/tokens-BCqyHYx2.d.ts

@@ -0,0 +1,40 @@
+import { L as Lang } from './text-BlY47nIt.js';
+
+interface FormatOptions {
+    /** Significant digits for a value below 10^(digits-1) (default 4); a larger value shows every integer digit, so a
+     * count is never rounded (27345 people, not 27,350). Ignored when `decimals` is set. */
+    digits?: number;
+    /** Fixed number of decimals. */
+    decimals?: number;
+    /** Render a fraction as a percentage (0.123 -> 12.3 %). */
+    percent?: boolean;
+}
+/** "Not available" in the interface language: what an absent or non-finite value renders as. */
+declare const NOT_AVAILABLE: Record<Lang, string>;
+/**
+ * A number in the interface language: a decimal point in English and a decimal comma in Spanish
+ * (`conventions/languages.md`), significant digits by default. `null`, `undefined` and non-finite values render as
+ * "not available", never as `NaN` (failure classes 5 and 23 of the 2026-10-04 history).
+ */
+declare function formatNumber(value: number | null | undefined, lang: Lang, opts?: FormatOptions): string;
+/** `formatNumber` bound to the current shell language. */
+declare function useFormat(): (value: number | null | undefined, opts?: FormatOptions) => string;
+
+/**
+ * The colour and font tokens `styles.css` defines for both themes. The architecture-modal validation and the
+ * template's web-baseline guard check every `var(--x)` a product names against this list; a token that is not
+ * defined renders as nothing, silently (failure class 25 of the 2026-10-04 history). A unit test keeps this list
+ * equal to the stylesheet.
+ */
+declare const SHELL_TOKENS: readonly ["--color-bg", "--color-surface", "--color-surface-2", "--color-border", "--color-fg", "--color-fg-subtle", "--color-fg-faint", "--color-accent", "--color-accent-fg", "--color-accent-soft", "--color-accent-2", "--color-magenta", "--color-good", "--color-warn", "--color-bad", "--color-shadow", "--font-sans", "--font-mono", "--maxw", "--maxw-wide"];
+type ShellToken = (typeof SHELL_TOKENS)[number];
+/** The computed value of a token on the document, or `fallback` outside a browser. */
+declare function resolveToken(token: string, fallback?: string): string;
+/**
+ * The colour tokens resolved to concrete values for the active theme, recomputed when the theme changes. Canvas
+ * and WebGL renderers cannot read CSS variables, so they take these (failure classes 7 and 18: charts drawn in
+ * dark-theme colours on a light page).
+ */
+declare function useThemeTokens(): Record<ShellToken, string>;
+
+export { type FormatOptions as F, NOT_AVAILABLE as N, type ShellToken as S, SHELL_TOKENS as a, useThemeTokens as b, formatNumber as f, resolveToken as r, useFormat as u };

package/gate/inpage.mjs

@@ -0,0 +1,454 @@
+// The gate's in-page library. `installLib` is serialised by Playwright into an init script, so it must be
+// self-contained: everything it uses is defined inside it. It installs `window.__caosGate` before the product's own
+// scripts run, wraps requestAnimationFrame to count frames during an idle window (G8), and exposes the measurements
+// the runner decides on. Each measurement answers one question about what a reader would see, on the element a
+// reader would see it on (never `#root`, never a host box standing in for a drawing).
+
+export function installLib() {
+  const G = (window.__caosGate = window.__caosGate || {});
+  G.raf = 0;
+  G.counting = false;
+  const nativeRaf = window.requestAnimationFrame ? window.requestAnimationFrame.bind(window) : null;
+  if (nativeRaf) {
+    window.requestAnimationFrame = (cb) =>
+      nativeRaf((t) => {
+        if (G.counting) G.raf += 1;
+        cb(t);
+      });
+  }
+
+  const visible = (el) => {
+    if (!el || el.nodeType !== 1) return false;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0) return false;
+    if (el.checkVisibility) return el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+    const s = getComputedStyle(el);
+    return s.visibility !== 'hidden' && s.display !== 'none' && Number(s.opacity) !== 0;
+  };
+  const shown = (el) => el.getClientRects().length > 0 && (el.checkVisibility ? el.checkVisibility({ checkVisibilityCSS: true }) : true);
+  const path = (el) => {
+    const parts = [];
+    let e = el;
+    while (e && e.nodeType === 1 && e !== document.body && e !== document.documentElement) {
+      const p = e.parentElement;
+      if (!p) break;
+      parts.unshift(`${e.tagName.toLowerCase()}:nth-child(${Array.prototype.indexOf.call(p.children, e) + 1})`);
+      e = p;
+    }
+    return parts.length ? `body > ${parts.join(' > ')}` : 'body';
+  };
+  const describe = (el) => {
+    if (!el || el.nodeType !== 1) return String(el);
+    const t = el.tagName.toLowerCase();
+    const cls = typeof el.className === 'string' && el.className.trim() ? `.${el.className.trim().split(/\s+/).slice(0, 3).join('.')}` : '';
+    const attrs = ['data-control', 'data-tab', 'data-panel', 'data-plot', 'data-stage', 'data-case', 'data-readout', 'aria-label']
+      .filter((a) => el.hasAttribute(a))
+      .map((a) => `[${a}="${String(el.getAttribute(a)).slice(0, 30)}"]`)
+      .join('');
+    const text = (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 32);
+    return `${t}${el.id ? `#${el.id}` : ''}${cls}${attrs}${text ? ` "${text}"` : ''}`;
+  };
+  G.describe = describe;
+
+  /** '' when the page has settled on its declared state; otherwise why not (G7: never networkidle, never a sleep). */
+  G.ready = () => {
+    if (!document.querySelector('[data-brand]')) return 'no [data-brand]: the shell has not rendered';
+    const loading = [...document.querySelectorAll('[data-state="loading"]')].filter(shown);
+    if (loading.length) return `${loading.length} element(s) still declare data-state="loading": ${loading.slice(0, 3).map(describe).join('; ')}`;
+    const stale = [...document.querySelectorAll('[data-stale="1"]')].filter(shown);
+    if (stale.length) return `${stale.length} view(s) still show an earlier selection (data-stale="1"): ${stale.slice(0, 3).map(describe).join('; ')}`;
+    const undrawn = [...document.querySelectorAll('[data-drawn="0"]')].filter(shown);
+    if (undrawn.length) return `${undrawn.length} stage(s) never got a size (data-drawn="0"): ${undrawn.slice(0, 3).map(describe).join('; ')}`;
+    return '';
+  };
+
+  /** What the page says it is and which mode it is in (G1, G2). */
+  G.identity = () => {
+    const b = document.querySelector('[data-brand]');
+    const active = document.querySelector('header nav a.active, header nav a[aria-current="page"]');
+    return {
+      brand: b ? b.getAttribute('data-brand') : null,
+      title: document.title,
+      theme: document.documentElement.dataset.theme ?? null,
+      lang: document.documentElement.lang || null,
+      activeHref: active ? active.href : null,
+    };
+  };
+
+  /** The static layout of the current view (G5, G6 inputs, ADR-0071 and ADR-0017 measures). */
+  G.facts = () => {
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const de = document.documentElement;
+    const body = document.body;
+    const docH = Math.max(de.scrollHeight, body.scrollHeight);
+    const docW = Math.max(de.scrollWidth, body.scrollWidth);
+
+    // Element boxes beyond the viewport, not clipped by an ancestor (scrollWidth alone misses clipped documents).
+    const beyond = [];
+    const walk = (el, clipped) => {
+      for (const c of el.children) {
+        const s = getComputedStyle(c);
+        if (s.display === 'none') continue;
+        const r = c.getBoundingClientRect();
+        if (!clipped && r.width > 1 && r.height > 1 && s.visibility !== 'hidden' && (r.right > vw + 1 || r.left < -1)) {
+          beyond.push(`${describe(c)} spans ${Math.round(r.left)}..${Math.round(r.right)} of a ${vw}px viewport`);
+          continue;
+        }
+        if (c.tagName.toLowerCase() === 'svg') continue;
+        walk(c, clipped || s.overflowX !== 'visible');
+      }
+    };
+    walk(body, false);
+
+    // Tab rows: one row each (ADR-0071 rule 4); tops clustered so a 1px active-tab offset is not a second row.
+    const rows = [...document.querySelectorAll('[role="tablist"]')]
+      .filter((tl) => visible(tl) && tl.getAttribute('aria-orientation') !== 'vertical')
+      .map((tl) => {
+        const tops = [...tl.querySelectorAll('[role="tab"]')]
+          .filter((t) => t.closest('[role="tablist"]') === tl && visible(t))
+          .map((t) => t.getBoundingClientRect().top)
+          .sort((a, b) => a - b);
+        let n = tops.length ? 1 : 0;
+        for (let i = 1; i < tops.length; i += 1) if (tops[i] - tops[i - 1] > 8) n += 1;
+        return { name: tl.getAttribute('aria-label') || describe(tl), rows: n };
+      });
+
+    // The rail: no scroll (rule 6) and every descendant inside its box (G5).
+    const railEl = document.querySelector('[data-rail]');
+    let rail = null;
+    if (railEl && visible(railEl)) {
+      const rr = railEl.getBoundingClientRect();
+      const outside = [];
+      for (const d of railEl.querySelectorAll('*')) {
+        if (d.closest('svg') && d.tagName.toLowerCase() !== 'svg') continue;
+        if (!visible(d)) continue;
+        const r = d.getBoundingClientRect();
+        if (r.width <= 1 || r.height <= 1) continue;
+        let p = d.parentElement;
+        let scroller = false;
+        while (p && p !== railEl) {
+          if (getComputedStyle(p).overflowX !== 'visible') {
+            scroller = true;
+            break;
+          }
+          p = p.parentElement;
+        }
+        if (scroller) continue;
+        if (r.right > rr.right + 1 || r.left < rr.left - 1) outside.push(`${describe(d)} spans ${Math.round(r.left)}..${Math.round(r.right)}, rail ${Math.round(rr.left)}..${Math.round(rr.right)}`);
+      }
+      rail = { scroll: railEl.scrollHeight, client: railEl.clientHeight, outside: outside.slice(0, 5), outsideCount: outside.length };
+    }
+
+    // Truncated text must carry its full text (G5).
+    const truncated = [];
+    for (const el of document.querySelectorAll('body *')) {
+      if (el.namespaceURI === 'http://www.w3.org/2000/svg') continue;
+      const s = getComputedStyle(el);
+      if (s.textOverflow !== 'ellipsis' || el.scrollWidth <= el.clientWidth + 1 || !visible(el)) continue;
+      // The full text must be readable somewhere: a title (or accessible name) on the element or its two nearest
+      // ancestors that CONTAINS it. Any label nearby is not enough: the rail's own aria-label would excuse everything.
+      const full = (el.textContent || '').trim().replace(/s+/g, ' ');
+      let named = false;
+      for (let i = 0, t = el; i < 3 && t; i += 1, t = t.parentElement) {
+        const label = `${t.getAttribute('title') || ''} ${t.getAttribute('aria-label') || ''}`.replace(/s+/g, ' ');
+        if (full && label.includes(full)) {
+          named = true;
+          break;
+        }
+      }
+      if (!named) truncated.push(describe(el));
+    }
+
+    // Containers that cut their content: overflow hidden or clip with more content than box (S1, G5).
+    const clipped = [];
+    const containers = new Set([de, body, document.getElementById('root'), ...document.querySelectorAll('main, .page, .page-body, [data-instrument], [data-rail], .tabpanel, .caos-cw, [data-plot]')]);
+    for (const el of containers) {
+      if (!el || !visible(el)) continue;
+      const s = getComputedStyle(el);
+      if ((s.overflowY === 'hidden' || s.overflowY === 'clip') && el.scrollHeight > el.clientHeight + 4) {
+        clipped.push(`${describe(el)} cuts ${el.scrollHeight - el.clientHeight}px of content (overflow-y ${s.overflowY})`);
+      }
+      if ((s.overflowX === 'hidden' || s.overflowX === 'clip') && el.scrollWidth > el.clientWidth + 4) {
+        clipped.push(`${describe(el)} cuts ${el.scrollWidth - el.clientWidth}px of content horizontally (overflow-x ${s.overflowX})`);
+      }
+    }
+
+    // Layout containers that scroll sideways: a wide child pushed the page, the instrument or a panel past its width.
+    // Rows built to scroll (the nav, tab rows, a plot body holding a wide table) are not layout containers.
+    for (const el of new Set([...document.querySelectorAll('main, .page, .page-body, [data-instrument], [data-rail], .tabpanel, .subtabpanel, .caos-cw')])) {
+      if (!visible(el)) continue;
+      const s = getComputedStyle(el);
+      if ((s.overflowX === 'auto' || s.overflowX === 'scroll') && el.scrollWidth > el.clientWidth + 4) {
+        clipped.push(`${describe(el)} scrolls sideways by ${el.scrollWidth - el.clientWidth}px (a child is wider than the layout)`);
+      }
+    }
+
+    // The instrument and what is drawn in it (G6): canvases, svg drawings, images, tables; icons excluded.
+    const inst = document.querySelector('[data-instrument]');
+    let instrument = null;
+    const surfaces = [];
+    let prose = false;
+    if (inst && visible(inst)) {
+      const ir = inst.getBoundingClientRect();
+      const cx0 = Math.max(0, ir.left);
+      const cy0 = Math.max(0, ir.top);
+      const cx1 = Math.min(vw, ir.right);
+      const cy1 = Math.min(vh, ir.bottom);
+      instrument = { x: cx0, y: cy0, w: Math.max(0, cx1 - cx0), h: Math.max(0, cy1 - cy0) };
+      const ctx = inst.querySelector('.caos-cw-context');
+      prose = Boolean(ctx && visible(ctx));
+      for (const el of inst.querySelectorAll('canvas, svg, img, table, video')) {
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'svg' && el.parentElement && el.parentElement.closest('svg')) continue;
+        if (el.parentElement && el.parentElement.closest('table') && tag === 'table') continue;
+        if (!visible(el)) continue;
+        const r = el.getBoundingClientRect();
+        const min = tag === 'canvas' || tag === 'table' ? 16 : 48;
+        if (r.width < min || r.height < min) continue;
+        const x = Math.max(cx0, r.left);
+        const y = Math.max(cy0, r.top);
+        const x2 = Math.min(cx1, r.right);
+        const y2 = Math.min(cy1, r.bottom);
+        if (x2 - x < 2 || y2 - y < 2) continue;
+        // The stage a drawing is judged against: the view's body, else the sized stage, else the surface itself; the
+        // view is the card that holds it. A drawing that fills a small corner of a large view underfills its stage.
+        const stageEl = el.closest('.caos-plot-body') || el.closest('[data-drawn]') || el;
+        const viewEl = el.closest('[data-plot]') || stageEl;
+        const clipRect = (b) => {
+          const sx = Math.max(cx0, b.left);
+          const sy = Math.max(cy0, b.top);
+          return { x: sx, y: sy, w: Math.max(0, Math.min(cx1, b.right) - sx), h: Math.max(0, Math.min(cy1, b.bottom) - sy) };
+        };
+        surfaces.push({
+          kind: tag,
+          label: describe(viewEl),
+          x,
+          y,
+          w: x2 - x,
+          h: y2 - y,
+          right: r.right,
+          stageKey: path(stageEl),
+          stage: clipRect(stageEl.getBoundingClientRect()),
+          viewKey: path(viewEl),
+          view: clipRect(viewEl.getBoundingClientRect()),
+        });
+      }
+    }
+
+    const wb = document.querySelector('[data-case-workbench]');
+    const workbench = wb
+      ? { case: wb.getAttribute('data-case'), key: wb.getAttribute('data-state-key'), replayOnly: wb.getAttribute('data-replay-only') === '1' }
+      : null;
+
+    let offCentre = null;
+    const proseBody = document.querySelector('.page-body:not(.wide)');
+    if (proseBody && visible(proseBody)) {
+      const parent = proseBody.parentElement;
+      const pb = proseBody.getBoundingClientRect();
+      const cb = parent.getBoundingClientRect();
+      offCentre = Math.abs(pb.left - cb.left - (parent.clientWidth - pb.width) / 2);
+    }
+    const pageBody = document.querySelector('.page-body');
+    return {
+      vw,
+      vh,
+      docH,
+      docW,
+      beyond: beyond.slice(0, 5),
+      beyondCount: beyond.length,
+      rows,
+      rail,
+      truncated: truncated.slice(0, 5),
+      truncatedCount: truncated.length,
+      clipped,
+      instrument,
+      surfaces,
+      prose,
+      workbench,
+      offCentre,
+      pageText: pageBody ? (pageBody.innerText || '').trim().length : 0,
+      referenceLists: [...document.querySelectorAll('.reference-list')].filter(visible).length,
+      uncaptioned: [...document.querySelectorAll('.equation')].filter((e) => visible(e) && !e.querySelector('.equation-caption')).length,
+      sectionsWithoutRefs: [...document.querySelectorAll('[data-no-refs-reason="missing"]')].filter(visible).length,
+    };
+  };
+
+  /** A tall view must move when scrolled (S1, G5). Restores the positions it changed. */
+  G.scrolls = () => {
+    const out = [];
+    const de = document.documentElement;
+    const docH = Math.max(de.scrollHeight, document.body.scrollHeight);
+    if (docH > window.innerHeight + 1) {
+      const y = window.scrollY;
+      winScroll(0, 0);
+      winScroll(0, docH);
+      const moved = window.scrollY > 0;
+      winScroll(0, y);
+      if (!moved) out.push(`the document is ${docH}px tall in a ${window.innerHeight}px viewport and does not scroll`);
+    }
+    for (const el of document.querySelectorAll('main, .page, .page-body, [data-instrument], [data-rail], .tabpanel')) {
+      if (!visible(el)) continue;
+      const s = getComputedStyle(el);
+      if ((s.overflowY === 'auto' || s.overflowY === 'scroll') && el.scrollHeight > el.clientHeight + 4) {
+        const t = el.scrollTop;
+        setScroll(el, el.scrollLeft, 0);
+        setScroll(el, el.scrollLeft, el.scrollHeight);
+        const moved = el.scrollTop > 0;
+        setScroll(el, el.scrollLeft, t);
+        if (!moved) out.push(`${describe(el)} holds ${el.scrollHeight - el.clientHeight}px more content and does not scroll`);
+      }
+    }
+    return out;
+  };
+
+  const setScroll = (el, left, top) => el.scrollTo({ left, top, behavior: 'instant' });
+  const winScroll = (x, y) => window.scrollTo({ left: x, top: y, behavior: 'instant' });
+
+  /** Brings an element into view the way a reader can: by scrolling the containers a reader can scroll (overflow auto
+   * or scroll) and the document, never an overflow-hidden ancestor (scrollIntoView would, and hide a real cut). */
+  const bring = (el) => {
+    for (let a = el.parentElement; a && a !== document.body && a !== document.documentElement; a = a.parentElement) {
+      const s = getComputedStyle(a);
+      const ar = a.getBoundingClientRect();
+      let r = el.getBoundingClientRect();
+      if ((s.overflowX === 'auto' || s.overflowX === 'scroll') && a.scrollWidth > a.clientWidth) {
+        if (r.left < ar.left) setScroll(a, a.scrollLeft - (ar.left - r.left + 8), a.scrollTop);
+        else if (r.right > ar.right) setScroll(a, a.scrollLeft + (r.right - ar.right + 8), a.scrollTop);
+      }
+      r = el.getBoundingClientRect();
+      if ((s.overflowY === 'auto' || s.overflowY === 'scroll') && a.scrollHeight > a.clientHeight) {
+        if (r.top < ar.top) setScroll(a, a.scrollLeft, a.scrollTop - (ar.top - r.top + 8));
+        else if (r.bottom > ar.bottom) setScroll(a, a.scrollLeft, a.scrollTop + (r.bottom - ar.bottom + 8));
+      }
+    }
+    const r = el.getBoundingClientRect();
+    if (r.top < 0 || r.bottom > window.innerHeight) winScroll(window.scrollX, window.scrollY + r.top + r.height / 2 - window.innerHeight / 2);
+    const r2 = el.getBoundingClientRect();
+    if (r2.left < 0 || r2.right > window.innerWidth) winScroll(window.scrollX + r2.left + r2.width / 2 - window.innerWidth / 2, window.scrollY);
+  };
+  G.bringEl = (el) => bring(el);
+  G.bring = (selector) => {
+    const el = document.querySelector(selector);
+    if (el) bring(el);
+    return Boolean(el);
+  };
+
+  /** Every visible control can be brought into the viewport and receives the pointer at its centre (G5). */
+  G.reach = () => {
+    const sel = 'a[href], button, select, input:not([type="hidden"]), textarea, [role="tab"], [role="button"], [tabindex]:not([tabindex="-1"])';
+    const saved = new Map();
+    for (const e of document.querySelectorAll('*')) if (e.scrollLeft || e.scrollTop) saved.set(e, [e.scrollLeft, e.scrollTop]);
+    const sx = window.scrollX;
+    const sy = window.scrollY;
+    const out = [];
+    let checked = 0;
+    const els = [...document.querySelectorAll(sel)].filter((el) => !el.disabled && !el.closest('[aria-hidden="true"]') && visible(el));
+    for (const el of els) {
+      bring(el);
+      // A wrapped inline element (a citation link over two lines) has its box centre between its line fragments; the
+      // pointer lands on a fragment, so the largest one is tested.
+      const frags = [...el.getClientRects()].filter((q) => q.width >= 1 && q.height >= 1);
+      const r = frags.length ? frags.reduce((a, b) => (b.width * b.height > a.width * a.height ? b : a)) : el.getBoundingClientRect();
+      if (r.width < 1 || r.height < 1) continue;
+      checked += 1;
+      const fits = r.width <= window.innerWidth && r.height <= window.innerHeight;
+      if (fits && (r.left < -1 || r.right > window.innerWidth + 1 || r.top < -1 || r.bottom > window.innerHeight + 1)) {
+        out.push(`${describe(el)} cannot be brought into the viewport (at ${Math.round(r.left)},${Math.round(r.top)})`);
+        continue;
+      }
+      const px = Math.min(Math.max(r.left + Math.min(r.width, window.innerWidth) / 2, 0), window.innerWidth - 1);
+      const py = Math.min(Math.max(r.top + Math.min(r.height, window.innerHeight) / 2, 0), window.innerHeight - 1);
+      const hit = document.elementFromPoint(px, py);
+      const ok =
+        hit && (hit === el || el.contains(hit) || (el.labels && [...el.labels].some((l) => l.contains(hit))) || (hit.tagName === 'LABEL' && hit.control === el));
+      if (!ok) out.push(`${describe(el)} is covered by ${hit ? describe(hit) : 'nothing (outside the page)'}`);
+    }
+    for (const e of document.querySelectorAll('*')) {
+      const s = saved.get(e);
+      if (s) setScroll(e, s[0], s[1]);
+      else if (e.scrollLeft || e.scrollTop) setScroll(e, 0, 0);
+    }
+    winScroll(sx, sy);
+    return { checked, unreachable: out.slice(0, 8), unreachableCount: out.length };
+  };
+
+  /** Animation frames and DOM mutations over a window at rest (G8). */
+  G.idle = (ms) =>
+    new Promise((done) => {
+      let mutations = 0;
+      const sample = [];
+      const mo = new MutationObserver((recs) => {
+        mutations += recs.length;
+        for (const r of recs) {
+          if (sample.length >= 3) break;
+          const t = r.target.nodeType === 1 ? r.target : r.target.parentElement;
+          sample.push(`${r.type}${r.attributeName ? ` ${r.attributeName}` : ''} on ${describe(t)}`);
+        }
+      });
+      mo.observe(document, { subtree: true, childList: true, attributes: true, characterData: true });
+      G.raf = 0;
+      G.counting = true;
+      setTimeout(() => {
+        G.counting = false;
+        mo.disconnect();
+        done({ raf: G.raf, mutations, sample, ms });
+      }, ms);
+    });
+
+  /** The visible tab lists outside the header, footer and dialogs, each with the list whose panel holds it (G7). */
+  G.tablists = () =>
+    [...document.querySelectorAll('[role="tablist"]')]
+      .filter((tl) => visible(tl) && !tl.closest('header, footer, [role="dialog"]'))
+      .map((tl) => {
+        const panel = tl.parentElement ? tl.parentElement.closest('[role="tabpanel"]') : null;
+        let owner = null;
+        if (panel) {
+          const id = panel.getAttribute('aria-labelledby');
+          const tab = id ? document.getElementById(id) : null;
+          const otl = tab ? tab.closest('[role="tablist"]') : null;
+          owner = otl ? path(otl) : 'unknown';
+        }
+        const tabs = [...tl.querySelectorAll('[role="tab"]')].filter((t) => t.closest('[role="tablist"]') === tl && visible(t));
+        return {
+          key: path(tl),
+          owner,
+          name: tl.getAttribute('aria-label') || '',
+          source: Boolean(tl.closest('.cs-source-tabs') || tl.classList.contains('cs-source-tabs')),
+          tabs: tabs.map((t) => (t.getAttribute('data-tab') || (t.textContent || '').trim()).slice(0, 40)),
+          active: tabs.findIndex((t) => t.getAttribute('aria-selected') === 'true'),
+        };
+      });
+
+  /** The cases the case control offers right now (G9). */
+  G.cases = () => {
+    const ctl = [...document.querySelectorAll('[data-control="case"]')].filter(visible);
+    const ids = [];
+    for (const c of ctl) {
+      if (c.tagName === 'SELECT') {
+        for (const o of c.options) if (!o.disabled && o.value) ids.push(o.value);
+      } else for (const b of c.querySelectorAll('[data-case]')) if (!b.disabled) ids.push(b.getAttribute('data-case'));
+    }
+    return { kind: ctl.length === 0 ? 'none' : ctl[0].tagName === 'SELECT' ? 'select' : 'chips', ids: [...new Set(ids)] };
+  };
+
+  /** The registered controls of the instrument, except the case control (G9). */
+  G.controls = () =>
+    [...document.querySelectorAll('[data-control]')]
+      .filter((c) => visible(c) && c.getAttribute('data-control') !== 'case')
+      .map((c) => {
+        let kind = 'unknown';
+        if (c.tagName === 'SELECT' || c.querySelector('select')) kind = 'select';
+        else if ((c.tagName === 'INPUT' && c.type === 'range') || c.querySelector('input[type="range"]')) kind = 'range';
+        else if (c.querySelector('input[type="checkbox"], input[type="radio"]') || (c.tagName === 'INPUT' && (c.type === 'checkbox' || c.type === 'radio'))) kind = 'check';
+        else if (c.querySelector('input[type="number"]') || (c.tagName === 'INPUT' && c.type === 'number')) kind = 'number';
+        else if (c.querySelector('button') || c.tagName === 'BUTTON') kind = 'buttons';
+        return { id: c.getAttribute('data-control'), path: path(c), kind };
+      });
+
+  /** The visible keyed views: every plot and readout with the selection key it shows (G9). */
+  G.views = () =>
+    [...document.querySelectorAll('[data-plot], [data-readout]')]
+      .filter(visible)
+      .map((v) => ({ label: describe(v), key: v.getAttribute('data-state-key') || '', stale: v.getAttribute('data-stale') === '1' }));
+}