@krizaka/page-audit 0.0.0-stage → 0.2.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,20 @@
-# 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.

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@krizaka/page-audit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "The page audit of every Krizaka app, in one place: 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": {
+    "playwright-core": ">=1.40"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "eslint": "^9.39.0",
+    "playwright-core": "^1.55.0",
+    "vitest": "^4.1.11",
+    "@krizaka/config": "^0.13.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,30 @@
+#!/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]     |     krizaka-page-audit --self-test
+import { auditRoutes, 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: 4 broken layouts seen, the fine ones clean");
+} else {
+  const routes = list(arg("routes"), ["/"]);
+  const widths = list(arg("widths"), WIDTHS).map(Number);
+  const themes = list(arg("themes"), THEMES);
+  const problems = await auditRoutes({ base: arg("base", "http://localhost:3000"), routes, widths, themes, themeKey: arg("theme-key", "kz-theme"), shots: arg("shots"), checks: { h1: process.argv.includes("--h1") } });
+  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,29 @@
+// 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>`,
+);

package/src/index.d.ts

@@ -0,0 +1,22 @@
+/* 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 interface ProblemChecks { errors?: string[]; h1?: boolean; headerAction?: boolean; fileLabels?: 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 }): boolean;
+export interface AuditRoutesOptions {
+  base: string; routes: string[]; widths?: number[]; themes?: string[]; height?: number; themeKey?: string; shots?: string; settleMs?: number;
+  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, 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,287 @@
+// 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") 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 && (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;
+}
+
+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(),
+    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, 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 } = {}) {
+  return [
+    ...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)`] : [];
+}

package/src/run.mjs

@@ -0,0 +1,96 @@
+// The audit over a route list: every route × viewport width × theme, in a real browser, the problems in words.
+import { 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. */
+export const isPageError = (message) => message.type() === "error" && !/Failed to load resource/.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) {
+  let errors = [];
+  page.on("console", (m) => {
+    if (isPageError(m)) 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;
+    },
+  };
+}
+
+/** One route at one width: load, settle, measure, screenshot. */
+async function measure(page, { base, route, width, height, settleMs, prepare, checks, errors, where, shots }) {
+  await resizeSettled(page, { width, height });
+  // « load » and the faces, not « networkidle »: router prefetches can keep the page from ever going idle.
+  await loadSettled(page, `${base}${route}`);
+  if (prepare) await prepare(page, route);
+  if (settleMs) await page.waitForTimeout(settleMs);
+  const result = await page.evaluate(auditPage);
+  if (shots) {
+    mkdirSync(shots, { recursive: true });
+    await page.screenshot({ path: join(shots, `${where.replace(/[/?=&@ ]/g, "_")}.png`) });
+  }
+  return problemsOf(where, result, { ...checks, errors: errors.take() });
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.base  origin of the running app
+ * @param {string[]} o.routes  paths to audit
+ * @param {number[]} [o.widths]  viewport widths (default 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)
+ * @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 = {}, prepare, launch }) {
+  const browser = await chromiumOf(launch);
+  const problems = [];
+  try {
+    for (const theme of themes) {
+      const context = await auditContext(browser, { colorScheme: theme });
+      if (themeKey) await context.addInitScript(rememberTheme, [themeKey, theme]);
+      const page = await context.newPage();
+      const errors = collectErrors(page);
+      for (const route of routes) {
+        for (const width of widths) {
+          const where = `${route} @${width} ${theme}`;
+          problems.push(...(await measure(page, { base, route, width, height, settleMs, prepare, checks, errors, where, shots })));
+        }
+      }
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+  return problems;
+}

package/src/self-test.mjs

@@ -0,0 +1,39 @@
+// 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 { CARD_OVER_NEXT, COLUMN_CUT, FINE, FOLDED_SECTION, HIDDEN_CONTENT, SECTIONS_OVERLAP } 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/],
+];
+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],
+];
+
+/** @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] of EXPECT) {
+      await page.setContent(html);
+      const problems = problemsOf("fixture", await page.evaluate(auditPage));
+      if (!problems.some((p) => pattern.test(p))) failures.push(`the audit does not see ${name}: ${problems.join(" | ") || "no problem reported"}`);
+    }
+    for (const [name, html] of FINES) {
+      await page.setContent(html);
+      const fine = problemsOf("fixture", await page.evaluate(auditPage));
+      if (fine.length) failures.push(`the audit reports ${name}: ${fine.join(" | ")}`);
+    }
+  } 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);
+}