debutly 0.0.0-stage → 0.2.0

package/src/detect/wcag.ts

@@ -0,0 +1,38 @@
+// WCAG 2.2 success criteria a finding relates to. They point a person at what to check; Debutly
+// doesn't test conformance, and a run without them says nothing about it.
+
+export interface Criterion {
+  id: string;
+  name: string;
+  level: "A" | "AA";
+  /** The criterion's page in W3C's "Understanding WCAG 2.2". */
+  url: string;
+}
+
+const understanding = (slug: string) => `https://www.w3.org/WAI/WCAG22/Understanding/${slug}`;
+
+export const CRITERIA: Record<string, Criterion> = {
+  "1.3.1": { id: "1.3.1", name: "Info and Relationships", level: "A", url: understanding("info-and-relationships") },
+  "1.4.4": { id: "1.4.4", name: "Resize Text", level: "AA", url: understanding("resize-text") },
+  "1.4.10": { id: "1.4.10", name: "Reflow", level: "AA", url: understanding("reflow") },
+  "2.1.1": { id: "2.1.1", name: "Keyboard", level: "A", url: understanding("keyboard") },
+  "2.4.4": { id: "2.4.4", name: "Link Purpose (In Context)", level: "A", url: understanding("link-purpose-in-context") },
+  "2.4.11": { id: "2.4.11", name: "Focus Not Obscured (Minimum)", level: "AA", url: understanding("focus-not-obscured-minimum") },
+  "3.1.1": { id: "3.1.1", name: "Language of Page", level: "A", url: understanding("language-of-page") },
+  "3.3.2": { id: "3.3.2", name: "Labels or Instructions", level: "A", url: understanding("labels-or-instructions") },
+  "4.1.2": { id: "4.1.2", name: "Name, Role, Value", level: "A", url: understanding("name-role-value") },
+};
+
+/** The criteria an unnamed control relates to, by what kind of control it is. */
+export function unlabeledCriteria(control: string): string[] {
+  if (control === "link") return ["2.4.4", "4.1.2"];
+  if (control === "button") return ["4.1.2"];
+  // Fields: a dropdown, text box, checkbox, radio button…
+  return ["1.3.1", "3.3.2", "4.1.2"];
+}
+
+/** "4.1.2 Name, Role, Value (A)", linked for Markdown. */
+export const describeCriterion = (id: string) => {
+  const c = CRITERIA[id];
+  return c ? `[${c.id} ${c.name}](${c.url}) (${c.level})` : id;
+};

package/src/doctor.ts

@@ -0,0 +1,145 @@
+// `debutly doctor`: is everything in place for a run? Each check says what to do when it fails.
+import { CONFIG_FILE, readConfig, type DebutlyConfig } from "./config";
+import { keyCreditsLeft } from "./llm/credits";
+import { isOpenRouter } from "./llm/openrouter";
+
+export type CheckStatus = "ok" | "warn" | "fail";
+export interface Check {
+  status: CheckStatus;
+  label: string;
+  detail?: string;
+}
+
+export interface DoctorDeps {
+  env: NodeJS.ProcessEnv;
+  nodeVersion: string;
+  fetchFn: typeof fetch;
+  chromiumInstalled: () => boolean;
+  readConfig: () => DebutlyConfig | undefined;
+}
+
+const MIN_NODE = [20, 12];
+const TIMEOUT_MS = 10_000;
+
+const atLeast = (version: string, [major, minor]: number[]) => {
+  const [a, b] = version.split(".").map(Number);
+  return a > major || (a === major && b >= minor);
+};
+
+// Addresses that are plainly a copy on this machine or a network-local test host.
+const LOCAL_HOST = /^(localhost|127\.\d+\.\d+\.\d+|\[::1\]|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|.+\.(localhost|local|test|internal))$/i;
+// A label that marks a hosted test copy: staging.example.com, my-app-git-branch.preview.example.com.
+const TEST_LABEL = /(^|[.-])(staging|stage|preview|dev|test|qa|sandbox|uat)([.-]|\d|$)/i;
+
+/** Could this address be the real, production app? Agents sign up, submit forms and pay. */
+export function looksLikeProduction(url: string): boolean {
+  try {
+    const host = new URL(url).hostname;
+    return !LOCAL_HOST.test(host) && !TEST_LABEL.test(host);
+  } catch {
+    return false;
+  }
+}
+
+async function keyWorks(env: NodeJS.ProcessEnv, fetchFn: typeof fetch): Promise<Check> {
+  const key = env.DEBUTLY_API_KEY ?? "";
+  const provider = env.DEBUTLY_PROVIDER ?? "anthropic";
+  const signal = AbortSignal.timeout(TIMEOUT_MS);
+  try {
+    const res =
+      provider === "anthropic"
+        ? await fetchFn("https://api.anthropic.com/v1/models", { headers: { "x-api-key": key, "anthropic-version": "2023-06-01" }, signal })
+        : await fetchFn(`${(env.DEBUTLY_BASE_URL ?? "").replace(/\/+$/, "")}/${isOpenRouter(env.DEBUTLY_BASE_URL) ? "key" : "models"}`, {
+            headers: { authorization: `Bearer ${key}` },
+            signal,
+          });
+    if (res.status === 401 || res.status === 403) return { status: "fail", label: "The provider rejects the API key", detail: "Check it was copied in full, or create a new one." };
+    if (!res.ok) return { status: "warn", label: `The provider answered HTTP ${res.status} when asked about the key` };
+  } catch (err) {
+    return { status: "warn", label: "Couldn't reach the model provider", detail: err instanceof Error ? err.message : String(err) };
+  }
+  const left = await keyCreditsLeft(env.DEBUTLY_BASE_URL ?? "", key, fetchFn);
+  return { status: "ok", label: "The provider accepts the API key", detail: left === null ? undefined : `$${left.toFixed(2)} left on the key's limit; the account's own balance isn't visible here` };
+}
+
+async function appAnswers(url: string, fetchFn: typeof fetch): Promise<Check> {
+  try {
+    const res = await fetchFn(url, { redirect: "follow", signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (res.status >= 500) return { status: "warn", label: `${url} answers HTTP ${res.status}`, detail: "Agents will start on an error page." };
+    return { status: "ok", label: `${url} answers (HTTP ${res.status})` };
+  } catch {
+    return { status: "fail", label: `Nothing answers at ${url}`, detail: "Start your app first (a test copy, never production), then check again." };
+  }
+}
+
+export async function runChecks(d: DoctorDeps): Promise<Check[]> {
+  const checks: Check[] = [];
+  checks.push(
+    atLeast(d.nodeVersion, MIN_NODE)
+      ? { status: "ok", label: `Node.js ${d.nodeVersion}` }
+      : { status: "fail", label: `Node.js ${d.nodeVersion} is too old`, detail: `Debutly needs ${MIN_NODE.join(".")} or later: https://nodejs.org` },
+  );
+
+  if (!d.env.DEBUTLY_API_KEY) {
+    checks.push({
+      status: "fail",
+      label: "No model API key",
+      detail: "Create one at https://openrouter.ai/keys and add DEBUTLY_API_KEY=… to a .env file here (keep .env out of git), or set OPENROUTER_API_KEY.",
+    });
+  } else {
+    const via = d.env.DEBUTLY_PROVIDER === "anthropic" ? "Anthropic" : (d.env.DEBUTLY_BASE_URL ?? "an OpenAI-compatible provider");
+    checks.push({ status: "ok", label: `API key found (${via}; agents use ${d.env.DEBUTLY_NAV_MODEL ?? "the default model"})` });
+    checks.push(await keyWorks(d.env, d.fetchFn));
+  }
+
+  checks.push(
+    d.chromiumInstalled()
+      ? { status: "ok", label: "Chromium is installed" }
+      : { status: "warn", label: "Chromium isn't downloaded yet", detail: "The first run downloads it (about 150 MB), or run: npx playwright install chromium" },
+  );
+
+  let config: DebutlyConfig | undefined;
+  try {
+    config = d.readConfig();
+  } catch (err) {
+    checks.push({ status: "fail", label: err instanceof Error ? err.message : String(err) });
+    return checks;
+  }
+  if (!config) {
+    checks.push({ status: "warn", label: `No ${CONFIG_FILE} here`, detail: "Run npx debutly init to create one, or pass --url, --goal and --icp to each run." });
+    return checks;
+  }
+  const missing = (["url", "goal", "icp"] as const).filter((k) => !config[k]);
+  checks.push(
+    missing.length
+      ? { status: "fail", label: `${CONFIG_FILE} has no ${missing.join(", ")}`, detail: "Every run needs the app's address, a goal and who the customers are." }
+      : { status: "ok", label: `${CONFIG_FILE}: "${config.goal}"` },
+  );
+  if (typeof config.url === "string") {
+    if (looksLikeProduction(config.url)) {
+      checks.push({
+        status: "warn",
+        label: `${config.url} may be your real app`,
+        detail: "Agents create accounts, submit forms and pay in test mode. Point Debutly at a local, staging or throwaway copy.",
+      });
+    }
+    checks.push(await appAnswers(config.url, d.fetchFn));
+  }
+  return checks;
+}
+
+const MARK: Record<CheckStatus, string> = { ok: "✓", warn: "!", fail: "✗" };
+
+export function renderChecks(checks: Check[]): string {
+  const lines = checks.map((c) => `${MARK[c.status]} ${c.label}${c.detail ? `\n    ${c.detail}` : ""}`);
+  const failed = checks.filter((c) => c.status === "fail").length;
+  lines.push("", failed ? `${failed} thing${failed === 1 ? "" : "s"} to fix before a run.` : "Ready. Start a run with: npx debutly");
+  return lines.join("\n");
+}
+
+export async function doctor(): Promise<number> {
+  const { chromiumInstalled } = await import("./util/chromium");
+  const checks = await runChecks({ env: process.env, nodeVersion: process.versions.node, fetchFn: fetch, chromiumInstalled, readConfig: () => readConfig() });
+  console.log(renderChecks(checks));
+  return checks.some((c) => c.status === "fail") ? 1 : 0;
+}

package/src/hear-cli.ts

@@ -0,0 +1,137 @@
+// `debutly hear [report dir] [--browser-state dir] [--tabs 120]`: a run's screen-reader findings,
+// checked with a real screen reader through Guidepup: NVDA on Windows, VoiceOver on macOS. The
+// app must be running where the report's pages point; for pages behind sign-in, run the agents
+// with --browser-state <dir> first.
+import { execFileSync } from "node:child_process";
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { chromium, type Page } from "playwright";
+import { hearFindings, nextUtterance, type ScreenReader } from "./hear";
+
+const USAGE =
+  "Usage: npx debutly hear [report dir] [--browser-state <dir>] [--tabs 120]\nNeeds Windows (NVDA) or macOS (VoiceOver), set up for automation: npm i -D @guidepup/guidepup && npx @guidepup/setup";
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: { "browser-state": { type: "string" }, tabs: { type: "string", default: "120" } },
+});
+
+/** The newest run under .debutly/runs, where `debutly run` writes reports by default. */
+function latestRun(): string | undefined {
+  try {
+    const root = join(".debutly", "runs");
+    return readdirSync(root)
+      .map((d) => join(root, d))
+      .filter((d) => statSync(d).isDirectory())
+      .sort()
+      .at(-1);
+  } catch {
+    return undefined;
+  }
+}
+
+const clean = (s: string) => s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** The Chrome Playwright launches, as macOS knows it. */
+const CHROME_FOR_TESTING = "com.google.chrome.for.testing";
+
+async function loadGuidepup(): Promise<typeof import("@guidepup/guidepup")> {
+  try {
+    return await import("@guidepup/guidepup");
+  } catch {
+    throw new Error(`Guidepup isn't installed.\n${USAGE}`);
+  }
+}
+
+/**
+ * NVDA, through Guidepup. Putting it on the page follows Guidepup's own Playwright helper (MIT):
+ * make sure the browser window is the one in front, then go to the top of the document. It
+ * doesn't click the page to focus it, as that helper does: a click lands on whatever is there.
+ */
+async function nvdaReader(): Promise<ScreenReader> {
+  const { nvda, NVDAKeyCodeCommands, WindowsKeyCodes, WindowsModifiers } = await loadGuidepup();
+  // Guidepup's NVDA build is versioned like "0.2.1-2026.2": the NVDA release is the last part.
+  const version = (nvda as unknown as { version?: string }).version?.match(/(\d{4}\.\d+(?:\.\d+)?)$/)?.[1];
+  return {
+    name: version ? `NVDA ${version}` : "NVDA",
+    start: () => nvda.start({ capture: "initial" }),
+    stop: () => nvda.stop(),
+    async focus(page: Page) {
+      await nvda.perform(NVDAKeyCodeCommands.exitFocusMode, { capture: false });
+      const title = clean(await page.title());
+      for (let attempt = 0; attempt < 10; attempt++) {
+        await nvda.perform(NVDAKeyCodeCommands.reportTitle);
+        const window = clean(await nvda.lastSpokenPhrase());
+        if ((title && window.startsWith(title)) || window.includes("chrome")) break;
+        await nvda.perform({ keyCode: [WindowsKeyCodes.Escape], modifiers: [WindowsModifiers.Alt] }, { capture: false });
+        await delay(500);
+      }
+      await page.bringToFront();
+      await nvda.perform({ keyCode: [WindowsKeyCodes.Home], modifiers: [WindowsModifiers.Control] }, { capture: false });
+      await nvda.clearSpokenPhraseLog();
+    },
+    press: (key) => nvda.press(key),
+    said: () => nextUtterance(nvda),
+  };
+}
+
+/**
+ * VoiceOver, through Guidepup. It follows keyboard focus, so Tab needs only Chrome in front
+ * (Guidepup's helper for reading a page with VoiceOver's own cursor goes further, through its
+ * item chooser; Tab doesn't need that). Pressing Control first stops anything still being read.
+ */
+async function voiceOverReader(): Promise<ScreenReader> {
+  const { voiceOver, macOSActivateId, MacOSKeyCodes } = await loadGuidepup();
+  let macOS = "";
+  try {
+    macOS = execFileSync("sw_vers", ["-productVersion"], { encoding: "utf8" }).trim();
+  } catch {
+    // not worth failing over
+  }
+  return {
+    name: macOS ? `VoiceOver (macOS ${macOS})` : "VoiceOver",
+    start: () => voiceOver.start({ capture: "initial" }),
+    stop: () => voiceOver.stop(),
+    async focus(page: Page) {
+      await macOSActivateId(CHROME_FOR_TESTING);
+      await voiceOver.perform({ keyCode: MacOSKeyCodes.Control }, { capture: false });
+      await page.bringToFront();
+      // Bringing Chrome forward has VoiceOver read the window and toolbar: let it finish first.
+      await nextUtterance(voiceOver, { startWithinMs: 1500, pauseMs: 800 });
+      await voiceOver.clearSpokenPhraseLog();
+    },
+    press: (key) => voiceOver.press(key),
+    said: () => nextUtterance(voiceOver),
+  };
+}
+
+async function screenReader(): Promise<ScreenReader> {
+  if (process.platform === "win32") return nvdaReader();
+  if (process.platform === "darwin") return voiceOverReader();
+  throw new Error(`debutly hear uses NVDA on Windows or VoiceOver on macOS.\n${USAGE}`);
+}
+
+const reportDir = positionals[0] ?? latestRun();
+if (!reportDir) {
+  console.error(`No report given, and none under .debutly/runs.\n${USAGE}`);
+  process.exit(1);
+}
+try {
+  const reader = await screenReader();
+  console.log(`Hearing ${reportDir} with ${reader.name}...`);
+  const heard = await hearFindings({
+    reportDir,
+    reader,
+    browserStateDir: values["browser-state"],
+    tabs: Number(values.tabs),
+    launch: () => chromium.launch({ headless: false }),
+  });
+  if (!heard.length) console.log("No screen-reader findings to hear in this report.");
+  for (const h of heard) console.log(`${h.verdict.padEnd(15)} ${h.title}: ${h.note}`);
+  console.log(`Added to ${join(reportDir, "report.md")} and ${join(reportDir, "heard.json")}.`);
+} catch (err) {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+}

package/src/hear.ts

@@ -0,0 +1,309 @@
+import { existsSync } from "node:fs";
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Browser, BrowserContext, Page } from "playwright";
+import { accessibleNames } from "./browser/ax";
+import { SCAN_SCRIPT } from "./browser/scan-script";
+import { nameProblem } from "./detect/findings";
+import type { Finding, InteractiveElement, Session } from "./types";
+
+// `debutly hear`: a run's screen-reader findings, checked with a real screen reader. Each page a
+// finding is about is opened again (signed in, with the agent's kept browser state), the screen
+// reader is put on it, and Tab is pressed through it. Debutly knows which control has focus at
+// each press, so it can say what the screen reader said for the very control a finding is about.
+// Checked by hand against NVDA on three open-source apps first, where about a third of
+// unnamed-control findings didn't hold up: this is how a report can tell those apart.
+
+/** What Debutly needs from a screen reader: NVDA through Guidepup, or a stand-in in tests. */
+export interface ScreenReader {
+  /** e.g. "NVDA 2026.2" */
+  name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  /** Puts the screen reader on the page, ready for Tab. */
+  focus(page: Page): Promise<void>;
+  press(key: string): Promise<void>;
+  /** What it has said since the last call. */
+  said(): Promise<string>;
+}
+
+export type Verdict = "confirmed" | "not confirmed" | "check by ear" | "not on the page";
+
+export interface Heard {
+  title: string;
+  page: string;
+  verdict: Verdict;
+  /** What the screen reader said on reaching each such control; empty when Tab never reached one. */
+  said: string[];
+  note: string;
+}
+
+export interface HearOptions {
+  reportDir: string;
+  reader: ScreenReader;
+  /** Where `debutly run --browser-state` kept each agent's browser, to open pages behind sign-in. */
+  browserStateDir?: string;
+  /** Tab presses per page at most; the walk stops sooner, once focus has come round twice. */
+  tabs?: number;
+  /** Opens the browser. A real screen reader needs a visible one in front. */
+  launch: () => Promise<Browser>;
+}
+
+const ACTIVE_ID = `(() => { const el = document.activeElement; return el ? el.getAttribute('data-debutly-id') : null; })()`;
+const BLUR = `(() => { if (document.activeElement && document.activeElement.blur) document.activeElement.blur(); })()`;
+const SETTLE_MS = 2500;
+
+// The words a screen reader adds about a control's role and state, NVDA's and VoiceOver's. What's
+// left once they're gone is its name: nothing left means the control was announced without one.
+// Longest first, so "edit text" goes as a whole before "edit" would.
+const ROLE_AND_STATE_WORDS = [
+  // NVDA
+  "button", "toggle button", "menu button", "link", "visited", "same page", "current page", "combo box", "edit",
+  "multi line", "blank", "read only", "protected", "collapsed", "expanded", "has auto complete", "editable",
+  "check box", "not checked", "half checked", "checked", "switch", "on", "off", "radio button", "sub ?menu",
+  "opens dialog", "opens list", "selected", "clickable", "unavailable", "required", "invalid entry", "pressed",
+  "not pressed", "section", "grouping", "region", "landmark", "navigation", "main", "form", "list",
+  "with \\d+ items", "out of list", "graphic", "heading", "level \\d+", "\\d+ of \\d+",
+  // VoiceOver
+  "text field", "secure text field", "text area", "pop[- ]?up button", "dimmed", "edit text", "secure edit text",
+  "unchecked", "group", "web content", "has keyboard focus", "image", "invalid data", "you are currently on an?",
+];
+const ROLE_AND_STATE = new RegExp(`\\b(${[...ROLE_AND_STATE_WORDS].sort((a, b) => b.length - a.length).join("|")})\\b`, "gi");
+
+/** True when a role was said with nothing but state words around it: silence isn't "no name". */
+export function saidNoName(said: string): boolean {
+  return /[\p{L}\p{N}]/u.test(said) && said.replace(ROLE_AND_STATE, " ").replace(/[^\p{L}\p{N}]+/gu, "") === "";
+}
+
+export interface SpeechLog {
+  spokenPhraseLog(): Promise<string[]>;
+  clearSpokenPhraseLog(): Promise<void>;
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * What a screen reader says after a key press: it waits for speech to start (VoiceOver can take
+ * a second, and what it says late was being credited to the next control), then for a pause.
+ */
+export async function nextUtterance(log: SpeechLog, { startWithinMs = 2500, pauseMs = 500, stepMs = 100 } = {}): Promise<string> {
+  const parts: string[] = [];
+  const take = async () => {
+    const said = await log.spokenPhraseLog();
+    if (said.length) await log.clearSpokenPhraseLog();
+    return said;
+  };
+  for (let waited = 0; waited < startWithinMs && !parts.length; waited += stepMs) {
+    await sleep(stepMs);
+    parts.push(...(await take()));
+  }
+  for (let quiet = 0; parts.length && quiet < pauseMs && parts.length < 30; ) {
+    await sleep(stepMs);
+    const said = await take();
+    parts.push(...said);
+    quiet = said.length ? 0 : quiet + stepMs;
+  }
+  return parts.join(" ").replace(/\s+/g, " ").trim();
+}
+
+/** How a screen reader says a placeholder: "john@doe.com" as "john at doe dot com", dots as "13 bullet". */
+export function spoken(text: string): string {
+  return text
+    .replace(/[•●·*]{2,}/g, (dots) => ` ${dots.length} bullet `)
+    .replace(/@/g, " at ")
+    .replace(/\./g, " dot ")
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim()
+    .toLowerCase();
+}
+
+// The same reading of a control as the finding's, so only controls with that very problem count.
+const matches = (control: NonNullable<Finding["control"]>, el: InteractiveElement): boolean =>
+  el.role === control.role && (control.problem === "keyboard" ? el.name === control.name : nameProblem(el) === control.problem);
+
+interface Stop {
+  id: string | null;
+  said: string;
+}
+
+/**
+ * Tab through the page from the top, twice round, noting which control had focus and everything
+ * said while it did. Arriving on a page, NVDA can say only where focus went ("form landmark",
+ * "Chatwoot, document") and not name the first field; on the way round again it does.
+ */
+async function tabThrough(page: Page, reader: ScreenReader, tabs: number): Promise<Stop[]> {
+  await page.evaluate(BLUR);
+  await reader.focus(page);
+  await reader.said();
+  const stops: Stop[] = [];
+  let first: string | null = null;
+  let arrivals = 0;
+  let previousId: string | null | undefined;
+  for (let i = 0; i < tabs; i++) {
+    await reader.press("Tab");
+    const said = await reader.said();
+    const id = (await page.evaluate(ACTIVE_ID).catch(() => null)) as string | null;
+    if (id !== null && id === first && previousId !== first && ++arrivals === 2) break; // round twice
+    if (first === null) first = id;
+    previousId = id;
+    const known = id === null ? undefined : stops.find((s) => s.id === id);
+    if (known) {
+      if (said && !known.said.includes(said)) known.said = `${known.said} ${said}`.trim();
+    }
+    else stops.push({ id, said });
+  }
+  return stops;
+}
+
+/** A kind of control, in NVDA's or VoiceOver's words: what an announcement of a control includes. */
+const CONTROL_KIND =
+  /\b(button|link|combo box|edit|check ?box|switch|radio button|menu button|toggle button|text field|secure text field|text area|edit text|secure edit text|pop[- ]?up button|slider|tab)\b/i;
+
+const FOCUS = (id: string) => `(() => { const el = document.querySelector('[data-debutly-id="${id}"]'); if (el) el.focus(); })()`;
+
+/**
+ * What the screen reader says about each control a finding is about, heard again on its own: focus
+ * moves to another control on the page and back, as Shift+Tab would. On the walk, a field reached
+ * from the browser's toolbar was announced only as where focus went ("Chatwoot, document", "form
+ * landmark"), and VoiceOver could still be speaking about one control when focus reached the next.
+ * Tab still decides what can be reached; this decides what is said about it.
+ */
+async function hearAgain(page: Page, reader: ScreenReader, stops: Stop[], ids: Set<string>): Promise<void> {
+  for (const [i, stop] of stops.entries()) {
+    // Only where the walk heard no kind of control at all; and only a hearing that names one is
+    // kept, as VoiceOver on a CI Mac sometimes spoke about something else entirely.
+    if (stop.id === null || !ids.has(stop.id) || CONTROL_KIND.test(stop.said)) continue;
+    const neighbour = [...stops.slice(i + 1), ...stops.slice(0, i).reverse()].find((s) => s.id !== null && s.id !== stop.id);
+    if (!neighbour) continue;
+    await page.evaluate(FOCUS(neighbour.id!));
+    await reader.said();
+    await page.evaluate(FOCUS(stop.id));
+    const said = await reader.said();
+    if (CONTROL_KIND.test(said)) stop.said = said;
+  }
+}
+
+function judge(f: Finding, page: string, elements: InteractiveElement[], stops: Stop[], readerName: string): Heard {
+  const control = f.control!;
+  const targets = elements.filter((el) => matches(control, el));
+  const base = { title: f.title, page };
+  if (!targets.length) return { ...base, verdict: "not on the page", said: [], note: "No such control was on the page when it was opened again." };
+  const reached = targets
+    .map((t) => ({ t, said: stops.find((s) => s.id === String(t.id))?.said }))
+    .filter((r): r is { t: InteractiveElement; said: string } => r.said !== undefined);
+  const said = reached.map((r) => r.said);
+  // A dropdown announces its current choice ("combo box, English (en)"): that is its value, not a name.
+  const nameless = reached.find((r) => saidNoName(r.t.value ? r.said.split(r.t.value).join(" ") : r.said));
+  const presses = stops.length;
+  switch (control.problem) {
+    case "keyboard":
+    case "unreached":
+      return said.length
+        ? { ...base, verdict: "not confirmed", said, note: `Tab did reach it: ${readerName} said "${said[0]}".` }
+        : { ...base, verdict: "confirmed", said, note: `Tab never reached it in ${presses} presses.` };
+    case "unnamed":
+      if (!said.length) return { ...base, verdict: "not confirmed", said, note: `Tab never reached it in ${presses} presses; a screen-reader user meets it only reading line by line.` };
+      return nameless
+        ? { ...base, verdict: "confirmed", said, note: `${readerName} said "${nameless.said}", with no name.` }
+        : { ...base, verdict: "check by ear", said, note: `${readerName} said "${said[0]}".` };
+    case "described":
+      return said.length
+        ? { ...base, verdict: "check by ear", said, note: `${readerName} said "${said[0]}": a description after the role, but no name.` }
+        : { ...base, verdict: "not confirmed", said, note: `Tab never reached it in ${presses} presses.` };
+    case "placeholder": {
+      if (!said.length) return { ...base, verdict: "not confirmed", said, note: `Tab never reached it in ${presses} presses.` };
+      const placeholders = targets.map((t) => spoken(t.name)).filter(Boolean);
+      const hit = said.find((s) => placeholders.some((p) => spoken(s).includes(p)));
+      return hit
+        ? { ...base, verdict: "confirmed", said, note: `${readerName} named it by its placeholder: "${hit}".` }
+        : { ...base, verdict: "check by ear", said, note: `${readerName} said "${said[0]}".` };
+    }
+  }
+}
+
+/** Hears each screen-reader finding of a run, and adds what was heard to its report. */
+export async function hearFindings(o: HearOptions): Promise<Heard[]> {
+  const findings = JSON.parse(await readFile(join(o.reportDir, "findings.json"), "utf8")) as Finding[];
+  const sessions = JSON.parse(await readFile(join(o.reportDir, "sessions.json"), "utf8")) as Session[];
+  // One visit per page and agent: the agent whose browser state opens it signed in.
+  const visits = new Map<string, { agentId: string; url: string; findings: Finding[] }>();
+  for (const f of findings) {
+    if (!f.control) continue;
+    const e = f.evidence[0];
+    const step = sessions.find((s) => s.agentId === e?.agentId)?.steps.find((st) => st.index === e.stepIndex);
+    if (!step) continue;
+    const key = `${e.agentId} ${step.observation.url}`;
+    const visit = visits.get(key) ?? { agentId: e.agentId, url: step.observation.url, findings: [] };
+    visit.findings.push(f);
+    visits.set(key, visit);
+  }
+  const heard: Heard[] = [];
+  if (!visits.size) return heard;
+
+  const browser = await o.launch();
+  await o.reader.start();
+  try {
+    for (const visit of visits.values()) {
+      const path = new URL(visit.url).pathname;
+      const stateFile = o.browserStateDir ? join(o.browserStateDir, `${visit.agentId}.json`) : undefined;
+      const state = stateFile && existsSync(stateFile) ? stateFile : undefined;
+      // Signed in first, as the agent ended; a page from before sign-in (sign-up, log in) sends a
+      // signed-in browser on, so it is opened again signed out.
+      const tries = state ? [state, undefined] : [undefined];
+      const landed: string[] = [];
+      let context: BrowserContext | undefined;
+      let page: Page | undefined;
+      for (const tryState of tries) {
+        context = await browser.newContext(tryState ? { storageState: tryState } : {});
+        page = await context.newPage();
+        await page.goto(visit.url).catch(() => {});
+        await page.waitForTimeout(SETTLE_MS);
+        if (new URL(page.url()).pathname === path) break;
+        landed.push(new URL(page.url()).pathname);
+        await context.close();
+        context = undefined;
+      }
+      if (!context || !page) {
+        const note = state
+          ? `Opening ${path} led to ${landed[0]} signed in and to ${landed[1]} signed out: it may be a step shown only once, such as set-up after sign-up.`
+          : `Opening ${path} led to ${landed[0]}; keep the agents' browser state with debutly run --browser-state <dir> to open pages behind sign-in.`;
+        for (const f of visit.findings) heard.push({ title: f.title, page: path, verdict: "not on the page", said: [], note });
+        continue;
+      }
+      try {
+        const elements = (await page.evaluate(SCAN_SCRIPT)) as InteractiveElement[];
+        const names = await accessibleNames(page);
+        if (names) for (const el of elements) if (names.get(el.id)) el.ax = names.get(el.id);
+        const stops = await tabThrough(page, o.reader, o.tabs ?? 120);
+        const ids = new Set(visit.findings.flatMap((f) => elements.filter((el) => matches(f.control!, el)).map((el) => String(el.id))));
+        await hearAgain(page, o.reader, stops, ids);
+        for (const f of visit.findings) heard.push(judge(f, path, elements, stops, o.reader.name.split(" ")[0]));
+      } finally {
+        await context.close();
+      }
+    }
+  } finally {
+    await o.reader.stop().catch(() => {});
+    await browser.close();
+  }
+
+  await writeFile(join(o.reportDir, "heard.json"), JSON.stringify({ reader: o.reader.name, heard }, null, 2));
+  await appendFile(join(o.reportDir, "report.md"), renderHeard(o.reader.name, heard));
+  return heard;
+}
+
+export function renderHeard(readerName: string, heard: Heard[]): string {
+  const count = (v: Verdict) => heard.filter((h) => h.verdict === v).length;
+  const lines = [
+    "",
+    "## Heard with a screen reader",
+    "",
+    `${readerName} went through each page with a screen-reader finding, pressing Tab from the top until it had been round twice. "Confirmed" means it said what the finding says; "check by ear" means a person should judge what it said.`,
+    "",
+    `${count("confirmed")} confirmed, ${count("not confirmed")} not confirmed, ${count("check by ear")} to check by ear, ${count("not on the page")} not on the page when opened again.`,
+    "",
+    ...heard.map((h) => `- **${h.verdict}**: ${h.title}. ${h.note}`),
+    "",
+  ];
+  return lines.join("\n");
+}