@krizaka/page-audit 0.5.0 → 0.6.0

package/README.md

@@ -63,3 +63,14 @@ defineJourneyTests({
 
 Baselines are taken in the official Playwright container by the shared workflows of krizaka/.github (`visual-regression.yml` to compare,
 `update-visual-baselines.yml` to commit them on a branch); never on a Mac.
+
+## The journey kit (0.6)
+
+`@krizaka/page-audit/journey` is the kit of the customer journeys (ADR-017, krizaka/.github#423). A product writes no copy of it.
+
+- **Catalogue**: `validateJourney` checks a row of `journeys/journeys.json` (kebab-case id, a promise, a persona of the seeded cast, platforms, steps, a budget of 90 s by default); `checkCatalogue` fails a file without a row, a row without a file, an id twice; `journeysByTag(index, "smoke")` picks what runs on every pull request; `budgetProblem` names a journey over its budget.
+- **Persona sign-in once per worker**: `personaSessions({ dir, signIn }).stateFor("eric")` signs the persona in on the first call and reuses the browser state after (parallel calls share one sign-in; one file per worker; a failed sign-in is not remembered).
+- **Seeded cast**: `seededPersona(cast, "eric")` reads a member or names who exists.
+- **Masks**: `journeyMaskSelectors({ extra })` = `time`, `[data-mask]`, `[data-date]`, `[data-testid$="-id"]`, `[data-run-id]` and the journey's own.
+- **Video hooks**: `videoContextOptions(journey, { dir })` records only the journeys with `video: true`; `videoFile(journey, "web")` names the file.
+- **Flake policy**: `assertNoRetries(playwrightConfig)` refuses retries above 0 (also per project); `quarantine(entries)` holds a named test with its reason and its issue, capped at one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krizaka/page-audit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The page audit of every Krizaka app, in one place: HTTP status, empty main, horizontal overflow, a card out of its panel, sections covering each other, a column cut off, top chrome overlaps, unnamed buttons, empty headings. Runs in a real browser (Playwright) over a route list, viewports and themes, with View Transitions neutralised and a self-test on its own fixtures.",
   "keywords": [
     "krizaka",
@@ -34,6 +34,10 @@
       "import": "./src/settle.mjs"
     },
     "./fixtures": "./src/fixtures.mjs",
+    "./journey": {
+      "types": "./src/journey.d.ts",
+      "import": "./src/journey.mjs"
+    },
     "./package.json": "./package.json",
     "./visual": {
       "types": "./src/visual.d.ts",
@@ -61,7 +65,7 @@
     "eslint": "^9.39.0",
     "playwright-core": "^1.55.0",
     "vitest": "^4.1.11",
-    "@krizaka/config": "^0.14.0"
+    "@krizaka/config": "^0.18.0"
   },
   "engines": {
     "node": ">=22"
@@ -72,7 +76,7 @@
   "scripts": {
     "lint": "eslint . --max-warnings 0",
     "typecheck": "node --check src/index.mjs",
-    "test": "vitest run",
+    "test": "vitest run --coverage --coverage.provider=v8 --coverage.reporter=lcov --coverage.reporter=text-summary \"--coverage.include=src/**/*.ts\"",
     "check": "pnpm run lint && pnpm run test"
   }
 }

package/src/cli.mjs

@@ -21,7 +21,9 @@ if (process.argv.includes("--self-test")) {
 } else {
   const base = arg("base", "http://localhost:3000");
   const has = (name) => process.argv.includes(`--${name}`);
-  const routes = has("sitemap") ? await routesFromSitemap(base, { first: list(arg("routes"), ["/"]), limit: Number(arg("limit", 14)) }) : list(arg("routes"), ["/"]);
+  const routes = has("sitemap")
+    ? await routesFromSitemap(base, { first: list(arg("routes"), ["/"]), limit: Number(arg("limit", 14)) })
+    : list(arg("routes"), ["/"]);
   if (!routes) {
     console.error(`Nothing answers at ${base}/sitemap.xml`);
     process.exit(2);
@@ -29,7 +31,21 @@ if (process.argv.includes("--self-test")) {
   const [app, baseline] = (arg("a11y") ?? "").split(":");
   const widths = list(arg("widths"), WIDTHS).map(Number);
   const themes = list(arg("themes"), THEMES);
-  const problems = await auditRoutes({ base, routes, widths, themes, themeKey: arg("theme-key", "kz-theme"), shots: arg("shots"), a11y: baseline ? { app, baseline } : undefined, checks: { h1: has("h1"), status: has("status"), emptyMain: has("empty-main"), minAction: arg("min-action") ? Number(arg("min-action")) : undefined } });
+  const problems = await auditRoutes({
+    base,
+    routes,
+    widths,
+    themes,
+    themeKey: arg("theme-key", "kz-theme"),
+    shots: arg("shots"),
+    a11y: baseline ? { app, baseline } : undefined,
+    checks: {
+      h1: has("h1"),
+      status: has("status"),
+      emptyMain: has("empty-main"),
+      minAction: arg("min-action") ? Number(arg("min-action")) : undefined,
+    },
+  });
   if (problems.length) {
     console.error(`${problems.length} page problem(s):\n  ${problems.join("\n  ")}`);
     process.exit(1);

package/src/fixtures.mjs

@@ -1,7 +1,8 @@
 // Small pages that reproduce what the layout audit must catch (yomizaka#435) and one that is fine, for `check-page-audit.mjs`:
 // the guard is proven on its own fixtures before it is trusted on the app.
 
-const page = (body, css = "") => `<!doctype html><html><head><meta charset="utf-8"><style>*{box-sizing:border-box}body{margin:0;font:16px sans-serif}${css}</style></head><body><main>${body}</main></body></html>`;
+const page = (body, css = "") =>
+  `<!doctype html><html><head><meta charset="utf-8"><style>*{box-sizing:border-box}body{margin:0;font:16px sans-serif}${css}</style></head><body><main>${body}</main></body></html>`;
 
 /** The binder as it was: the open folder's card is as tall as its grid row (a fixed height) and runs over the next section. */
 export const CARD_OVER_NEXT = page(
@@ -9,7 +10,9 @@ export const CARD_OVER_NEXT = page(
   "section{display:block}",
 );
 /** Two sections laid out on top of each other. */
-export const SECTIONS_OVERLAP = page(`<section data-testid="a" style="height:100px">A</section><section data-testid="b" style="margin-top:-60px;height:100px;position:relative">B</section>`);
+export const SECTIONS_OVERLAP = page(
+  `<section data-testid="a" style="height:100px">A</section><section data-testid="b" style="margin-top:-60px;height:100px;position:relative">B</section>`,
+);
 /** A two-column layout whose wrapper clips the right column. */
 export const COLUMN_CUT = page(
   `<div style="overflow:hidden;width:600px"><div style="display:grid;grid-template-columns:400px 400px"><section data-testid="main">Main</section><aside data-testid="activity"><section data-testid="activity-figures">Activité</section></aside></div></div>`,
@@ -31,29 +34,45 @@ export const FOLDED_SECTION = page(
 /** A page whose `<main>` draws nothing. */
 export const EMPTY_MAIN = page("");
 /** The signed-in frame asks 1000 px of a 700 px screen under a 60 px notice (akinaza#444). */
-export const FRAME_FORCES_SCROLL = page(`<div style="height:60px">notice</div><div data-app-frame-slot><div style="min-height:1000px">shell</div></div>`);
+export const FRAME_FORCES_SCROLL = page(
+  `<div style="height:60px">notice</div><div data-app-frame-slot><div style="min-height:1000px">shell</div></div>`,
+);
 /** The same frame, sized to what is left of the screen. */
-export const FRAME_FITS = page(`<div style="height:60px">notice</div><div data-app-frame-slot><div style="min-height:500px">shell</div></div>`);
+export const FRAME_FITS = page(
+  `<div style="height:60px">notice</div><div data-app-frame-slot><div style="min-height:500px">shell</div></div>`,
+);
 /** A button-styled action 24 px tall, under the 36 px tap target. */
 export const SMALL_ACTION = page(`<a class="kz-button" href="/" style="display:block;height:24px;width:120px">Go</a>`);
 /** A landmark whose content is wider than its box. */
 export const BOX_TOO_WIDE = page(`<aside style="width:200px"><div style="width:500px">wide</div></aside>`);
 /** Broken picture, a tile that draws nothing, an inline hard-coded colour. */
-export const BROKEN_PARTS = page(`<img src="data:image/png;base64,AAAA" width="40" height="40" alt=""><a href="/" style="display:block;width:60px;height:60px"></a><p style="color:#ff0000">x</p>`);
+export const BROKEN_PARTS = page(
+  `<img src="data:image/png;base64,AAAA" width="40" height="40" alt=""><a href="/" style="display:block;width:60px;height:60px"></a><p style="color:#ff0000">x</p>`,
+);
 /** Chrome that fits the family: one footer naming Krizaka, a nav. */
 export const CHROME_FINE = `<!doctype html><html><body><nav>n</nav><main><p>Hello</p></main><footer>A Krizaka product</footer></body></html>`;
 export const CHROME_BAD = `<!doctype html><html><body><main><p>Hello</p></main><footer>one</footer><footer>two</footer></body></html>`;
 
 /** A short token in a table row stretched by a tall neighbour: the cell is tall, its text is one line. */
-export const TOKEN_IN_STRETCHED_ROW = page(`<table style="width:600px"><tbody><tr><td>orazaka-media-pack</td><td>${"A long description. ".repeat(30)}</td></tr></tbody></table>`);
+export const TOKEN_IN_STRETCHED_ROW = page(
+  `<table style="width:600px"><tbody><tr><td>orazaka-media-pack</td><td>${"A long description. ".repeat(30)}</td></tr></tbody></table>`,
+);
 /** An identifier in a narrow cell that breaks every few characters. */
-export const TOKEN_WRAPPED = page(`<table style="width:100px;table-layout:fixed"><tbody><tr><td style="word-break:break-all;font-size:20px">abcdefghijklmnopqrstuvwxyz0123456789</td></tr></tbody></table>`);
+export const TOKEN_WRAPPED = page(
+  `<table style="width:100px;table-layout:fixed"><tbody><tr><td style="word-break:break-all;font-size:20px">abcdefghijklmnopqrstuvwxyz0123456789</td></tr></tbody></table>`,
+);
 
 /** A map that laid out at 0 px: `absolute inset-0` in a frame with no height of its own (akinaza#488). */
-export const MAP_COLLAPSED = page(`<section><div style="position:relative"><div class="maplibregl-map" style="position:absolute;inset:0"><canvas width="0" height="0"></canvas></div></div></section>`);
+export const MAP_COLLAPSED = page(
+  `<section><div style="position:relative"><div class="maplibregl-map" style="position:absolute;inset:0"><canvas width="0" height="0"></canvas></div></div></section>`,
+);
 /** A map box with a size and a canvas, and a Leaflet one with a loaded tile. */
-export const MAP_FINE = page(`<section><div class="maplibregl-map" style="height:300px;width:600px"><canvas style="width:600px;height:300px" width="600" height="300"></canvas></div><div class="leaflet-container" style="height:300px;width:600px"><img class="leaflet-tile-loaded" alt="" width="256" height="256"></div></section>`);
+export const MAP_FINE = page(
+  `<section><div class="maplibregl-map" style="height:300px;width:600px"><canvas style="width:600px;height:300px" width="600" height="300"></canvas></div><div class="leaflet-container" style="height:300px;width:600px"><img class="leaflet-tile-loaded" alt="" width="256" height="256"></div></section>`,
+);
 /** A GL map box of a good size where nothing was drawn (no canvas). */
-export const MAP_NO_CANVAS = page(`<section><div class="maplibregl-map" style="height:300px;width:600px"></div></section>`);
+export const MAP_NO_CANVAS = page(
+  `<section><div class="maplibregl-map" style="height:300px;width:600px"></div></section>`,
+);
 /** A map that is not drawn (display none: a closed tab, a small screen): nothing to measure. */
 export const MAP_HIDDEN = page(`<section><div class="maplibregl-map" style="display:none"></div></section>`);

package/src/index.d.ts

@@ -5,35 +5,74 @@ export type Browser = { newContext(o?: object): Promise<BrowserContext>; close()
 export const auditPage: string;
 export type Chrome = "public" | "app" | "auth";
 export interface ProblemChecks {
-  errors?: string[]; h1?: boolean; headerAction?: boolean; fileLabels?: boolean;
+  errors?: string[];
+  h1?: boolean;
+  headerAction?: boolean;
+  fileLabels?: boolean;
   /** HTTP status of the load (`null`: no response); a 4xx/5xx is a problem. */
   status?: number | null;
-  emptyMain?: boolean; frame?: boolean; minAction?: number; boxes?: boolean; landmarks?: Chrome; pictures?: boolean; emptyControls?: boolean; hardColors?: boolean;
+  emptyMain?: boolean;
+  frame?: boolean;
+  minAction?: number;
+  boxes?: boolean;
+  landmarks?: Chrome;
+  pictures?: boolean;
+  emptyControls?: boolean;
+  hardColors?: boolean;
   /** Empty maps (a GL / Leaflet / `[data-kz-map]` box under 120 px, no canvas, no loaded tile); `{ min, required }` to tune, `required` fails a page with no map. */
   maps?: boolean | { min?: number; required?: boolean };
 }
 export function problemsOf(where: string, result: Record<string, unknown>, checks?: ProblemChecks): string[];
 export function auditOptions<T extends object>(options?: T): T & { reducedMotion: "reduce" };
 export function withoutViewTransitions(): void;
-export function auditContext(browser: { newContext(o?: object): Promise<BrowserContext> }, options?: object): Promise<BrowserContext>;
+export function auditContext(
+  browser: { newContext(o?: object): Promise<BrowserContext> },
+  options?: object,
+): Promise<BrowserContext>;
 export function settled(page: Page): Promise<unknown>;
 export function loadSettled(page: Page, url: string, options?: object): Promise<BrowserContext>;
 export function resizeSettled(page: Page, size: { width: number; height: number }): Promise<void>;
 export const WIDTHS: number[];
 export const THEMES: string[];
 export function isPageError(message: { type(): string; text(): string }, ignore?: RegExp[]): boolean;
-export function routesFromSitemap(base: string, options?: { first?: string[]; limit?: number; fetcher?: typeof fetch }): Promise<string[] | null>;
-export interface RouteSpec { url: string; name?: string; chrome?: Chrome; session?: boolean }
-export interface A11yOptions { app: string; baseline: string; widths?: number[]; log?: (line: string) => void; session?: { app: string; baseline: string } }
+export function routesFromSitemap(
+  base: string,
+  options?: { first?: string[]; limit?: number; fetcher?: typeof fetch },
+): Promise<string[] | null>;
+export interface RouteSpec {
+  url: string;
+  name?: string;
+  chrome?: Chrome;
+  session?: boolean;
+}
+export interface A11yOptions {
+  app: string;
+  baseline: string;
+  widths?: number[];
+  log?: (line: string) => void;
+  session?: { app: string; baseline: string };
+}
 export interface SessionOptions {
   storageState?: object | string;
   signIn?: (context: BrowserContext, o: { base: string; theme: string; page: Page }) => Promise<void>;
   routes?: (page: Page, o: { base: string; theme: string }) => Promise<Array<string | RouteSpec>>;
 }
 export interface AuditRoutesOptions {
-  base: string; routes: Array<string | RouteSpec>; widths?: Array<number | { width: number; height?: number }>; themes?: string[]; height?: number; themeKey?: string; shots?: string; settleMs?: number;
-  ignoreConsole?: RegExp[]; attempts?: number; a11y?: A11yOptions; session?: SessionOptions;
-  checks?: Omit<ProblemChecks, "errors">; prepare?: (page: Page, route: string) => Promise<void>; launch?: () => Promise<BrowserContext>;
+  base: string;
+  routes: Array<string | RouteSpec>;
+  widths?: Array<number | { width: number; height?: number }>;
+  themes?: string[];
+  height?: number;
+  themeKey?: string;
+  shots?: string;
+  settleMs?: number;
+  ignoreConsole?: RegExp[];
+  attempts?: number;
+  a11y?: A11yOptions;
+  session?: SessionOptions;
+  checks?: Omit<ProblemChecks, "errors">;
+  prepare?: (page: Page, route: string) => Promise<void>;
+  launch?: () => Promise<BrowserContext>;
 }
 export function auditRoutes(options: AuditRoutesOptions): Promise<string[]>;
 export function selfTest(options?: { launch?: () => Promise<BrowserContext> }): Promise<string[]>;

package/src/index.mjs

@@ -1,4 +1,4 @@
 export { auditPage, problemsOf } from "./page-audit.mjs";
 export { auditRoutes, isPageError, routesFromSitemap, THEMES, WIDTHS } from "./run.mjs";
 export { selfTest } from "./self-test.mjs";
-export { auditContext, auditOptions, loadSettled, resizeSettled,settled, withoutViewTransitions } from "./settle.mjs";
+export { auditContext, auditOptions, loadSettled, resizeSettled, settled, withoutViewTransitions } from "./settle.mjs";

package/src/journey.d.ts

@@ -0,0 +1,54 @@
+export type Platform = "web" | "mobile";
+
+/** A row of `journeys/journeys.json` (ADR-017 §3). */
+export interface JourneyRow {
+  id: string;
+  promise: string;
+  persona: string;
+  platforms: Platform[];
+  steps: string[];
+  video?: boolean;
+  budgetSeconds?: number;
+  tags?: string[];
+}
+
+export const DEFAULT_BUDGET_SECONDS: 90;
+export function validateJourney(journey: Partial<JourneyRow>, options?: { cast?: readonly string[] }): string[];
+export function checkCatalogue(input: { files: readonly string[]; index: readonly { id: string }[] }): string[];
+export function journeysByTag<T extends { tags?: string[] }>(index: readonly T[], tag: string): T[];
+export function budgetProblem(journey: Pick<JourneyRow, "id" | "budgetSeconds">, elapsedMs: number): string | undefined;
+
+export interface PersonaSessions {
+  /** The path of the persona's browser state for this worker; signs in on the first call only. */
+  stateFor(persona: string): Promise<string>;
+}
+export function personaSessions(options: {
+  dir: string;
+  signIn: (persona: string, file: string) => Promise<unknown>;
+  worker?: number;
+}): PersonaSessions;
+
+export function seededPersona<T>(cast: Record<string, T>, id: string): T;
+
+export const JOURNEY_MASKS: readonly string[];
+export function journeyMaskSelectors(options?: { extra?: readonly string[]; defaults?: boolean }): string[];
+
+export const VIDEO_SIZE: Readonly<{ width: number; height: number }>;
+export function videoContextOptions(
+  journey: Pick<JourneyRow, "id" | "video">,
+  options: { dir: string; size?: { width: number; height: number } },
+): { recordVideo?: { dir: string; size: { width: number; height: number } } };
+export function videoFile(journey: Pick<JourneyRow, "id">, platform: Platform): string;
+
+export function assertNoRetries(config: { retries?: number; projects?: { name?: string; retries?: number }[] }): void;
+
+export const QUARANTINE_CAP: 1;
+export interface QuarantineEntry {
+  test: string;
+  reason: string;
+  issue: string;
+}
+export function quarantine(
+  entries: readonly QuarantineEntry[],
+  options?: { max?: number },
+): { entries: readonly QuarantineEntry[]; has(title: string): boolean };

package/src/journey.mjs

@@ -0,0 +1,162 @@
+// The shared journey kit (ADR-017 §7, krizaka/.github#423): what every product's customer journeys need, in one place.
+//
+// A journey is one customer promise told from a persona's point of view, run on the seeded cast. The kit gives them:
+// the catalogue format and its check, a persona signed in once per worker, the seeded cast, the masks of the live
+// values, the video hooks of the « videos from tests » rule, and the flake policy (retries 0, a capped quarantine).
+//
+//   import { personaSessions, journeyMaskSelectors, videoContextOptions } from "@krizaka/page-audit/journey";
+
+import { mkdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_BUDGET_SECONDS = 90;
+const PLATFORMS = Object.freeze(["web", "mobile"]);
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ISSUE = /^[\w.-]+\/[\w.-]+#\d+$/;
+const JOURNEY_SUFFIX = /\.journey\.[cm]?[jt]sx?$/;
+/** The journey id of a file path (`<id>.journey.ts`), or undefined. The base name is cut first: no backtracking over the path. */
+function journeyId(file) {
+  const base = file.slice(Math.max(file.lastIndexOf("/"), file.lastIndexOf("\\")) + 1);
+  const match = JOURNEY_SUFFIX.exec(base);
+  return match && match.index > 0 ? base.slice(0, match.index) : undefined;
+}
+
+/** The problems of one catalogue row (`journeys/journeys.json`), empty when it is a good journey. `cast` = the seeded persona ids. */
+export function validateJourney(journey, { cast } = {}) {
+  const problems = [];
+  const at = `journey « ${journey?.id ?? "?"} »`;
+  if (typeof journey?.id !== "string" || !KEBAB.test(journey.id)) problems.push(`${at}: id must be kebab-case`);
+  if (typeof journey?.promise !== "string" || !journey.promise.trim()) problems.push(`${at}: promise is empty`);
+  if (typeof journey?.persona !== "string" || !journey.persona) problems.push(`${at}: persona is missing`);
+  else if (cast && !cast.includes(journey.persona))
+    problems.push(`${at}: persona « ${journey.persona} » is not in the seeded cast (${cast.join(", ")})`);
+  if (!Array.isArray(journey?.platforms) || journey.platforms.length === 0) problems.push(`${at}: platforms is empty`);
+  else
+    for (const p of journey.platforms)
+      if (!PLATFORMS.includes(p)) problems.push(`${at}: platform « ${p} » is not one of ${PLATFORMS.join(", ")}`);
+  if (!Array.isArray(journey?.steps) || journey.steps.length === 0) problems.push(`${at}: steps is empty`);
+  const budget = journey?.budgetSeconds ?? DEFAULT_BUDGET_SECONDS;
+  if (!Number.isFinite(budget) || budget <= 0) problems.push(`${at}: budgetSeconds must be a positive number`);
+  return problems;
+}
+
+/** Files and rows must match: a file with no row, a row with no file, an id twice. `files` are paths of `<id>.journey.ts`. */
+export function checkCatalogue({ files, index }) {
+  const problems = [];
+  const fileIds = new Set(files.map(journeyId).filter(Boolean));
+  const seen = new Set();
+  for (const row of index) {
+    if (seen.has(row.id)) problems.push(`journeys.json lists « ${row.id} » twice`);
+    seen.add(row.id);
+    if (!fileIds.has(row.id)) problems.push(`journeys.json row « ${row.id} » has no file`);
+  }
+  for (const id of fileIds) if (!seen.has(id)) problems.push(`journey file « ${id} » has no row in journeys.json`);
+  return problems;
+}
+
+/** The rows that carry a tag (`smoke` runs on every pull request, the rest in the nightly pass). */
+export function journeysByTag(index, tag) {
+  return index.filter((j) => j.tags?.includes(tag));
+}
+
+/** The message when a run took longer than its journey's budget, `undefined` within it. */
+export function budgetProblem(journey, elapsedMs) {
+  const seconds = journey.budgetSeconds ?? DEFAULT_BUDGET_SECONDS;
+  if (elapsedMs <= seconds * 1000) return undefined;
+  return `journey « ${journey.id} » took ${Math.round(elapsedMs / 1000)} s, over its budget of ${seconds} s: split it, or the product is slow`;
+}
+
+async function written(file) {
+  try {
+    return (await stat(file)).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Persona sign-in once per worker. `signIn(persona, file)` signs in and writes the Playwright browser state to `file`
+ * (the app's own way: its form, its API). `stateFor(persona)` returns that file's path: the first call signs in, the
+ * next ones (also parallel ones) reuse it, so a worker never asks the sign-in more than once per persona (rate-limit
+ * safe). One file per worker; a failed sign-in is not remembered.
+ */
+export function personaSessions({ dir, signIn, worker = Number(process.env.TEST_WORKER_INDEX ?? 0) }) {
+  const inFlight = new Map();
+  return {
+    stateFor(persona) {
+      const known = inFlight.get(persona);
+      if (known) return known;
+      const file = join(dir, `${persona}.w${worker}.json`);
+      const pending = (async () => {
+        if (!(await written(file))) {
+          await mkdir(dirname(file), { recursive: true });
+          await signIn(persona, file);
+          if (!(await written(file))) throw new Error(`sign-in of « ${persona} » wrote no storage state to ${file}`);
+        }
+        return file;
+      })();
+      inFlight.set(persona, pending);
+      pending.catch(() => inFlight.delete(persona));
+      return pending;
+    },
+  };
+}
+
+/** A member of the seeded cast (the same people locally and deployed), or an error naming who exists. */
+export function seededPersona(cast, id) {
+  const person = cast[id];
+  if (!person) throw new Error(`« ${id} » is not in the seeded cast: ${Object.keys(cast).join(", ")}`);
+  return person;
+}
+
+/** What changes between two runs of the same build: dates, ids, anything marked `data-mask`. */
+export const JOURNEY_MASKS = Object.freeze([
+  "time",
+  "[data-mask]",
+  "[data-date]",
+  '[data-testid$="-id"]',
+  "[data-run-id]",
+]);
+
+/** The selectors to mask in a capture of a journey screen. */
+export function journeyMaskSelectors({ extra = [], defaults = true } = {}) {
+  return [...new Set([...(defaults ? JOURNEY_MASKS : []), ...extra])];
+}
+
+/** The size of a recorded video: the laptop of the visual matrix. */
+export const VIDEO_SIZE = Object.freeze({ width: 1280, height: 800 });
+
+/** Context options that record the run of a journey whose `video` is true (the source of the product video), none otherwise. */
+export function videoContextOptions(journey, { dir, size = VIDEO_SIZE }) {
+  if (!journey.video) return {};
+  return { recordVideo: { dir: join(dir, journey.id), size: { ...size } } };
+}
+
+/** The name the recorded video is published under. */
+export function videoFile(journey, platform) {
+  return `${journey.id}.${platform}.webm`;
+}
+
+/** A flake is a bug, not a retry: retries are 0 (top level and every project). */
+export function assertNoRetries(config) {
+  if ((config.retries ?? 0) > 0)
+    throw new Error(`retries is ${config.retries}: a flake is a bug, fix its cause (retries must be 0)`);
+  for (const project of config.projects ?? [])
+    if ((project.retries ?? 0) > 0)
+      throw new Error(`project « ${project.name} » sets retries ${project.retries}: retries must be 0`);
+}
+
+export const QUARANTINE_CAP = 1;
+
+/** The quarantine: a named test, why, and the issue that fixes it. Capped; the audit keeps running, only the assertion is skipped. */
+export function quarantine(entries, { max = QUARANTINE_CAP } = {}) {
+  if (entries.length > max) throw new Error(`the quarantine holds at most ${max} test(s), it has ${entries.length}`);
+  for (const e of entries) {
+    if (!e.test) throw new Error("a quarantine entry names its test");
+    if (!e.reason?.trim()) throw new Error(`quarantine « ${e.test} » needs a reason`);
+    if (!ISSUE.test(e.issue ?? ""))
+      throw new Error(`quarantine « ${e.test} » needs an issue as owner/repo#n, got « ${e.issue} »`);
+  }
+  const names = new Set(entries.map((e) => e.test));
+  return { entries, has: (title) => names.has(title) };
+}

package/src/page-audit.mjs

@@ -10,8 +10,12 @@ const nameOf = (el) => {
   const id = el.dataset?.testid;
   return el.tagName.toLowerCase() + (id ? "[" + id + "]" : "") + "." + className(el, 2);
 };
-const scrolls = (el) => ["auto", "scroll"].includes(getComputedStyle(el).overflowY) || ["auto", "scroll"].includes(getComputedStyle(el).overflowX);
-const meets = (ra, rb) => Math.min(ra.right, rb.right) - Math.max(ra.left, rb.left) > 2 && Math.min(ra.bottom, rb.bottom) - Math.max(ra.top, rb.top) > 2;
+const scrolls = (el) =>
+  ["auto", "scroll"].includes(getComputedStyle(el).overflowY) ||
+  ["auto", "scroll"].includes(getComputedStyle(el).overflowX);
+const meets = (ra, rb) =>
+  Math.min(ra.right, rb.right) - Math.max(ra.left, rb.left) > 2 &&
+  Math.min(ra.bottom, rb.bottom) - Math.max(ra.top, rb.top) > 2;
 const apart = (a, b) => !a.contains(b) && !b.contains(a);
 
 /** An element that pokes out only matters when nothing clips it: decorative layers (aria-hidden) and anything inside a clipping or scrolling ancestor are meant to extend. */
@@ -27,7 +31,12 @@ function wideOf(doc) {
   return [...document.querySelectorAll("body *")]
     .filter((el) => {
       const r = el.getBoundingClientRect();
-      return r.width > 0 && getComputedStyle(el).visibility !== "hidden" && (r.right > doc.clientWidth + 1 || r.left < -1) && !clipped(el);
+      return (
+        r.width > 0 &&
+        getComputedStyle(el).visibility !== "hidden" &&
+        (r.right > doc.clientWidth + 1 || r.left < -1) &&
+        !clipped(el)
+      );
     })
     .slice(0, 3)
     .map((el) => `${el.tagName.toLowerCase()}.${String(el.className).split(" ").slice(0, 3).join(".")}`);
@@ -36,12 +45,21 @@ function wideOf(doc) {
 /** A button's accessible name: its text, aria-label, aria-labelledby, title — or a <label for> pointing at it (a checkbox, a switch). */
 function named(b) {
   const labelled = !!b.id && !!document.querySelector(`label[for="${CSS.escape(b.id)}"]`);
-  return !!((b.textContent || "").trim() || b.getAttribute("aria-label") || b.getAttribute("aria-labelledby") || b.title || labelled);
+  return !!(
+    (b.textContent || "").trim() ||
+    b.getAttribute("aria-label") ||
+    b.getAttribute("aria-labelledby") ||
+    b.title ||
+    labelled
+  );
 }
 
 function unnamedOf() {
   const unnamed = [...document.querySelectorAll("button")].filter((b) => !named(b));
-  return { unnamedButtons: unnamed.length, unnamedSamples: unnamed.slice(0, 2).map((b) => b.outerHTML.slice(0, 160).replace(/\s+/g, " ")) };
+  return {
+    unnamedButtons: unnamed.length,
+    unnamedSamples: unnamed.slice(0, 2).map((b) => b.outerHTML.slice(0, 160).replace(/\s+/g, " ")),
+  };
 }
 
 function headerActionOf(doc) {
@@ -68,7 +86,14 @@ function keptBetween(el, panel) {
 }
 
 function notDrawn(el, r) {
-  return r.width === 0 || r.height === 0 || getComputedStyle(el).position === "fixed" || !!el.closest(ARIA_HIDDEN) || !!el.closest("[data-radix-popper-content-wrapper]") || folded(el);
+  return (
+    r.width === 0 ||
+    r.height === 0 ||
+    getComputedStyle(el).position === "fixed" ||
+    !!el.closest(ARIA_HIDDEN) ||
+    !!el.closest("[data-radix-popper-content-wrapper]") ||
+    folded(el)
+  );
 }
 
 function runsOut(el, panel, box) {
@@ -96,10 +121,14 @@ function spillOf(panels) {
 function overlapsOf(panels, spill) {
   const overlaps = [];
   for (const el of spill) {
-    for (const other of panels) if (apart(el, other) && meets(el.getBoundingClientRect(), other.getBoundingClientRect())) overlaps.push(`${nameOf(el)} over ${nameOf(other)}`);
+    for (const other of panels)
+      if (apart(el, other) && meets(el.getBoundingClientRect(), other.getBoundingClientRect()))
+        overlaps.push(`${nameOf(el)} over ${nameOf(other)}`);
   }
   panels.forEach((a, i) => {
-    for (const b of panels.slice(i + 1)) if (apart(a, b) && meets(a.getBoundingClientRect(), b.getBoundingClientRect())) overlaps.push(`${nameOf(a)} over ${nameOf(b)}`);
+    for (const b of panels.slice(i + 1))
+      if (apart(a, b) && meets(a.getBoundingClientRect(), b.getBoundingClientRect()))
+        overlaps.push(`${nameOf(a)} over ${nameOf(b)}`);
   });
   return overlaps;
 }
@@ -138,16 +167,27 @@ function isTopBar(el, width) {
   const pos = getComputedStyle(el).position;
   if (pos !== "fixed" && pos !== "sticky") return false;
   const r = topBoxOf(el).getBoundingClientRect();
-  return r.width > width * 0.5 && r.height > 8 && r.height < 200 && r.top < 160 && r.bottom > 0 && !el.closest("[data-top-chrome]");
+  return (
+    r.width > width * 0.5 &&
+    r.height > 8 &&
+    r.height < 200 &&
+    r.top < 160 &&
+    r.bottom > 0 &&
+    !el.closest("[data-top-chrome]")
+  );
 }
 
 function chromeOverlapsOf(doc) {
-  const chrome = [...document.querySelectorAll("[data-top-chrome]")].filter((el) => el.getBoundingClientRect().height > 0);
+  const chrome = [...document.querySelectorAll("[data-top-chrome]")].filter(
+    (el) => el.getBoundingClientRect().height > 0,
+  );
   const bars = [...document.querySelectorAll("body *")].filter((el) => isTopBar(el, doc.clientWidth)).map(topBoxOf);
   const stack = [...chrome, ...bars];
   const found = [];
   stack.forEach((a, i) => {
-    for (const b of stack.slice(i + 1)) if (apart(a, b) && meets(a.getBoundingClientRect(), b.getBoundingClientRect())) found.push(`${nameOf(a)} / ${nameOf(b)}`);
+    for (const b of stack.slice(i + 1))
+      if (apart(a, b) && meets(a.getBoundingClientRect(), b.getBoundingClientRect()))
+        found.push(`${nameOf(a)} / ${nameOf(b)}`);
   });
   return found;
 }
@@ -158,7 +198,14 @@ function clipsOf() {
     .filter((el) => {
       const r = el.getBoundingClientRect();
       const style = getComputedStyle(el);
-      return r.width > 4 && r.height > 4 && ["hidden", "clip"].includes(style.overflowX) && style.textOverflow !== "ellipsis" && el.scrollWidth > el.clientWidth + 1 && !clipped(el);
+      return (
+        r.width > 4 &&
+        r.height > 4 &&
+        ["hidden", "clip"].includes(style.overflowX) &&
+        style.textOverflow !== "ellipsis" &&
+        el.scrollWidth > el.clientWidth + 1 &&
+        !clipped(el)
+      );
     })
     .slice(0, 3)
     .map(nameOf);
@@ -185,12 +232,16 @@ function wrappedOf() {
 /** The whole measure of a page. Decorative layers (aria-hidden), fixed elements and anything inside a scroller are left out of the layout probes (yomizaka#435). */
 /** A heading with no text (and no image or labelled icon) says nothing to a screen reader. */
 function emptyHeadingsOf() {
-  return [...document.querySelectorAll("h1, h2, h3")].filter((h) => !(h.textContent || "").trim() && !h.querySelector("img, svg[aria-label]")).length;
+  return [...document.querySelectorAll("h1, h2, h3")].filter(
+    (h) => !(h.textContent || "").trim() && !h.querySelector("img, svg[aria-label]"),
+  ).length;
 }
 
 /** A file input that no label, `aria-label` or title names. */
 function unlabelledFilesOf() {
-  return [...document.querySelectorAll("input[type=file]")].filter((i) => !(i.getAttribute("aria-label") || i.getAttribute("aria-labelledby") || i.title || i.labels?.length)).length;
+  return [...document.querySelectorAll("input[type=file]")].filter(
+    (i) => !(i.getAttribute("aria-label") || i.getAttribute("aria-labelledby") || i.title || i.labels?.length),
+  ).length;
 }
 
 /** `<main>` with no text at all: the page answered but drew nothing (a route that fell through, a failed fetch). */
@@ -200,7 +251,9 @@ function emptyMainOf() {
 
 /** Height of every action of the page's main (a button-styled link): the tap targets the responsive guard keeps over `minAction`. */
 function actionsOf() {
-  return [...document.querySelectorAll("main a[class*='kz-button'], main a[data-slot='button'], main .kz-button")].filter((a) => a.getBoundingClientRect().width > 0).map((a) => Math.round(a.getBoundingClientRect().height));
+  return [...document.querySelectorAll("main a[class*='kz-button'], main a[data-slot='button'], main .kz-button")]
+    .filter((a) => a.getBoundingClientRect().width > 0)
+    .map((a) => Math.round(a.getBoundingClientRect().height));
 }
 
 /**
@@ -213,7 +266,12 @@ function frameOf(doc) {
   const rail = [...shell.querySelectorAll("nav")].find((n) => getComputedStyle(n).position === "sticky");
   return {
     top: Math.round(shell.getBoundingClientRect().top + window.scrollY),
-    forced: Math.round(Math.max(Number.parseFloat(getComputedStyle(shell).minHeight) || 0, rail ? rail.getBoundingClientRect().height : 0)),
+    forced: Math.round(
+      Math.max(
+        Number.parseFloat(getComputedStyle(shell).minHeight) || 0,
+        rail ? rail.getBoundingClientRect().height : 0,
+      ),
+    ),
     viewport: doc.clientHeight,
   };
 }
@@ -221,15 +279,24 @@ function frameOf(doc) {
 /** A landmark (`main`, `aside`, `header`, `nav`) whose content is wider than its own box, with nothing to scroll it. */
 function boxesOf() {
   return [...document.querySelectorAll("main, aside, header, nav")]
-    .filter((box) => getComputedStyle(box).overflowX === "visible" && box.scrollWidth > box.clientWidth + 1 && box.clientWidth > 0)
+    .filter(
+      (box) =>
+        getComputedStyle(box).overflowX === "visible" && box.scrollWidth > box.clientWidth + 1 && box.clientWidth > 0,
+    )
     .slice(0, 3)
     .map((box) => `<${box.tagName.toLowerCase()}> ${box.scrollWidth}px in ${box.clientWidth}px`);
 }
 
 /** The family contract of the page chrome: the page's own footers (not those of an article or a dialog), whether the first names Krizaka, a navigation landmark. */
 function landmarksOf() {
-  const footers = [...document.querySelectorAll("footer")].filter((f) => !f.closest("main, article, section, dialog, [role=dialog]"));
-  return { footers: footers.length, footerNamesKrizaka: /krizaka/i.test(footers[0]?.textContent || ""), nav: !!document.querySelector("nav") };
+  const footers = [...document.querySelectorAll("footer")].filter(
+    (f) => !f.closest("main, article, section, dialog, [role=dialog]"),
+  );
+  return {
+    footers: footers.length,
+    footerNamesKrizaka: /krizaka/i.test(footers[0]?.textContent || ""),
+    nav: !!document.querySelector("nav"),
+  };
 }
 
 /** A picture drawn at a real size that never loaded. */
@@ -250,15 +317,27 @@ function emptyControlsOf() {
     const box = el.getBoundingClientRect();
     const style = getComputedStyle(el);
     if (style.visibility === "hidden" || style.display === "none") continue;
-    if (box.width > 0 && box.height > 0 && box.height < 4) found.push(`collapsed control ${(el.getAttribute("aria-label") || el.textContent || "").trim().slice(0, 30)}`);
-    else if (box.width > 24 && box.height > 24 && !el.textContent?.trim() && !el.getAttribute("aria-label") && !el.getAttribute("aria-labelledby") && !el.querySelector("img, svg, video, picture, canvas")) found.push("empty tile");
+    if (box.width > 0 && box.height > 0 && box.height < 4)
+      found.push(`collapsed control ${(el.getAttribute("aria-label") || el.textContent || "").trim().slice(0, 30)}`);
+    else if (
+      box.width > 24 &&
+      box.height > 24 &&
+      !el.textContent?.trim() &&
+      !el.getAttribute("aria-label") &&
+      !el.getAttribute("aria-labelledby") &&
+      !el.querySelector("img, svg, video, picture, canvas")
+    )
+      found.push("empty tile");
   }
   return [...new Set(found)].slice(0, 3);
 }
 
 /** Elements whose inline style carries a colour that is not a token (`var(--kz-*)`). */
 function hardColorsOf() {
-  return [...document.querySelectorAll("[style]")].filter((e) => /#[0-9a-f]{3,8}\b|rgba?\(/i.test(e.getAttribute("style") || "") && !/var\(/.test(e.getAttribute("style") || "")).length;
+  return [...document.querySelectorAll("[style]")].filter(
+    (e) =>
+      /#[0-9a-f]{3,8}\b|rgba?\(/i.test(e.getAttribute("style") || "") && !/var\(/.test(e.getAttribute("style") || ""),
+  ).length;
 }
 
 /**
@@ -268,19 +347,36 @@ function hardColorsOf() {
  */
 function mapsOf() {
   return [...document.querySelectorAll(".maplibregl-map, .mapboxgl-map, .leaflet-container, [data-kz-map]")]
-    .filter((el) => el.getClientRects().length > 0 && !el.closest(ARIA_HIDDEN) && !folded(el) && !el.parentElement?.closest(".maplibregl-map, .mapboxgl-map, .leaflet-container, [data-kz-map]"))
+    .filter(
+      (el) =>
+        el.getClientRects().length > 0 &&
+        !el.closest(ARIA_HIDDEN) &&
+        !folded(el) &&
+        !el.parentElement?.closest(".maplibregl-map, .mapboxgl-map, .leaflet-container, [data-kz-map]"),
+    )
     .map((el) => {
       const box = el.getBoundingClientRect();
       const canvas = el.querySelector("canvas")?.getBoundingClientRect();
-      return { name: nameOf(el), width: Math.round(box.width), height: Math.round(box.height), canvas: !!canvas && canvas.width > 0 && canvas.height > 0, leaflet: el.classList.contains("leaflet-container"), tiles: el.querySelectorAll(".leaflet-tile-loaded").length };
+      return {
+        name: nameOf(el),
+        width: Math.round(box.width),
+        height: Math.round(box.height),
+        canvas: !!canvas && canvas.width > 0 && canvas.height > 0,
+        leaflet: el.classList.contains("leaflet-container"),
+        tiles: el.querySelectorAll(".leaflet-tile-loaded").length,
+      };
     });
 }
 
 function measurePage() {
   const doc = document.documentElement;
-  const panels = [...document.querySelectorAll("[data-panel], main section, main [role=region]")].filter((el) => !el.closest(ARIA_HIDDEN) && !folded(el));
+  const panels = [...document.querySelectorAll("[data-panel], main section, main [role=region]")].filter(
+    (el) => !el.closest(ARIA_HIDDEN) && !folded(el),
+  );
   const { overflowing, spill } = spillOf(panels);
-  const chips = [...document.querySelectorAll('[data-testid="audience-picker"] a')].map((a) => Math.round(a.getBoundingClientRect().height));
+  const chips = [...document.querySelectorAll('[data-testid="audience-picker"] a')].map((a) =>
+    Math.round(a.getBoundingClientRect().height),
+  );
   return {
     h1: document.querySelectorAll("h1").length,
     scrollWidth: doc.scrollWidth,
@@ -310,7 +406,44 @@ function measurePage() {
   };
 }
 
-const PROBES = [tooTall, wrappedOf, className, nameOf, scrolls, meets, apart, clipped, wideOf, named, unnamedOf, headerActionOf, folded, keptBetween, notDrawn, runsOut, spillOf, overlapsOf, cutBy, cutColumnsOf, topBoxOf, isTopBar, chromeOverlapsOf, clipsOf, emptyHeadingsOf, unlabelledFilesOf, emptyMainOf, actionsOf, frameOf, boxesOf, landmarksOf, brokenPicturesOf, emptyControlsOf, hardColorsOf, mapsOf, measurePage];
+const PROBES = [
+  tooTall,
+  wrappedOf,
+  className,
+  nameOf,
+  scrolls,
+  meets,
+  apart,
+  clipped,
+  wideOf,
+  named,
+  unnamedOf,
+  headerActionOf,
+  folded,
+  keptBetween,
+  notDrawn,
+  runsOut,
+  spillOf,
+  overlapsOf,
+  cutBy,
+  cutColumnsOf,
+  topBoxOf,
+  isTopBar,
+  chromeOverlapsOf,
+  clipsOf,
+  emptyHeadingsOf,
+  unlabelledFilesOf,
+  emptyMainOf,
+  actionsOf,
+  frameOf,
+  boxesOf,
+  landmarksOf,
+  brokenPicturesOf,
+  emptyControlsOf,
+  hardColorsOf,
+  mapsOf,
+  measurePage,
+];
 
 /** The expression Playwright runs in the page (`page.evaluate(auditPage)`): the probes, serialised together, then the measure. */
 export const auditPage = `(() => {\nconst ARIA_HIDDEN = ${JSON.stringify(ARIA_HIDDEN)};\n${PROBES.map((f) => `const ${f.name} = ${f.toString()};`).join("\n")}\nreturn measurePage();\n})()`;
@@ -323,11 +456,31 @@ export const auditPage = `(() => {\nconst ARIA_HIDDEN = ${JSON.stringify(ARIA_HI
 function accessibilityProblems(where, result, fileLabels) {
   const problems = [];
   if (result.emptyHeadings) problems.push(`${where}: ${result.emptyHeadings} empty heading(s)`);
-  if (fileLabels && result.unlabelledFiles) problems.push(`${where}: ${result.unlabelledFiles} file input(s) without a label`);
+  if (fileLabels && result.unlabelledFiles)
+    problems.push(`${where}: ${result.unlabelledFiles} file input(s) without a label`);
   return problems;
 }
 
-export function problemsOf(where, result, { errors = [], h1 = false, headerAction = false, fileLabels = false, status, emptyMain = false, frame = false, minAction, boxes = false, landmarks, pictures = false, emptyControls = false, hardColors = false, maps = false } = {}) {
+export function problemsOf(
+  where,
+  result,
+  {
+    errors = [],
+    h1 = false,
+    headerAction = false,
+    fileLabels = false,
+    status,
+    emptyMain = false,
+    frame = false,
+    minAction,
+    boxes = false,
+    landmarks,
+    pictures = false,
+    emptyControls = false,
+    hardColors = false,
+    maps = false,
+  } = {},
+) {
   return [
     ...statusProblems(where, status),
     ...(emptyMain && result.emptyMain ? [`${where}: empty <main>`] : []),
@@ -335,9 +488,13 @@ export function problemsOf(where, result, { errors = [], h1 = false, headerActio
     ...(minAction ? actionProblems(where, result.actions ?? [], minAction) : []),
     ...(boxes ? boxProblems(where, result.boxes ?? []) : []),
     ...(landmarks ? landmarkProblems(where, result.landmarks, landmarks) : []),
-    ...(pictures && result.brokenPictures?.length ? [`${where}: broken picture ${result.brokenPictures.join(", ")}`] : []),
+    ...(pictures && result.brokenPictures?.length
+      ? [`${where}: broken picture ${result.brokenPictures.join(", ")}`]
+      : []),
     ...(emptyControls ? (result.emptyControls ?? []).map((c) => `${where}: ${c}`) : []),
-    ...(hardColors && result.hardColors ? [`${where}: ${result.hardColors} element(s) with a hard-coded colour in an inline style`] : []),
+    ...(hardColors && result.hardColors
+      ? [`${where}: ${result.hardColors} element(s) with a hard-coded colour in an inline style`]
+      : []),
     ...(maps ? mapProblems(where, result.maps ?? [], maps) : []),
     ...errorsOf(where, errors),
     ...layoutProblems(where, result),
@@ -361,7 +518,8 @@ function mapProblems(where, found, option) {
   const out = [];
   for (const m of found) {
     if (m.width < min || m.height < min) out.push(`${where}: the map ${m.name} is ${m.width}x${m.height} px (empty)`);
-    else if (m.leaflet ? m.tiles === 0 : !m.canvas) out.push(`${where}: the map ${m.name} ${m.leaflet ? "has no loaded tile" : "has no canvas"}`);
+    else if (m.leaflet ? m.tiles === 0 : !m.canvas)
+      out.push(`${where}: the map ${m.name} ${m.leaflet ? "has no loaded tile" : "has no canvas"}`);
   }
   return out;
 }
@@ -373,15 +531,23 @@ function errorsOf(where, errors) {
 /** Overflow, elements past the edge, boxes that cover or cut one another, a token wrapped per character, the error state. */
 function layoutProblems(where, result) {
   const problems = [];
-  if (result.scrollWidth > result.clientWidth) problems.push(`${where}: scrollWidth ${result.scrollWidth} > ${result.clientWidth} (${result.wide.join(", ")})`);
+  if (result.scrollWidth > result.clientWidth)
+    problems.push(`${where}: scrollWidth ${result.scrollWidth} > ${result.clientWidth} (${result.wide.join(", ")})`);
   else if (result.wide.length) problems.push(`${where}: elements past the edge (${result.wide.join(", ")})`);
-  const lists = [[result.overflowing, "overflows its panel"], [result.overlaps, "covers a neighbouring section"], [result.cutColumns, "is cut off"]];
+  const lists = [
+    [result.overflowing, "overflows its panel"],
+    [result.overlaps, "covers a neighbouring section"],
+    [result.cutColumns, "is cut off"],
+  ];
   for (const [list, words] of lists) {
     if (list?.length) problems.push(`${where}: ${words} (${list.join(", ")})`);
   }
-  if (result.wrapped?.length) problems.push(`${where}: a token wraps one character per line (${result.wrapped.join(", ")}) — truncate it`);
-  if (result.segmentError) problems.push(`${where}: the page rendered its error state (segment-error), e.g. React #441`);
-  if (result.chromeOverlaps?.length) problems.push(`${where}: the top chrome chromeOverlaps (${result.chromeOverlaps.slice(0, 2).join(", ")})`);
+  if (result.wrapped?.length)
+    problems.push(`${where}: a token wraps one character per line (${result.wrapped.join(", ")}) — truncate it`);
+  if (result.segmentError)
+    problems.push(`${where}: the page rendered its error state (segment-error), e.g. React #441`);
+  if (result.chromeOverlaps?.length)
+    problems.push(`${where}: the top chrome chromeOverlaps (${result.chromeOverlaps.slice(0, 2).join(", ")})`);
   if (result.clips?.length) problems.push(`${where}: content cut inside its box (${result.clips.join(", ")})`);
   return problems;
 }
@@ -416,7 +582,9 @@ function statusProblems(where, status) {
 /** The signed-in frame forces a scroll when what it asks of the screen (its shell, its rail) does not fit under what is above it. */
 function frameProblems(where, frame) {
   if (!frame || frame.top + frame.forced <= frame.viewport + 1) return [];
-  return [`${where}: the frame forces a scroll (starts at ${frame.top} px and asks ${frame.forced} px of a ${frame.viewport} px screen)`];
+  return [
+    `${where}: the frame forces a scroll (starts at ${frame.top} px and asks ${frame.forced} px of a ${frame.viewport} px screen)`,
+  ];
 }
 
 /** A button-styled action under `min` px tall is hard to tap. */
@@ -432,7 +600,8 @@ function boxProblems(where, boxes) {
 function landmarkProblems(where, found, kind) {
   const problems = [];
   if (kind === "public") {
-    if (found.footers !== 1) problems.push(`${where}: ${found.footers} page footers (one « A Krizaka product » footer expected)`);
+    if (found.footers !== 1)
+      problems.push(`${where}: ${found.footers} page footers (one « A Krizaka product » footer expected)`);
     else if (!found.footerNamesKrizaka) problems.push(`${where}: the footer does not name Krizaka`);
   } else if (found.footers > 1) problems.push(`${where}: ${found.footers} page footers (at most one)`);
   if (kind !== "auth" && !found.nav) problems.push(`${where}: no <nav> landmark`);

package/src/run.mjs

@@ -9,7 +9,8 @@ export const WIDTHS = [360, 390, 430, 768, 1024, 1440];
 export const THEMES = ["dark", "light"];
 
 /** A blocked third-party resource is not a page error; a script error and a hydration mismatch are. `ignore`: the messages the app tolerates. */
-export const isPageError = (message, ignore = [/Failed to load resource/]) => message.type() === "error" && !ignore.some((re) => re.test(message.text()));
+export const isPageError = (message, ignore = [/Failed to load resource/]) =>
+  message.type() === "error" && !ignore.some((re) => re.test(message.text()));
 
 async function chromiumOf(launch) {
   if (launch) return launch();
@@ -55,7 +56,10 @@ const nameOfRoute = (r) => r.name ?? r.url;
  */
 export async function routesFromSitemap(base, { first = ["/"], limit = 14, fetcher = fetch } = {}) {
   const origin = base.replace(/\/$/, "");
-  const xml = await fetcher(`${origin}/sitemap.xml`).then((r) => (r.ok ? r.text() : null), () => null);
+  const xml = await fetcher(`${origin}/sitemap.xml`).then(
+    (r) => (r.ok ? r.text() : null),
+    () => null,
+  );
   if (xml === null) return null;
   const paths = [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => new URL(m[1]).pathname || "/");
   return [...new Set([...first, ...paths])].slice(0, limit);
@@ -66,8 +70,18 @@ async function a11yOf(a11y) {
   if (!a11y) return null;
   const lib = await import("@krizaka/a11y-audit");
   const kinds = { public: { collector: new lib.A11yCollector(a11y.app), baseline: a11y.baseline } };
-  if (a11y.session) kinds.session = { collector: new lib.A11yCollector(a11y.session.app), baseline: a11y.session.baseline, optional: true };
-  return { lib, kinds, widths: a11y.widths ?? [390, 1440], log: a11y.log ?? ((line) => process.stdout.write(`${line}\n`)) };
+  if (a11y.session)
+    kinds.session = {
+      collector: new lib.A11yCollector(a11y.session.app),
+      baseline: a11y.session.baseline,
+      optional: true,
+    };
+  return {
+    lib,
+    kinds,
+    widths: a11y.widths ?? [390, 1440],
+    log: a11y.log ?? ((line) => process.stdout.write(`${line}\n`)),
+  };
 }
 
 /** The ratchet's verdict, per kind. A baseline not recorded yet (`optional`) is counted, not enforced, until `--a11y-init`. */
@@ -75,7 +89,9 @@ function a11yProblems(state) {
   const problems = [];
   for (const { collector, baseline, optional } of Object.values(state.kinds)) {
     if (optional && !existsSync(baseline) && !process.argv.includes("--a11y-init")) {
-      state.log(`· a11y baseline missing: counted, not enforced (${collector.summary().join("; ") || "no violation"}); record it with --a11y-init`);
+      state.log(
+        `· a11y baseline missing: counted, not enforced (${collector.summary().join("; ") || "no violation"}); record it with --a11y-init`,
+      );
       continue;
     }
     const guard = state.lib.finish(collector, { baseline });
@@ -92,7 +108,10 @@ function statusOf(response, checks) {
 }
 
 /** One route at one width: load, settle, measure, screenshot. */
-async function measure(page, { base, spec, viewport, settleMs, prepare, checks, errors, where, shots, a11y, kind, theme }) {
+async function measure(
+  page,
+  { base, spec, viewport, settleMs, prepare, checks, errors, where, shots, a11y, kind, theme },
+) {
   await resizeSettled(page, viewport);
   // « load » and the faces, not « networkidle »: router prefetches can keep the page from ever going idle.
   const response = await loadSettled(page, `${base}${spec.url}`);
@@ -131,7 +150,9 @@ async function auditPageRoutes(page, routes, o) {
   for (const spec of routes) {
     for (const w of o.widths) {
       const viewport = viewportOf(w, o.height);
-      problems.push(...(await measureWithRetries(page, o, spec, viewport, `${nameOfRoute(spec)} @${viewport.width} ${o.theme}`)));
+      problems.push(
+        ...(await measureWithRetries(page, o, spec, viewport, `${nameOfRoute(spec)} @${viewport.width} ${o.theme}`)),
+      );
     }
   }
   return problems;
@@ -146,7 +167,11 @@ async function newPage(browser, o, extra = {}) {
 
 /** The signed-in pages of one theme: a context with the session (a stored state, or `signIn` on the context), the routes the session names, then the flagged ones. */
 async function auditSession(browser, session, flagged, o) {
-  const { context, page, errors } = await newPage(browser, o, session.storageState ? { storageState: session.storageState } : {});
+  const { context, page, errors } = await newPage(
+    browser,
+    o,
+    session.storageState ? { storageState: session.storageState } : {},
+  );
   try {
     if (session.signIn) await session.signIn(context, { base: o.base, theme: o.theme, page });
     const own = session.routes ? await session.routes(page, { base: o.base, theme: o.theme }) : [];
@@ -175,7 +200,23 @@ async function auditSession(browser, session, flagged, o) {
  * @param {() => Promise<object>} [o.launch]  returns a Playwright browser (default: chromium of playwright-core)
  * @returns {Promise<string[]>} the problems, empty when the pages are fine
  */
-export async function auditRoutes({ base, routes, widths = WIDTHS, themes = THEMES, height = 900, themeKey = "kz-theme", shots, settleMs = 300, checks = {}, ignoreConsole, attempts = 1, a11y, session, prepare, launch }) {
+export async function auditRoutes({
+  base,
+  routes,
+  widths = WIDTHS,
+  themes = THEMES,
+  height = 900,
+  themeKey = "kz-theme",
+  shots,
+  settleMs = 300,
+  checks = {},
+  ignoreConsole,
+  attempts = 1,
+  a11y,
+  session,
+  prepare,
+  launch,
+}) {
   const browser = await chromiumOf(launch);
   const state = await a11yOf(a11y);
   const specs = routes.map(specOf);
@@ -184,11 +225,25 @@ export async function auditRoutes({ base, routes, widths = WIDTHS, themes = THEM
   const problems = [];
   try {
     for (const theme of themes) {
-      const o = { base, widths, height, theme, themeKey, shots, settleMs, checks, ignoreConsole, attempts, prepare, a11y: state };
+      const o = {
+        base,
+        widths,
+        height,
+        theme,
+        themeKey,
+        shots,
+        settleMs,
+        checks,
+        ignoreConsole,
+        attempts,
+        prepare,
+        a11y: state,
+      };
       const { context, page, errors } = await newPage(browser, o);
       problems.push(...(await auditPageRoutes(page, plain, { ...o, errors, kind: "public" })));
       await context.close();
-      if (session && (session.routes || flagged.length)) problems.push(...(await auditSession(browser, session, flagged, o)));
+      if (session && (session.routes || flagged.length))
+        problems.push(...(await auditSession(browser, session, flagged, o)));
     }
   } finally {
     await browser.close();

package/src/self-test.mjs

@@ -1,6 +1,27 @@
 // The audit proven on its own fixtures, in a real browser: each broken fixture must be reported, the fine ones must not.
 // A guard that stopped seeing is itself a red build.
-import { BOX_TOO_WIDE, BROKEN_PARTS, CARD_OVER_NEXT, CHROME_BAD, CHROME_FINE, COLUMN_CUT, EMPTY_MAIN, FINE, FOLDED_SECTION, FRAME_FITS, FRAME_FORCES_SCROLL, HIDDEN_CONTENT, MAP_COLLAPSED, MAP_FINE, MAP_HIDDEN, MAP_NO_CANVAS, SECTIONS_OVERLAP, SMALL_ACTION, TOKEN_IN_STRETCHED_ROW, TOKEN_WRAPPED } from "./fixtures.mjs";
+import {
+  BOX_TOO_WIDE,
+  BROKEN_PARTS,
+  CARD_OVER_NEXT,
+  CHROME_BAD,
+  CHROME_FINE,
+  COLUMN_CUT,
+  EMPTY_MAIN,
+  FINE,
+  FOLDED_SECTION,
+  FRAME_FITS,
+  FRAME_FORCES_SCROLL,
+  HIDDEN_CONTENT,
+  MAP_COLLAPSED,
+  MAP_FINE,
+  MAP_HIDDEN,
+  MAP_NO_CANVAS,
+  SECTIONS_OVERLAP,
+  SMALL_ACTION,
+  TOKEN_IN_STRETCHED_ROW,
+  TOKEN_WRAPPED,
+} from "./fixtures.mjs";
 import { auditPage, problemsOf } from "./page-audit.mjs";
 import { auditContext } from "./settle.mjs";
 
@@ -30,7 +51,17 @@ const FINES = [
   ["a short token in a row a taller neighbour stretches", TOKEN_IN_STRETCHED_ROW],
 ];
 /** Fixtures that must stay clean even with every opt-in check on. */
-const ALL = { emptyMain: true, frame: true, minAction: 36, boxes: true, pictures: true, emptyControls: true, hardColors: true, landmarks: "public", maps: true };
+const ALL = {
+  emptyMain: true,
+  frame: true,
+  minAction: 36,
+  boxes: true,
+  pictures: true,
+  emptyControls: true,
+  hardColors: true,
+  landmarks: "public",
+  maps: true,
+};
 const FINES_STRICT = [
   ["a frame that fits its screen", FRAME_FITS, { frame: true, emptyMain: false }],
   ["the family chrome", CHROME_FINE, ALL],
@@ -57,7 +88,8 @@ export async function selfTest({ launch } = {}) {
     const page = await (await auditContext(browser, { viewport: { width: 1280, height: 800 } })).newPage();
     for (const [name, html, pattern, checks] of EXPECT) {
       const problems = await problemsOn(page, html, checks);
-      if (!problems.some((p) => pattern.test(p))) failures.push(`the audit does not see ${String(name)}: ${problems.join(" | ") || "no problem reported"}`);
+      if (!problems.some((p) => pattern.test(p)))
+        failures.push(`the audit does not see ${String(name)}: ${problems.join(" | ") || "no problem reported"}`);
     }
     for (const [name, html] of FINES) failures.push(...(await reported(page, name, html)));
     await page.setViewportSize({ width: 1280, height: 700 });

package/src/settle.mjs

@@ -28,7 +28,11 @@ export async function auditContext(browser, options) {
 
 /** Resolves once no view transition is running (none starts under reduced motion; this makes the wait explicit). */
 export const settled = (page) =>
-  page.waitForFunction(() => !document.activeViewTransition && !document.documentElement.matches(":active-view-transition"), null, { timeout: 10_000 });
+  page.waitForFunction(
+    () => !document.activeViewTransition && !document.documentElement.matches(":active-view-transition"),
+    null,
+    { timeout: 10_000 },
+  );
 
 /**
  * Loads a page, then waits for the faces and for the transitions: what is read afterwards is final. Returns the response.

package/src/visual.d.ts

@@ -1,6 +1,9 @@
-import type { Browser,Page } from "playwright-core";
+import type { Browser, Page } from "playwright-core";
 
-export interface Size { width: number; height: number }
+export interface Size {
+  width: number;
+  height: number;
+}
 export const VIEWPORTS: Readonly<{ desktop: Size; phone: Size }>;
 export const VISUAL_THEMES: readonly ["light", "dark"];
 export const FROZEN_TIME: string;
@@ -8,19 +11,43 @@ export const VISUAL_LOCALE: string;
 export const VISUAL_TIME_ZONE: string;
 export const FREEZE_CSS: string;
 export interface Journey {
-  name: string; path: string | ((page: Page, o: { origin: string }) => Promise<string>); session?: boolean; mask?: string[]; viewports?: string[];
+  name: string;
+  path: string | ((page: Page, o: { origin: string }) => Promise<string>);
+  session?: boolean;
+  mask?: string[];
+  viewports?: string[];
   ready?: string | ((page: Page) => Promise<unknown>);
   firstPaint?: true | { hold: string[] };
 }
-export interface Cell { viewport: string; size: Size; theme: string; snapshot: string }
-export function visualMatrix(journey: Journey, options?: { viewports?: Record<string, Size>; themes?: readonly string[] }): Cell[];
-export function visualContextOptions(o: { size: Size; theme: string; javaScript?: boolean; storageState?: unknown }): Record<string, unknown>;
+export interface Cell {
+  viewport: string;
+  size: Size;
+  theme: string;
+  snapshot: string;
+}
+export function visualMatrix(
+  journey: Journey,
+  options?: { viewports?: Record<string, Size>; themes?: readonly string[] },
+): Cell[];
+export function visualContextOptions(o: {
+  size: Size;
+  theme: string;
+  javaScript?: boolean;
+  storageState?: unknown;
+}): Record<string, unknown>;
 export function initVisualPage(o: { theme: string; themeKey: string }): void;
 export function prepareVisualPage(page: Page, o?: { theme?: string; themeKey?: string; now?: string }): Promise<void>;
 export function settleForShot(page: Page, o?: { javaScript?: boolean }): Promise<void>;
 export function shotOptions(o?: { mask?: string[]; page?: Page }): Record<string, unknown>;
 export function defineJourneyTests(o: {
-  test: unknown; expect: unknown; journeys: Journey[]; signIn: (page: Page, o: { base?: string }) => Promise<void>;
-  base?: string; viewports?: Record<string, Size>; themes?: readonly string[]; themeKey?: string; now?: string;
+  test: unknown;
+  expect: unknown;
+  journeys: Journey[];
+  signIn: (page: Page, o: { base?: string }) => Promise<void>;
+  base?: string;
+  viewports?: Record<string, Size>;
+  themes?: readonly string[];
+  themeKey?: string;
+  now?: string;
 }): void;
 export type { Browser };

package/src/visual.mjs

@@ -31,7 +31,12 @@ export function visualMatrix(journey, { viewports = VIEWPORTS, themes = VISUAL_T
     if (!viewports[viewport]) throw new Error(`unknown viewport « ${viewport} » in journey « ${journey.name} »`);
     for (const theme of themes) {
       const suffix = journey.firstPaint ? "-first-paint" : "";
-      cells.push({ viewport, size: viewports[viewport], theme, snapshot: `${journey.name}${suffix}-${viewport}-${theme}.png` });
+      cells.push({
+        viewport,
+        size: viewports[viewport],
+        theme,
+        snapshot: `${journey.name}${suffix}-${viewport}-${theme}.png`,
+      });
     }
   }
   return cells;
@@ -53,7 +58,8 @@ export function visualContextOptions({ size, theme, javaScript = true, storageSt
 }
 
 /** The style every capture carries: nothing moves, nothing blinks. */
-export const FREEZE_CSS = "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important;scroll-behavior:auto!important}";
+export const FREEZE_CSS =
+  "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important;scroll-behavior:auto!important}";
 
 /** Runs before the page's own scripts: the theme the app reads, no View Transition. */
 export const initVisualPage = ({ theme, themeKey }) => {
@@ -74,8 +80,10 @@ export async function prepareVisualPage(page, { theme, themeKey = "kz-theme", no
 
 /** Waits until what is on screen is final: the faces, the images, the transitions. */
 export async function settleForShot(page, { javaScript = true } = {}) {
-  await page.addStyleTag({ content: FREEZE_CSS });
+  // With JavaScript off, Playwright cannot run a script in the page: addStyleTag never returns (the first paint hung for the whole test timeout).
+  // Nothing moves without scripts, and `animations: "disabled"` of the screenshot still freezes CSS animations.
   if (!javaScript) return;
+  await page.addStyleTag({ content: FREEZE_CSS });
   await page.evaluate(() => document.fonts.ready);
   await settled(page);
   await page.evaluate(() =>
@@ -104,11 +112,23 @@ export function shotOptions({ mask = [], page } = {}) {
  * now: the instant of the browser clock (default FROZEN_TIME); an app whose seed stamps rows with the day of the run passes that moment.
  * signIn(page, { base }): signs the persona in; its cookies are kept and reused by every signed-in capture of the worker.
  */
-export function defineJourneyTests({ test, expect, journeys, signIn, base, viewports = VIEWPORTS, themes = VISUAL_THEMES, themeKey = "kz-theme", now = FROZEN_TIME }) {
+export function defineJourneyTests({
+  test,
+  expect,
+  journeys,
+  signIn,
+  base,
+  viewports = VIEWPORTS,
+  themes = VISUAL_THEMES,
+  themeKey = "kz-theme",
+  now = FROZEN_TIME,
+}) {
   let session;
   const sessionState = (browser) => {
     session ??= (async () => {
-      const context = await browser.newContext(visualContextOptions({ size: viewports.desktop ?? Object.values(viewports)[0], theme: "light" }));
+      const context = await browser.newContext(
+        visualContextOptions({ size: viewports.desktop ?? Object.values(viewports)[0], theme: "light" }),
+      );
       const page = await context.newPage();
       await signIn(page, { base });
       const state = await context.storageState();
@@ -119,17 +139,24 @@ export function defineJourneyTests({ test, expect, journeys, signIn, base, viewp
   };
   for (const journey of journeys) {
     for (const cell of visualMatrix(journey, { viewports, themes })) {
-      test(`${journey.name} · ${cell.viewport} · ${cell.theme}${journey.firstPaint ? " · first paint" : ""}`, async ({ browser, baseURL }) => {
+      test(`${journey.name} · ${cell.viewport} · ${cell.theme}${journey.firstPaint ? " · first paint" : ""}`, async ({
+        browser,
+        baseURL,
+      }) => {
         const origin = base ?? baseURL;
         const javaScript = !(journey.firstPaint === true);
         const storageState = journey.session ? await sessionState(browser) : undefined;
-        const context = await browser.newContext(visualContextOptions({ size: cell.size, theme: cell.theme, javaScript, storageState }));
+        const context = await browser.newContext(
+          visualContextOptions({ size: cell.size, theme: cell.theme, javaScript, storageState }),
+        );
         try {
           const page = await context.newPage();
           await prepareVisualPage(page, { theme: cell.theme, themeKey, now });
           for (const pattern of journey.firstPaint?.hold ?? []) await page.route(pattern, () => undefined);
           const path = typeof journey.path === "function" ? await journey.path(page, { origin }) : journey.path;
-          await page.goto(new URL(path, origin).toString(), { waitUntil: journey.firstPaint ? "domcontentloaded" : "load" });
+          await page.goto(new URL(path, origin).toString(), {
+            waitUntil: journey.firstPaint ? "domcontentloaded" : "load",
+          });
           if (typeof journey.ready === "string") await page.locator(journey.ready).first().waitFor();
           else if (journey.ready) await journey.ready(page);
           await settleForShot(page, { javaScript });