@krizaka/page-audit 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @krizaka/page-audit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The page audit of every Krizaka app, in one place (ADR-013: one source per rule set). It measures a rendered page in a real browser:
+horizontal overflow, a card out of its panel, sections covering each other, a column cut by a clipping ancestor, top chrome that
+overlaps, content cut inside its box, a token wrapped per character, unnamed buttons, empty headings. Closed `<details>`, `aria-hidden`
+layers, scrollers and fixed elements are not counted. Library code, not UI: it lives in krizaka-ts.
+
+```bash
+npm i -D @krizaka/page-audit playwright-core
+npx krizaka-page-audit --self-test                                       # proves it on its own fixtures
+npx krizaka-page-audit --base http://localhost:3000 --routes /en,/fr --widths 360,390,1440 --themes dark,light
+```
+
+```js
+import { auditRoutes, auditContext, loadSettled, resizeSettled, auditPage, problemsOf } from "@krizaka/page-audit";
+const problems = await auditRoutes({ base, routes: ["/en", "/fr"], checks: { h1: true } }); // [] when fine
+```
+
+`auditContext` / `loadSettled` / `resizeSettled` open a context with reduced motion and no View Transition, and wait for none to run
+before anything is measured (yomizaka#354). `prepare(page, route)` signs in or seeds; `launch` gives your own browser.
+
+## The dev-preview crawls, in one audit (0.3)
+
+Opt-in through `checks` (nothing changes for a repo that does not ask): `status` (HTTP 4xx/5xx or no response), `emptyMain`, `frame`
+(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`. 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)
+await auditRoutes({
+  base, routes: [...routes, { url: "/login", chrome: "auth" }, { url: "/chat", session: true, chrome: "app" }],
+  widths: [{ width: 1440, height: 900 }, { width: 390, height: 844 }],
+  session: { storageState }, // or { signIn(context, { base, theme }) {…}, routes: async (page) => […] } for pages found once signed in
+  a11y: { app: "my-app", baseline: "a11y-baseline.json", widths: [390, 1440], session: { app: "my-app-app", baseline: "a11y-baseline.app.json" } },
+  checks: { status: true, emptyMain: true, minAction: 36, landmarks: "public", frame: true },
+});
+```
+
+`a11y` runs axe through `@krizaka/a11y-audit` (an optional peer) and ratchets with the repo's own baseline file; `--a11y-update` and
+`--a11y-init` work as there. The CLI takes `--sitemap`, `--status`, `--empty-main`, `--min-action`, `--a11y app:baseline.json`.

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@krizaka/page-audit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.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",
+    "audit",
+    "overflow",
+    "layout",
+    "playwright"
+  ],
+  "homepage": "https://ts.krizaka.com/page-audit",
+  "bugs": "https://github.com/krizaka/krizaka-ts/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krizaka/krizaka-ts.git",
+    "directory": "packages/page-audit"
+  },
+  "license": "Apache-2.0",
+  "author": "Krizaka (https://www.krizaka.com)",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "bin": {
+    "krizaka-page-audit": "./src/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs"
+    },
+    "./settle": {
+      "types": "./src/index.d.ts",
+      "import": "./src/settle.mjs"
+    },
+    "./fixtures": "./src/fixtures.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@krizaka/a11y-audit": ">=0.2.0",
+    "playwright-core": ">=1.40"
+  },
+  "peerDependenciesMeta": {
+    "@krizaka/a11y-audit": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@krizaka/a11y-audit": "0.2.0",
+    "@types/node": "^22.10.0",
+    "eslint": "^9.39.0",
+    "playwright-core": "^1.55.0",
+    "vitest": "^4.1.11",
+    "@krizaka/config": "^0.14.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "typecheck": "node --check src/index.mjs",
+    "test": "vitest run",
+    "check": "pnpm run lint && pnpm run test"
+  }
 }

package/src/cli.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// krizaka-page-audit --base http://localhost:3000 --routes /en,/fr [--widths 360,390,1440] [--themes dark,light]
+//                    [--theme-key kz-theme] [--h1] [--shots dir]
+//                    [--sitemap [--limit 14]] [--status] [--empty-main] [--min-action 36] [--a11y app:baseline.json]     |     krizaka-page-audit --self-test
+import { auditRoutes, routesFromSitemap, THEMES, WIDTHS } from "./run.mjs";
+import { selfTest } from "./self-test.mjs";
+
+const arg = (name, fallback) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? process.argv[i + 1] : fallback;
+};
+const list = (value, fallback) => (value ? value.split(",").filter(Boolean) : fallback);
+
+if (process.argv.includes("--self-test")) {
+  const failures = await selfTest();
+  if (failures.length) {
+    console.error(`page-audit self-test failed:\n  ${failures.join("\n  ")}`);
+    process.exit(1);
+  }
+  console.log("page-audit self-test: every broken layout seen, the fine ones clean");
+} 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"), ["/"]);
+  if (!routes) {
+    console.error(`Nothing answers at ${base}/sitemap.xml`);
+    process.exit(2);
+  }
+  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 } });
+  if (problems.length) {
+    console.error(`${problems.length} page problem(s):\n  ${problems.join("\n  ")}`);
+    process.exit(1);
+  }
+  console.log(`no page problem: ${routes.length} routes x ${widths.length} widths x ${themes.length} themes`);
+}

package/src/fixtures.mjs

@@ -0,0 +1,45 @@
+// 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>`;
+
+/** 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(
+  `<section data-testid="binder" style="height:200px"><h2>Le classeur</h2><div data-testid="collection-card" style="height:500px">Mes documents · 0 fichiers</div></section><section data-testid="latest-checks"><h2>Dernières vérifications</h2></section>`,
+  "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>`);
+/** 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>`,
+);
+/** What it should be: the card follows its content, the columns fit, a wide table scrolls inside its own scroller. */
+export const FINE = page(
+  `<div style="display:grid;grid-template-columns:minmax(0,1fr) 320px;gap:16px"><section data-testid="binder"><h2>Le classeur</h2><div data-testid="collection-card">Mes documents · 0 fichiers</div></section><aside><section data-testid="activity">Activité</section></aside></div><section data-testid="latest-checks"><h2>Dernières vérifications</h2><div style="overflow:auto;width:300px"><div style="width:900px">table</div></div></section>`,
+);
+/** Not drawn, so not a problem: a chart's text version in a visually hidden wrapper, and the content of a folded `<details>` (the browser still gives both a box). */
+export const HIDDEN_CONTENT = page(
+  `<section data-testid="activity" style="height:120px"><h2>Activité</h2><div style="position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)"><table><tbody>${"<tr><td>21 oct.</td><td>7</td></tr>".repeat(40)}</tbody></table></div></section><section data-testid="report"><details><summary>Détails</summary><div style="height:400px">Texte du rapport</div></details></section>`,
+);
+
+/** The report tab: a section inside a folded details (the closing note) beside sections it must not be taken to cover. */
+export const FOLDED_SECTION = page(
+  `<div style="display:flex;flex-direction:column"><section data-testid="facts" style="height:80px">Faits</section><details><summary>Détails</summary><section data-testid="closing-note" style="padding:16px">Ce que nous avons vérifié</section></details><section data-testid="other" style="height:80px">Autres</section></div>`,
+);
+
+/** 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>`);
+/** 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>`);
+/** 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>`);
+/** 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>`;

package/src/index.d.ts

@@ -0,0 +1,37 @@
+/* Minimal structural types: playwright-core is a peer dependency, not imported here. */
+export type Page = Record<string, unknown>;
+export type BrowserContext = Record<string, unknown>;
+export type Browser = { newContext(o?: object): Promise<BrowserContext>; close(): Promise<void> };
+export const auditPage: string;
+export type Chrome = "public" | "app" | "auth";
+export interface ProblemChecks {
+  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;
+}
+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 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 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>;
+}
+export function auditRoutes(options: AuditRoutesOptions): Promise<string[]>;
+export function selfTest(options?: { launch?: () => Promise<BrowserContext> }): Promise<string[]>;

package/src/index.mjs

@@ -0,0 +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";

package/src/page-audit.mjs

@@ -0,0 +1,404 @@
+// What a rendered page is measured on, in a real browser (Playwright `page.evaluate(auditPage)`), and what counts as a problem.
+// Shared by the responsive guard of the public pages (check-overflow.mjs) and the signed-in pages' check (check-app-pages.mjs).
+
+// The probes below run in the page, so each uses only the browser's globals and the other probes (all of them are serialised together
+// into `auditPage`). They are small on purpose: one measure each, proven on its own fixture (check-page-audit.mjs).
+
+const ARIA_HIDDEN = '[aria-hidden="true"]';
+const className = (el, n) => String(el.className).split(" ").filter(Boolean).slice(0, n).join(".");
+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 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. */
+function clipped(el) {
+  for (let n = el; n && n !== document.body; n = n.parentElement) {
+    if (n.getAttribute("aria-hidden") === "true" || n.hasAttribute("inert")) return true;
+    if (n !== el && ["hidden", "clip", "auto", "scroll"].includes(getComputedStyle(n).overflowX)) return true;
+  }
+  return false;
+}
+
+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);
+    })
+    .slice(0, 3)
+    .map((el) => `${el.tagName.toLowerCase()}.${String(el.className).split(" ").slice(0, 3).join(".")}`);
+}
+
+/** 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);
+}
+
+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, " ")) };
+}
+
+function headerActionOf(doc) {
+  const action = document.querySelector('[data-testid="header-check"]');
+  if (!action) return null;
+  const box = action.getBoundingClientRect();
+  const visible = box.width > 0 && box.height > 0 && box.left >= 0 && box.right <= doc.clientWidth + 1 && box.top >= 0;
+  return { visible, named: !!(action.getAttribute("aria-label") || action.textContent || "").trim() };
+}
+
+/** What a folded `<details>` holds is not drawn, though the browser still gives it a box (its summary is). */
+function folded(el) {
+  return !!el.closest("details:not([open])") && !el.closest("summary");
+}
+
+/** Whether an ancestor between the element and the panel keeps what runs out of it: a scroller, or a visually hidden wrapper (`sr-only`: a 1 px clipped box, the text version of a chart). */
+function keptBetween(el, panel) {
+  for (let n = el.parentElement; n && n !== panel; n = n.parentElement) {
+    if (scrolls(n)) return true;
+    const nb = n.getBoundingClientRect();
+    if ((nb.width <= 2 || nb.height <= 2) && getComputedStyle(n).overflowY !== "visible") return true;
+  }
+  return false;
+}
+
+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);
+}
+
+function runsOut(el, panel, box) {
+  const r = el.getBoundingClientRect();
+  if (notDrawn(el, r) || keptBetween(el, panel)) return false;
+  return r.bottom > box.bottom + 1.5 || r.right > box.right + 1.5;
+}
+
+/** `overflowing`: a panel's content that runs out of the panel (a card taller than its panel, over the next section). `spill` holds those elements. */
+function spillOf(panels) {
+  const overflowing = [];
+  const spill = [];
+  for (const panel of panels) {
+    if (scrolls(panel) || ["hidden", "clip"].includes(getComputedStyle(panel).overflowY)) continue;
+    const box = panel.getBoundingClientRect();
+    const out = [...panel.querySelectorAll("*")].find((el) => runsOut(el, panel, box));
+    if (!out) continue;
+    overflowing.push(`${nameOf(out)} out of ${nameOf(panel)}`);
+    spill.push(out);
+  }
+  return { overflowing, spill };
+}
+
+/** `overlaps`: two sections that are not nested and cover each other, or what ran out of its panel and lands on another section (the card covering « Dernières vérifications »). */
+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)}`);
+  }
+  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)}`);
+  });
+  return overlaps;
+}
+
+/** The clipping ancestor that cuts an element sideways (overflow hidden / clip), or null; a scroller stops the search (it keeps what runs out of it). */
+function cutBy(el, r) {
+  for (let n = el.parentElement; n && n !== document.documentElement; n = n.parentElement) {
+    const style = getComputedStyle(n);
+    if (["auto", "scroll"].includes(style.overflowX)) return null;
+    if (!["hidden", "clip"].includes(style.overflowX)) continue;
+    const c = n.getBoundingClientRect();
+    return r.right > c.right + 2 || r.left < c.left - 2 ? n : null;
+  }
+  return null;
+}
+
+/** `cutColumns`: a section or a column cut by a clipping ancestor, which hides part of its content. */
+function cutColumnsOf() {
+  const cut = [];
+  for (const el of document.querySelectorAll("main section, main aside, main [data-testid], [data-panel]")) {
+    const r = el.getBoundingClientRect();
+    if (el.closest(ARIA_HIDDEN) || r.width === 0 || r.height === 0) continue;
+    const by = cutBy(el, r);
+    if (by) cut.push(`${nameOf(el)} cut by ${nameOf(by)}`);
+  }
+  return [...new Set(cut)].slice(0, 3);
+}
+
+/** The top chrome never overlaps (yomizaka#449): the in-flow blocks above the page (`[data-top-chrome]`, e.g. the development-version notice) and a bar that is fixed or sticky at the top of the viewport. Two of them that share pixels hide one another. */
+function topBoxOf(el) {
+  return el.getBoundingClientRect().height === 0 && el.firstElementChild ? el.firstElementChild : el;
+}
+
+/** A bar is whatever is fixed or sticky across the top of the viewport (a wrapper, whatever its tag): wide, short, near the top. The site's bar stands in a sticky wrapper of zero height, so what it holds is measured. */
+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]");
+}
+
+function chromeOverlapsOf(doc) {
+  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)}`);
+  });
+  return found;
+}
+
+/** « Never overflows »: a control or a card that clips its own content (overflow hidden / clip with more content than room) cuts a word. */
+function clipsOf() {
+  return [...document.querySelectorAll("button, a, [role=button], [data-testid], [class*=badge], [class*=chip]")]
+    .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);
+    })
+    .slice(0, 3)
+    .map(nameOf);
+}
+
+/** A long token (an id, an address) that wraps character by character: a cell taller than two lines for text without a space. */
+function tooTall(el) {
+  const text = (el.textContent || "").trim();
+  if (text.length < 12 || /\s/.test(text) || el.children.length > 1) return false;
+  const cs = getComputedStyle(el);
+  const lh = Number.parseFloat(cs.lineHeight) || Number.parseFloat(cs.fontSize) * 1.4;
+  const content = el.getBoundingClientRect().height - Number.parseFloat(cs.paddingTop) - Number.parseFloat(cs.paddingBottom);
+  return content > lh * 2.5;
+}
+
+function wrappedOf() {
+  return [...document.querySelectorAll("td, th, code, [role=cell]")]
+    .filter(tooTall)
+    .slice(0, 2)
+    .map((el) => (el.textContent || "").trim().slice(0, 24));
+}
+
+/** 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;
+}
+
+/** 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;
+}
+
+/** `<main>` with no text at all: the page answered but drew nothing (a route that fell through, a failed fetch). */
+function emptyMainOf() {
+  return document.querySelector("main")?.innerText.trim().length === 0;
+}
+
+/** 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));
+}
+
+/**
+ * The signed-in frame's own screen (akinaza#444): its shell (`min-height`) and its sticky rail must fit in what is left of the viewport
+ * under the notice, or every page, an empty one included, scrolls by the notice's height. `null` when the page has no `[data-app-frame-slot]`.
+ */
+function frameOf(doc) {
+  const shell = document.querySelector("[data-app-frame-slot] > *");
+  if (!shell) return null;
+  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)),
+    viewport: doc.clientHeight,
+  };
+}
+
+/** 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)
+    .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") };
+}
+
+/** A picture drawn at a real size that never loaded. */
+function brokenPicturesOf() {
+  return [...document.querySelectorAll("img")]
+    .filter((img) => {
+      const box = img.getBoundingClientRect();
+      return box.width > 8 && box.height > 8 && img.complete && img.naturalWidth === 0 && !!img.currentSrc;
+    })
+    .slice(0, 3)
+    .map((img) => img.currentSrc.slice(0, 80));
+}
+
+/** A control of the main that collapsed (under 4 px tall), or a tile that renders nothing (no text, label or image). */
+function emptyControlsOf() {
+  const found = [];
+  for (const el of document.querySelectorAll("main a[href], main button")) {
+    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");
+  }
+  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;
+}
+
+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 { overflowing, spill } = spillOf(panels);
+  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,
+    clientWidth: doc.clientWidth,
+    wide: wideOf(doc),
+    ...unnamedOf(),
+    headerAction: headerActionOf(doc),
+    chips,
+    overflowing: overflowing.slice(0, 3),
+    overlaps: overlapsOf(panels, spill).slice(0, 3),
+    cutColumns: cutColumnsOf(),
+    chromeOverlaps: chromeOverlapsOf(doc).slice(0, 3),
+    clips: clipsOf(),
+    emptyHeadings: emptyHeadingsOf(),
+    unlabelledFiles: unlabelledFilesOf(),
+    wrapped: wrappedOf(),
+    emptyMain: emptyMainOf(),
+    actions: actionsOf(),
+    frame: frameOf(doc),
+    boxes: boxesOf(),
+    landmarks: landmarksOf(),
+    brokenPictures: brokenPicturesOf(),
+    emptyControls: emptyControlsOf(),
+    hardColors: hardColorsOf(),
+    segmentError: !!document.querySelector('[data-testid="segment-error"]'),
+  };
+}
+
+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, 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})()`;
+
+/**
+ * The problems of one page × width × theme, in words: console errors, a horizontal overflow (or elements past the edge),
+ * not exactly one h1 (when asked), unnamed buttons, the header's action off screen or unnamed (when the page has one).
+ */
+/** Empty headings; file inputs without a label (opt-in until `Dropzone` of @krizaka/ui names its hidden input, a prop of the package). */
+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`);
+  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 } = {}) {
+  return [
+    ...statusProblems(where, status),
+    ...(emptyMain && result.emptyMain ? [`${where}: empty <main>`] : []),
+    ...(frame ? frameProblems(where, result.frame) : []),
+    ...(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(", ")}`] : []),
+    ...(emptyControls ? (result.emptyControls ?? []).map((c) => `${where}: ${c}`) : []),
+    ...(hardColors && result.hardColors ? [`${where}: ${result.hardColors} element(s) with a hard-coded colour in an inline style`] : []),
+    ...errorsOf(where, errors),
+    ...layoutProblems(where, result),
+    ...(h1 ? namingProblems(where, result) : []),
+    ...(headerAction ? headerActionProblems(where, result.headerAction) : []),
+    ...chipProblems(where, result.chips ?? []),
+    ...accessibilityProblems(where, result, fileLabels),
+  ];
+}
+
+function errorsOf(where, errors) {
+  return errors.length ? [`${where}: console error — ${errors[0]}`] : [];
+}
+
+/** 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(", ")})`);
+  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"]];
+  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.clips?.length) problems.push(`${where}: content cut inside its box (${result.clips.join(", ")})`);
+  return problems;
+}
+
+/** Exactly one h1 and every button named. */
+function namingProblems(where, result) {
+  const problems = [];
+  if (result.h1 !== 1) problems.push(`${where}: ${result.h1} h1 (expected exactly one)`);
+  if (result.unnamedButtons > 0) {
+    const samples = (result.unnamedSamples ?? []).join(" | ");
+    problems.push(`${where}: ${result.unnamedButtons} unnamed button(s) ${samples}`.trimEnd());
+  }
+  return problems;
+}
+
+function headerActionProblems(where, action) {
+  if (!action) return [`${where}: no header action`];
+  if (!action.visible) return [`${where}: the header's action is off screen`];
+  return action.named ? [] : [`${where}: the header's action has no accessible name`];
+}
+
+function chipProblems(where, chips) {
+  return chips.some((h) => h < 44) ? [`${where}: a chip is ${Math.min(...chips)} px tall (< 44)`] : [];
+}
+
+/** The HTTP status of the page's own load (`undefined`: not asked): a 4xx or 5xx, or no response at all. */
+function statusProblems(where, status) {
+  if (status === undefined) return [];
+  return status === null || status >= 400 ? [`${where}: HTTP ${status ?? "none"}`] : [];
+}
+
+/** 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)`];
+}
+
+/** A button-styled action under `min` px tall is hard to tap. */
+function actionProblems(where, actions, min) {
+  return actions.some((h) => h < min) ? [`${where}: an action is ${Math.min(...actions)} px tall (< ${min})`] : [];
+}
+
+function boxProblems(where, boxes) {
+  return boxes.map((b) => `${where}: never overflows — ${b} content wider than its box`);
+}
+
+/** `kind`: "public" (one page footer that names Krizaka, a nav), "app" (at most one footer, a nav), "auth" (at most one footer, no nav asked). */
+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)`);
+    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`);
+  return problems;
+}

package/src/run.mjs

@@ -0,0 +1,198 @@
+// The audit over a route list: every route × viewport width × theme, in a real browser, the problems in words.
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { auditPage, problemsOf } from "./page-audit.mjs";
+import { auditContext, loadSettled, resizeSettled } from "./settle.mjs";
+
+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()));
+
+async function chromiumOf(launch) {
+  if (launch) return launch();
+  const { chromium } = await import("playwright-core");
+  return chromium.launch();
+}
+
+/** Persists the theme the way the apps do, before any page script runs. */
+function rememberTheme([key, value]) {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+    // storage blocked: the colour scheme is still emulated
+  }
+}
+
+/** The page's console errors and uncaught exceptions, read and cleared by `take()`. */
+function collectErrors(page, ignore) {
+  let errors = [];
+  page.on("console", (m) => {
+    if (isPageError(m, ignore)) errors.push(m.text().slice(0, 140));
+  });
+  page.on("pageerror", (e) => errors.push(String(e).slice(0, 140)));
+  return {
+    take() {
+      const seen = errors;
+      errors = [];
+      return seen;
+    },
+  };
+}
+
+const viewportOf = (w, height) => (typeof w === "number" ? { width: w, height } : { height, ...w });
+const specOf = (r) => (typeof r === "string" ? { url: r } : { ...r, url: r.url ?? r.route });
+const nameOfRoute = (r) => r.name ?? r.url;
+
+/**
+ * A route source that is a crawl: the paths of the site's own sitemap (a page added there is audited), the `first` ones always first,
+ * at most `limit`. Returns `null` when nothing answers at `${base}/sitemap.xml` (the caller says so and stops).
+ * @param {string} base
+ * @param {{ first?: string[], limit?: number, fetcher?: typeof fetch }} [o]
+ * @returns {Promise<string[] | null>}
+ */
+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);
+  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);
+}
+
+/** The optional axe step: `@krizaka/a11y-audit` (a peer, loaded only when asked), one collector per kind of page, each ratcheted by the repo's own baseline file. */
+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`)) };
+}
+
+/** The ratchet's verdict, per kind. A baseline not recorded yet (`optional`) is counted, not enforced, until `--a11y-init`. */
+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`);
+      continue;
+    }
+    const guard = state.lib.finish(collector, { baseline });
+    for (const note of guard.notes) state.log(note);
+    problems.push(...guard.problems);
+  }
+  return problems;
+}
+
+/** The HTTP status of the load when asked for (`null`: no response), else `undefined`. */
+function statusOf(response, checks) {
+  if (!checks.status) return undefined;
+  return response ? response.status() : null;
+}
+
+/** 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 }) {
+  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}`);
+  if (prepare) await prepare(page, spec.url);
+  if (settleMs) await page.waitForTimeout(settleMs);
+  const result = await page.evaluate(auditPage);
+  if (a11y?.widths.includes(viewport.width)) {
+    const { collector } = a11y.kinds[kind] ?? a11y.kinds.public;
+    collector.add({ route: spec.url, theme }, await a11y.lib.auditPage(page));
+  }
+  if (shots) {
+    mkdirSync(shots, { recursive: true });
+    await page.screenshot({ path: join(shots, `${where.replace(/[/?=&@ ]/g, "_")}.png`) });
+  }
+  const status = statusOf(response, checks);
+  const landmarks = spec.chrome ?? checks.landmarks;
+  return problemsOf(where, result, { ...checks, landmarks, status, errors: errors.take() });
+}
+
+/** One route at one width, with `attempts` tries before it counts as « could not be audited ». */
+async function measureWithRetries(page, o, spec, viewport, where) {
+  let failure;
+  for (let attempt = 1; attempt <= o.attempts; attempt++) {
+    try {
+      return await measure(page, { ...o, spec, viewport, where });
+    } catch (error) {
+      failure = error;
+    }
+  }
+  return [`${where}: could not be audited — ${String(failure?.message).split("\n")[0]}`];
+}
+
+/** Audits the routes of one page (one context), each width. */
+async function auditPageRoutes(page, routes, o) {
+  const problems = [];
+  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}`)));
+    }
+  }
+  return problems;
+}
+
+async function newPage(browser, o, extra = {}) {
+  const context = await auditContext(browser, { colorScheme: o.theme, ...extra });
+  if (o.themeKey) await context.addInitScript(rememberTheme, [o.themeKey, o.theme]);
+  const page = await context.newPage();
+  return { context, page, errors: collectErrors(page, o.ignoreConsole) };
+}
+
+/** 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 } : {});
+  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 }) : [];
+    return await auditPageRoutes(page, [...own, ...flagged].map(specOf), { ...o, errors, kind: "session" });
+  } finally {
+    await context.close();
+  }
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.base  origin of the running app
+ * @param {Array<string | { url: string, name?: string, chrome?: "public" | "app" | "auth", session?: boolean }>} o.routes  paths to audit (a route flagged `session` is audited signed in; `chrome` replaces `checks.landmarks` for that route)
+ * @param {Array<number | { width: number, height?: number }>} [o.widths]  viewports (default widths 360 to 1440)
+ * @param {string[]} [o.themes]  "dark" | "light" (default both): emulated colour scheme and, when `themeKey` is set, localStorage
+ * @param {number} [o.height]  viewport height (default 900)
+ * @param {string} [o.themeKey]  localStorage key the app persists its theme in (default "kz-theme")
+ * @param {string} [o.shots]  directory for one screenshot per route × width × theme
+ * @param {number} [o.settleMs]  pause after load, for late layout (default 300)
+ * @param {object} [o.checks]  options of `problemsOf`: h1, headerAction, fileLabels, and the opt-in status, emptyMain, frame, minAction, boxes, landmarks, pictures, emptyControls, hardColors
+ * @param {RegExp[]} [o.ignoreConsole]  console errors the app tolerates (default: « Failed to load resource »; `[]` counts every error)
+ * @param {number} [o.attempts]  tries per route before it counts as not audited (default 1)
+ * @param {{ app: string, baseline: string, widths?: number[], log?: (line: string) => void, session?: { app: string, baseline: string } }} [o.a11y]  the axe step (`@krizaka/a11y-audit`, a peer) and the repo's ratchet file
+ * @param {{ storageState?: object | string, signIn?: Function, routes?: Function }} [o.session]  how the signed-in pages are reached
+ * @param {(page: object, route: string) => Promise<void>} [o.prepare]  before each route is measured (sign in, seed)
+ * @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 }) {
+  const browser = await chromiumOf(launch);
+  const state = await a11yOf(a11y);
+  const specs = routes.map(specOf);
+  const plain = specs.filter((r) => !r.session);
+  const flagged = specs.filter((r) => r.session);
+  const problems = [];
+  try {
+    for (const theme of themes) {
+      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)));
+    }
+  } finally {
+    await browser.close();
+  }
+  if (state) problems.push(...a11yProblems(state));
+  return problems;
+}

package/src/self-test.mjs

@@ -0,0 +1,62 @@
+// 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, SECTIONS_OVERLAP, SMALL_ACTION } from "./fixtures.mjs";
+import { auditPage, problemsOf } from "./page-audit.mjs";
+import { auditContext } from "./settle.mjs";
+
+const EXPECT = [
+  ["a card taller than its panel", CARD_OVER_NEXT, /overflows its panel/],
+  ["a card over the next section", CARD_OVER_NEXT, /covers a neighbouring section/],
+  ["two sections on top of each other", SECTIONS_OVERLAP, /covers a neighbouring section/],
+  ["a column cut by a clipping wrapper", COLUMN_CUT, /is cut off/],
+  ["an empty <main>", EMPTY_MAIN, /empty <main>/, { emptyMain: true }],
+  ["a frame that forces a scroll", FRAME_FORCES_SCROLL, /the frame forces a scroll/, { frame: true }],
+  ["an action under the tap target", SMALL_ACTION, /an action is 24 px tall \(< 36\)/, { minAction: 36 }],
+  ["a landmark wider than its box", BOX_TOO_WIDE, /content wider than its box/, { boxes: true }],
+  ["a broken picture", BROKEN_PARTS, /broken picture/, { pictures: true }],
+  ["a tile that draws nothing", BROKEN_PARTS, /empty tile/, { emptyControls: true }],
+  ["a hard-coded inline colour", BROKEN_PARTS, /hard-coded colour/, { hardColors: true }],
+  ["two page footers and no nav", CHROME_BAD, /2 page footers/, { landmarks: "public" }],
+  ["no nav landmark", CHROME_BAD, /no <nav> landmark/, { landmarks: "app" }],
+];
+const FINES = [
+  ["a fine layout", FINE],
+  ["content that is not drawn (a visually hidden table, a folded details)", HIDDEN_CONTENT],
+  ["a section folded in a details", FOLDED_SECTION],
+];
+/** 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" };
+const FINES_STRICT = [
+  ["a frame that fits its screen", FRAME_FITS, { frame: true, emptyMain: false }],
+  ["the family chrome", CHROME_FINE, ALL],
+];
+
+async function problemsOn(page, html, checks) {
+  await page.setContent(html);
+  return problemsOf("fixture", await page.evaluate(auditPage), checks);
+}
+
+/** The failure for a fixture that must be clean and is not (none, when it is). */
+async function reported(page, name, html, checks) {
+  const fine = await problemsOn(page, html, checks);
+  return fine.length ? [`the audit reports ${String(name)}: ${fine.join(" | ")}`] : [];
+}
+
+/** @returns {Promise<string[]>} the failures (empty when the audit sees what it must and nothing else) */
+export async function selfTest({ launch } = {}) {
+  const browser = launch ? await launch() : await (await import("playwright-core")).chromium.launch();
+  const failures = [];
+  try {
+    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"}`);
+    }
+    for (const [name, html] of FINES) failures.push(...(await reported(page, name, html)));
+    await page.setViewportSize({ width: 1280, height: 700 });
+    for (const [name, html, checks] of FINES_STRICT) failures.push(...(await reported(page, name, html, checks)));
+  } finally {
+    await browser.close();
+  }
+  return failures;
+}

package/src/settle.mjs

@@ -0,0 +1,54 @@
+// One way for every browser audit to measure (yomizaka#354): never while a View Transition is swapping the page.
+//
+// The flake: the page was read while a transition was running (« Viewport size changed », 0 of 2 h1). The cure is the
+// same everywhere, so it lives here and nowhere else: the context emulates reduced motion (the app honours it, the page
+// change is instant — motion.css of @krizaka/ui) and every load or resize waits, explicitly, until no transition is
+// active. No retry, no sleep standing in for a condition. `tests/browser-audits.test.mjs` fails a script that
+// opens a context, loads a page or resizes without these.
+
+/** The options of an audit's browser context: the caller's, plus reduced motion. */
+export const auditOptions = (options = {}) => ({ ...options, reducedMotion: "reduce" });
+
+/**
+ * Runs before any page script: the browser offers no View Transition, so PageTransition (@krizaka/ui) changes the page
+ * at once. Reduced motion alone is not enough: the transition still starts, and a resize or a load under it, or a slow
+ * runner, makes the browser log « Transition was aborted » / « DOM update timed out » as a console error that has
+ * nothing to do with the page (main and two PRs, 2026-10-27). An audit measures layout, not motion.
+ */
+export const withoutViewTransitions = () => {
+  Object.defineProperty(Document.prototype, "startViewTransition", { value: undefined, configurable: true });
+};
+
+/** A browser context for an audit (reduced motion emulated, no View Transition). */
+export async function auditContext(browser, options) {
+  const context = await browser.newContext(auditOptions(options));
+  await context.addInitScript(withoutViewTransitions);
+  return context;
+}
+
+/** 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 });
+
+/**
+ * Loads a page, then waits for the faces and for the transitions: what is read afterwards is final. Returns the response.
+ * It first lets the page we are leaving finish any transition it started after the last measure (a router refresh, a
+ * poll): leaving one running aborts it, and the browser reports « Transition was aborted » as a console error (#354).
+ */
+export async function loadSettled(page, url, options = { waitUntil: "load" }) {
+  if (page.url() !== "about:blank") await settled(page);
+  const response = await page.goto(url, options);
+  await page.evaluate(() => document.fonts.ready);
+  await settled(page);
+  return response;
+}
+
+/**
+ * Resizes the viewport, then waits for the transitions a resize can start. A transition already running is let finish
+ * first: a resize under it aborts it (« Viewport size changed », a console error), which is how this audit once failed.
+ */
+export async function resizeSettled(page, size) {
+  await settled(page);
+  await page.setViewportSize(size);
+  await settled(page);
+}