@krizaka/page-audit 0.5.1 → 0.7.0

package/README.md

@@ -25,7 +25,7 @@ Opt-in through `checks` (nothing changes for a repo that does not ask): `status`
 (the signed-in frame, `[data-app-frame-slot]`, forces a scroll), `minAction` (a button-styled action under N px), `boxes` (a landmark
 wider than its box), `landmarks` (`"public"` one footer naming Krizaka and a nav, `"app"`, `"auth"`), `pictures`, `emptyControls`,
 `hardColors`, `maps` (an empty map, akinaza#488: a GL / Leaflet / `[data-kz-map]` box under 120 px on a side, a GL map with no canvas,
-a Leaflet map with no loaded tile; `maps: { required: true }` also fails a page that should draw one but has none). Console noise the app tolerates: `ignoreConsole: [/…/]` (`[]` counts every error); `attempts` retries a route.
+a Leaflet map with no loaded tile; `maps: { required: true }` also fails a page that should draw one but has none), `controlOverlaps` (two interactive elements that share pixels on screen, one not inside the other — akinaza#214: the composer's title over a row). Console noise the app tolerates: `ignoreConsole: [/…/]` (`[]` counts every error); `attempts` retries a route.
 
 ```js
 const routes = await routesFromSitemap(base, { first: ["/", "/docs"], limit: 14 }); // a crawl as the route source (null: nothing answers)
@@ -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.1",
+  "version": "0.7.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.1"
+    "@krizaka/config": "^0.19.0"
   },
   "engines": {
     "node": ">=22"

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,54 @@ 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>`);
+
+/** Two controls on top of each other: a title button over a row's button (akinaza#214, the composer's « Style » over « Réservation »). */
+export const CONTROLS_OVERLAP = page(
+  `<button style="display:block;width:200px;height:40px">Réservation</button><button style="display:block;width:200px;height:40px;margin-top:-20px;position:relative">Style</button>`,
+);
+/** Controls that sit side by side, a control inside a label, a hidden checkbox and a control scrolled out of its list: none overlaps. */
+export const CONTROLS_FINE = page(
+  `<div style="display:flex;gap:8px"><button style="width:100px;height:40px">A</button><button style="width:100px;height:40px">B</button></div><label style="display:block"><input type="checkbox"> Remember</label><div style="height:60px;overflow:auto"><button style="display:block;width:100px;height:40px">1</button><button style="display:block;width:100px;height:40px">2</button><button style="display:block;width:100px;height:40px">3</button></div><button style="display:block;width:100px;height:40px;margin-top:8px">After</button>`,
+);

package/src/index.d.ts

@@ -5,35 +5,76 @@ 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 };
+  /** Two interactive elements (buttons, links, inputs, radios…) that share pixels on screen, one not inside the other: one of them cannot be clicked. The box is cut by clipping and scrolling ancestors. */
+  controlOverlaps?: 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) };
+}