debutly 0.0.0-stage → 0.2.0

package/src/agent/parse-reply.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { PRESS_KEYS, type Action } from "../types";
+
+const ActionSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("click"), id: z.number().int() }),
+  z.object({ type: z.literal("fill"), id: z.number().int(), text: z.string() }),
+  z.object({ type: z.literal("upload"), id: z.number().int(), file: z.enum(["photo", "document"]).optional() }),
+  z.object({ type: z.literal("goto"), path: z.string() }),
+  z.object({ type: z.literal("check_email") }),
+  z.object({ type: z.literal("press"), key: z.enum(PRESS_KEYS) }),
+  z.object({ type: z.literal("wait") }),
+  z.object({ type: z.literal("done"), success: z.boolean(), note: z.string() }),
+]);
+
+// Real models sometimes drop the reasoning; the action is what matters.
+const ReplySchema = z.object({ reasoning: z.string().default(""), action: ActionSchema });
+
+export function parseAgentReply(raw: string): { reasoning: string; action: Action } {
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start === -1 || end <= start) throw new Error("no JSON object in agent reply");
+  const reply = actionAsObject(parseQuotedAction(raw.slice(start, end + 1)));
+  const parsed = ReplySchema.safeParse(reply);
+  if (!parsed.success) throw new Error(problemWith(reply, parsed.error));
+  return parsed.data;
+}
+
+/** A reply with reasoning and no action. It carries the reasoning, so the agent can be left to wait. */
+export class NoActionError extends Error {
+  constructor(readonly reasoning: string) {
+    super(`the reply has no "action". Add one, for example {"reasoning":"…","action":{"type":"wait"}}`);
+  }
+}
+
+// Said back to the agent when it is asked again, so in words it can act on. Shown the validator's
+// own JSON for a reply with reasoning and no action, one model sent the same reply three times.
+function problemWith(reply: unknown, error: z.ZodError): string {
+  if (reply && typeof reply === "object" && !("action" in reply)) {
+    const reasoning = (reply as { reasoning?: unknown }).reasoning;
+    throw new NoActionError(typeof reasoning === "string" ? reasoning : "");
+  }
+  return error.issues.map((i) => `${i.path.join(".") || "reply"}: ${i.message}`).join("; ");
+}
+
+/**
+ * The reply split into objects one after another, merged: {"reasoning":"…"} and on the next line
+ * {"action":"press","key":"Enter"} (GLM 5.3 Flash, 2026-10-24, twice in one run). When two whole
+ * replies come, the first one counts. Undefined when there is only one object or one doesn't parse.
+ */
+function splitReply(text: string): Record<string, unknown> | undefined {
+  const objects: string[] = [];
+  let depth = 0;
+  let from = 0;
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inString) {
+      if (c === "\\") i++;
+      else if (c === '"') inString = false;
+    } else if (c === '"') inString = true;
+    else if (c === "{" && depth++ === 0) from = i;
+    else if (c === "}" && depth > 0 && --depth === 0) objects.push(text.slice(from, i + 1));
+  }
+  if (objects.length < 2) return undefined;
+  try {
+    const parsed = objects.map((o) => JSON.parse(o) as unknown);
+    if (!parsed.every((p) => p && typeof p === "object" && !Array.isArray(p))) return undefined;
+    return Object.assign({}, ...(parsed as Record<string, unknown>[]).reverse());
+  } catch {
+    return undefined;
+  }
+}
+
+// Some models (GLM 5.3 Flash) send the action as a string. Unescaped,
+// {"reasoning":"…","action":"{"type":"fill","id":1,"text":"x"}"} is not JSON at all, and asking
+// again got the same reply three times, ending the agent. An action is a flat object, so its
+// quotes can be dropped and the rest parsed as meant. Sometimes the closing quote and brace never
+// come at all; then the reasoning and the action are read out separately.
+function parseQuotedAction(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    const split = splitReply(text);
+    if (split) return split;
+    const unquoted = text.replace(/("action"\s*:\s*)"(\{[^{}]*\})"/, "$1$2");
+    if (unquoted !== text) {
+      try {
+        return JSON.parse(unquoted);
+      } catch {
+        // fall through to reading the parts
+      }
+    }
+    const parts = readParts(text);
+    if (!parts) throw err;
+    return parts;
+  }
+}
+
+function readParts(text: string): { reasoning: string; action: unknown } | undefined {
+  const action = text.match(/"action"\s*:\s*"?\s*(\{[^{}]*\})/)?.[1];
+  if (!action) return undefined;
+  const reasoning = text.match(/"reasoning"\s*:\s*"((?:[^"\\]|\\.)*)"/)?.[1];
+  try {
+    return { reasoning: reasoning ? JSON.parse(`"${reasoning}"`) : "", action: JSON.parse(action.replace(/\\"/g, '"')) };
+  } catch {
+    return undefined;
+  }
+}
+
+const ACTION_TYPES = new Set(["click", "fill", "upload", "goto", "check_email", "press", "wait", "done"]);
+const ACTION_FIELDS = ["id", "text", "file", "path", "key", "success", "note"] as const;
+
+// Escaped, the same mistake parses, with the action as a string holding its JSON. Or the action is
+// flattened into the reply, {"reasoning":"…","action":"click","id":40}: its type as a string, its
+// fields beside it (2026-10-18; asking again got the same reply).
+function actionAsObject(reply: unknown): unknown {
+  if (!reply || typeof reply !== "object" || typeof (reply as { action?: unknown }).action !== "string") return reply;
+  const r = reply as Record<string, unknown> & { action: string };
+  try {
+    return { ...r, action: JSON.parse(r.action) };
+  } catch {
+    if (!ACTION_TYPES.has(r.action)) return reply; // the schema says what is wrong with it
+    const action: Record<string, unknown> = { type: r.action };
+    for (const field of ACTION_FIELDS) if (field in r) action[field] = r[field];
+    return { reasoning: r.reasoning, action };
+  }
+}

package/src/agent/prompt.ts

@@ -0,0 +1,85 @@
+import { inclusionBrief } from "../persona/inclusion";
+import { languageBrief } from "../persona/language";
+import type { InteractiveElement, Observation, Persona } from "../types";
+import { controlLabel, type StepView } from "./label";
+
+export type { StepView } from "./label";
+
+// Stays constant for the whole session so providers can cache it; everything that changes goes in the user message.
+export interface AgentIdentity {
+  email: string;
+}
+
+// `brief` carries shared context, e.g. the company a crew member works at and what their owner reported.
+export function buildSystemPrompt(persona: Persona, goal: string, identity?: AgentIdentity, brief?: string): string {
+  const email = identity
+    ? `Your email address is ${identity.email}. Use it whenever the site asks for your email.
+To read your inbox (for example a login link or a confirmation), reply {"type":"check_email"}. To open a link from an email, use {"type":"goto","path":"<the full link>"}.`
+    : `Use emails at example.com.`;
+  const about = [
+    `You are ${persona.name}. ${persona.background}`,
+    `Patience: ${persona.patience}. Tech savvy: ${persona.techSavvy}.`,
+    persona.role ? `Your role: ${persona.role}.` : "",
+    brief ?? "",
+    persona.inclusion ? inclusionBrief(persona.inclusion) : "",
+    languageBrief(persona.language),
+  ]
+    .filter(Boolean)
+    .join("\n");
+  return `${about}
+
+You are a real prospective customer using this web product for the first time. Act exactly as this person would: read what is on screen, decide what they would do next, and react honestly to confusion or breakage. If something fails, try a reasonable alternative like a real person. Give up (done with success false) at the point this person would give up, and say why.
+
+Your goal: ${goal}
+
+${email}
+Use test data only: card number 4242 4242 4242 4242. Never enter real personal or payment data.
+
+Reply with exactly one JSON object: {"reasoning": string, "action": Action}
+Action is one of:
+{"type":"click","id":number}
+{"type":"fill","id":number,"text":string}  (on a select or dropdown, text is the option to choose)
+{"type":"upload","id":number,"file":"photo"|"document"}  (attach a file through an upload button or file field: you have a sample photo and a sample CV/document)
+{"type":"goto","path":string}
+{"type":"press","key":"Escape"|"Enter"|"Space"|"Tab"|"ArrowDown"|"ArrowUp"}  (e.g. Escape closes a popup that blocks the page; Space presses the focused button or ticks a box)
+{"type":"wait"}  (the page is still loading, e.g. a spinner or a form that has not appeared yet: wait a few seconds rather than leave)${identity ? `\n{"type":"check_email"}` : ""}
+{"type":"done","success":boolean,"note":string}`;
+}
+
+/** A control's state, as a person sees it (and a screen reader announces it). */
+function stateOf(e: InteractiveElement): string {
+  const states = [
+    e.disabled ? "disabled" : "",
+    e.readOnly ? "read-only" : "",
+    e.checked === undefined ? "" : e.checked ? "checked" : "not checked",
+    e.expanded === undefined ? "" : e.expanded ? "open" : "closed",
+    e.filled ? "filled in" : "",
+    !e.options && e.value ? `holds "${e.value}"` : "",
+  ].filter(Boolean);
+  return states.length ? ` (${states.join(", ")})` : "";
+}
+
+function describeElement(e: InteractiveElement, screenReader = false): string {
+  const line = `[${e.id}] ${controlLabel(e, screenReader)}${stateOf(e)}`;
+  if (!e.options) return line;
+  return `${line} set to "${e.value ?? ""}", options: ${e.options.map((o) => `"${o}"`).join(" | ")}`;
+}
+
+export function buildStepMessage(obs: Observation, history: string[], view: StepView = {}): string {
+  const shown = view.screenReader ? obs.elements.filter((e) => !e.ax?.hidden) : obs.elements;
+  const elements = shown.map((e) => describeElement(e, view.screenReader)).join("\n");
+  const past = history.length ? history.map((h, i) => `${i + 1}. ${h}`).join("\n") : "(none yet)";
+  return `URL: ${obs.url}
+Title: ${obs.title}
+
+Interactive elements:
+${elements}
+
+Visible text:
+${obs.text}
+
+Your actions so far:
+${past}
+
+What do you do next?`;
+}

package/src/agent/run-agent.ts

@@ -0,0 +1,68 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { Browser } from "playwright";
+import type { ArtifactStore } from "../artifacts/store";
+import type { Inbox } from "../inbox/types";
+import type { ModelPrice } from "../llm/meter";
+import type { LlmClient } from "../llm/types";
+import { openAgentPage } from "../persona/inclusion";
+import type { RunStore } from "../store/run-store";
+import type { Persona, Session } from "../types";
+import { runSession } from "./loop";
+
+export interface AgentRunDeps {
+  browser: Browser;
+  llm: LlmClient;
+  origin: string;
+  maxSteps: number;
+  artifacts: ArtifactStore;
+  emailOf: (persona: Persona) => string;
+  inbox?: Inbox;
+  caps?: { maxTokens?: number; maxMs?: number };
+  price?: ModelPrice | null;
+  shouldStop?: () => boolean | Promise<boolean>;
+  /** With a store and run id, the session and each step are recorded as they happen. */
+  store?: RunStore;
+  runId?: string;
+  /** Keeps the agent's browser state here as <agent id>.json when it finishes, for `debutly hear`. */
+  browserStateDir?: string;
+}
+
+/**
+ * One agent, start to finish, in its own browser context (no shared cookies or login, even
+ * inside a crew). Used in-process by runSimulation and by queue workers alike.
+ */
+export async function runAgentSession(d: AgentRunDeps, persona: Persona, goal: string, brief: string | undefined): Promise<Session> {
+  const record = d.store && d.runId ? { store: d.store, runId: d.runId } : undefined;
+  const { context, page } = await openAgentPage(d.browser, persona.inclusion, persona.language);
+  if (record) await record.store.startSession(record.runId, persona.id, goal);
+  let session: Session;
+  try {
+    session = await runSession({
+      page,
+      llm: d.llm,
+      persona,
+      goal,
+      origin: d.origin,
+      maxSteps: d.maxSteps,
+      artifacts: d.artifacts,
+      identity: d.inbox ? { email: d.emailOf(persona) } : undefined,
+      inbox: d.inbox,
+      brief,
+      caps: d.caps,
+      price: d.price,
+      shouldStop: d.shouldStop,
+      onStep: record ? (step) => record.store.appendStep(record.runId, persona.id, step) : undefined,
+    });
+  } catch (err) {
+    session = { agentId: persona.id, personaName: persona.name, goal, steps: [], outcome: "error", outcomeNote: err instanceof Error ? err.message : String(err) };
+  } finally {
+    if (d.browserStateDir) {
+      await mkdir(d.browserStateDir, { recursive: true });
+      await context.storageState({ path: join(d.browserStateDir, `${persona.id}.json`) }).catch(() => {});
+    }
+    await context.close();
+  }
+  if (record) await record.store.finishSession(record.runId, session);
+  return session;
+}

package/src/artifacts/db.ts

@@ -0,0 +1,55 @@
+import { and, eq, lt } from "drizzle-orm";
+import type { Db } from "../store/db";
+import { screenshots } from "../store/schema";
+import type { ArtifactStore, ScreenshotFormat } from "./store";
+
+/** What a step's screenshot reference looks like when the image is in the database. */
+export const DB_SCREENSHOT_PREFIX = "db:";
+
+/**
+ * Screenshots in the run's own Postgres, for deployments with no object storage: a free
+ * Postgres (Neon's 0.5 GB) is all the dashboard needs. Compact JPEGs, and prune() drops old ones.
+ */
+export class DbArtifactStore implements ArtifactStore {
+  readonly screenshotFormat: ScreenshotFormat = { type: "jpeg", quality: 50 };
+
+  constructor(
+    private readonly db: Db,
+    private readonly runId: string,
+  ) {}
+
+  async put(key: string, body: Buffer, contentType: string): Promise<string> {
+    await this.db.insert(screenshots).values({ runId: this.runId, key, contentType, data: body }).onConflictDoNothing();
+    return `${DB_SCREENSHOT_PREFIX}${this.runId}/${key}`;
+  }
+
+  /** Delete screenshots older than `days`: steps keep their text, the pictures go. */
+  static async prune(db: Db, days: number, now = new Date()): Promise<number> {
+    const cutoff = new Date(now.getTime() - days * 86_400_000);
+    const deleted = await db.delete(screenshots).where(lt(screenshots.createdAt, cutoff)).returning({ key: screenshots.key });
+    return deleted.length;
+  }
+
+  static async get(db: Db, runId: string, key: string): Promise<{ contentType: string; data: Buffer } | null> {
+    const [row] = await db
+      .select({ contentType: screenshots.contentType, data: screenshots.data })
+      .from(screenshots)
+      .where(and(eq(screenshots.runId, runId), eq(screenshots.key, key)));
+    return row ?? null;
+  }
+}
+
+/** Every screenshot to each store (e.g. the CI artifact folder and the database); the last one's reference is kept. */
+export class TeeArtifactStore implements ArtifactStore {
+  readonly screenshotFormat?: ScreenshotFormat;
+
+  constructor(private readonly stores: ArtifactStore[]) {
+    this.screenshotFormat = stores.find((s) => s.screenshotFormat)?.screenshotFormat;
+  }
+
+  async put(key: string, body: Buffer, contentType: string): Promise<string> {
+    let ref = "";
+    for (const store of this.stores) ref = await store.put(key, body, contentType);
+    return ref;
+  }
+}

package/src/artifacts/s3.ts

@@ -0,0 +1,36 @@
+import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import type { ArtifactStore } from "./store";
+
+export interface S3ArtifactOptions {
+  bucket: string;
+  /** Usually the run id, so each run's artifacts sit together. */
+  prefix: string;
+  /** Base URL the bucket is served at, for links in reports (e.g. MinIO's http://localhost:9000/<bucket>). */
+  publicBaseUrl: string;
+  client: Pick<S3Client, "send">;
+}
+
+/** Any S3-compatible store: MinIO in the self-hosted stack, S3/R2/etc. in production. */
+export class S3ArtifactStore implements ArtifactStore {
+  constructor(private readonly o: S3ArtifactOptions) {}
+
+  /** From DEBUTLY_S3_ENDPOINT, DEBUTLY_S3_BUCKET, DEBUTLY_S3_ACCESS_KEY, DEBUTLY_S3_SECRET_KEY (and optional DEBUTLY_S3_REGION, DEBUTLY_S3_PUBLIC_URL); undefined if unset. */
+  static fromEnv(env: Record<string, string | undefined>, prefix: string): S3ArtifactStore | undefined {
+    const endpoint = env.DEBUTLY_S3_ENDPOINT;
+    if (!endpoint) return undefined;
+    const bucket = env.DEBUTLY_S3_BUCKET ?? "debutly";
+    const client = new S3Client({
+      endpoint,
+      region: env.DEBUTLY_S3_REGION ?? "us-east-1",
+      forcePathStyle: true,
+      credentials: { accessKeyId: env.DEBUTLY_S3_ACCESS_KEY ?? "", secretAccessKey: env.DEBUTLY_S3_SECRET_KEY ?? "" },
+    });
+    return new S3ArtifactStore({ bucket, prefix, publicBaseUrl: env.DEBUTLY_S3_PUBLIC_URL ?? `${endpoint.replace(/\/+$/, "")}/${bucket}`, client });
+  }
+
+  async put(key: string, body: Buffer, contentType: string): Promise<string> {
+    const fullKey = `${this.o.prefix}/${key}`;
+    await this.o.client.send(new PutObjectCommand({ Bucket: this.o.bucket, Key: fullKey, Body: body, ContentType: contentType }));
+    return `${this.o.publicBaseUrl.replace(/\/+$/, "")}/${fullKey}`;
+  }
+}

package/src/artifacts/store.ts

@@ -0,0 +1,26 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+/** How a store wants screenshots taken; PNG when it doesn't say. */
+export interface ScreenshotFormat {
+  type: "jpeg";
+  quality: number;
+}
+
+/** Where step artifacts (screenshots) go. Returns a path or URL the report can show. */
+export interface ArtifactStore {
+  put(key: string, body: Buffer, contentType: string): Promise<string>;
+  readonly screenshotFormat?: ScreenshotFormat;
+}
+
+/** A local folder: what file-only CLI runs (and CI) have always used. */
+export class LocalArtifactStore implements ArtifactStore {
+  constructor(private readonly dir: string) {}
+
+  async put(key: string, body: Buffer, _contentType?: string): Promise<string> {
+    const path = join(this.dir, key);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, body);
+    return path;
+  }
+}

package/src/bin.ts

@@ -0,0 +1,140 @@
+// The `debutly` command: `npx debutly init` once, then `npx debutly` runs the agents.
+import "./util/load-env";
+import "./util/legacy-env";
+import "./util/key-defaults";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_FILE, configArgs, readConfig } from "./config";
+import { OutOfCreditsError } from "./llm/types";
+
+const HELP = `Debutly: AI agents use a test copy of your app like your first customers, and report what breaks.
+
+Usage: npx debutly [command] [flags]
+
+  init         a few questions, then a ${CONFIG_FILE} (and, if you want, a weekly GitHub workflow)
+  run          the agents, with the settings in ${CONFIG_FILE} (the default command)
+  doctor       checks the key, the browser, the config and that the app answers
+  perceive     skeptical-buyer evaluators judge your pages, variants or an idea
+  hear         checks a run's screen-reader findings with NVDA (Windows) or VoiceOver (macOS)
+  worker       an agent worker for queued runs
+  cancel       stops a run: cancel <run id> --store <url>
+  import       loads earlier runs from GitHub Actions report artifacts
+  predictions  records real outcomes and shows prediction accuracy
+  costs        your OpenRouter key's spend and each app's latest run
+
+Flags override ${CONFIG_FILE}, e.g. npx debutly --tier standard --max-cost 3
+The model key is read from DEBUTLY_API_KEY (or OPENROUTER_API_KEY, ANTHROPIC_API_KEY), and from a .env file here.
+Docs: https://debutly.dev/docs`;
+
+const [first, ...rest] = process.argv.slice(2);
+const flagsOnly = !first || (first.startsWith("-") && !["--help", "-h", "--version", "-v"].includes(first));
+const command = flagsOnly ? "run" : first;
+const args = flagsOnly ? process.argv.slice(2) : rest;
+
+// The other entry points read their own flags from process.argv, as if run directly.
+const handOver = (entry: string, argv: string[]) => {
+  process.argv = [process.argv[0], fileURLToPath(new URL(entry, import.meta.url)), ...argv];
+};
+
+async function run(): Promise<void> {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(HELP);
+    return;
+  }
+  let config;
+  try {
+    config = readConfig();
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+  if (!config && !args.includes("--url")) {
+    console.error(`No ${CONFIG_FILE} here. Set one up with: npx debutly init\n(or pass --url, --goal and --icp)`);
+    process.exit(1);
+  }
+  let argv: string[];
+  try {
+    argv = [...(config ? configArgs(config) : []), ...args];
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+  if (process.env.DEBUTLY_STORE_URL && !argv.includes("--store")) argv.push("--store", process.env.DEBUTLY_STORE_URL);
+  if (!argv.includes("--out")) argv.push("--out", join(".debutly", "runs", new Date().toISOString().replace(/[:.]/g, "-")));
+
+  const { chromiumInstalled, installChromium } = await import("./util/chromium");
+  if (!chromiumInstalled()) {
+    console.log("Downloading Chromium for the agents (once per machine, about 150 MB)...");
+    if (!installChromium()) {
+      console.error("Couldn't download Chromium. Try: npx playwright install chromium");
+      process.exit(1);
+    }
+  }
+  handOver("./cli.ts", argv);
+  await import("./cli");
+}
+
+try {
+  switch (command) {
+    case "run":
+      await run();
+      break;
+    case "init": {
+      const { init } = await import("./init");
+      process.exitCode = await init();
+      break;
+    }
+    case "doctor": {
+      const { doctor } = await import("./doctor");
+      process.exitCode = await doctor();
+      break;
+    }
+    case "perceive":
+      handOver("./perceive.ts", args);
+      await import("./perceive");
+      break;
+    case "hear":
+      handOver("./hear-cli.ts", args);
+      await import("./hear-cli");
+      break;
+    case "worker":
+      handOver("./worker.ts", args);
+      await import("./worker");
+      break;
+    case "cancel":
+      handOver("./cancel.ts", args);
+      await import("./cancel");
+      break;
+    case "import":
+      handOver("./import.ts", args);
+      await import("./import");
+      break;
+    case "predictions":
+      handOver("./predictions.ts", args);
+      await import("./predictions");
+      break;
+    case "costs":
+      handOver("./costs.ts", args);
+      await import("./costs");
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(HELP);
+      break;
+    case "version":
+    case "--version":
+    case "-v":
+      console.log(createRequire(import.meta.url)("../package.json").version);
+      break;
+    default:
+      console.error(`Unknown command "${command}".\n\n${HELP}`);
+      process.exitCode = 1;
+  }
+} catch (err) {
+  // A known dead end gets its fix, not a stack trace.
+  if (!(err instanceof OutOfCreditsError)) throw err;
+  console.error(`${err.message}\n\nTop up at https://openrouter.ai/settings/credits, or raise the key's limit, then run again.`);
+  process.exitCode = 1;
+}

package/src/browser/ax.ts

@@ -0,0 +1,77 @@
+import type { CDPSession, Page } from "playwright";
+import type { AccessibleName } from "../types";
+
+// The name and role Chromium gives assistive technology for each element Debutly tagged, read
+// from its accessibility tree. Debutly's own reading of names (scan-script) is close but not the
+// same: an icon button named by its SVG <title> has a name here and none there, and a control
+// hidden with aria-hidden is listed there but hidden here. Chromium only; undefined elsewhere.
+
+interface AXNode {
+  ignored: boolean;
+  ignoredReasons?: { name: string }[];
+  role?: { value?: string };
+  name?: { value?: string };
+  description?: { value?: string };
+  backendDOMNodeId?: number;
+}
+
+interface DOMNode {
+  backendNodeId: number;
+  attributes?: string[];
+  children?: DOMNode[];
+  shadowRoots?: DOMNode[];
+  contentDocument?: DOMNode;
+}
+
+const sessions = new WeakMap<Page, Promise<CDPSession | undefined>>();
+
+function cdpFor(page: Page): Promise<CDPSession | undefined> {
+  let session = sessions.get(page);
+  if (!session) {
+    session = page
+      .context()
+      .newCDPSession(page)
+      .then(async (s) => {
+        await s.send("Accessibility.enable");
+        return s;
+      })
+      .catch(() => undefined);
+    sessions.set(page, session);
+  }
+  return session;
+}
+
+/** Debutly id → what assistive technology is told about that element. */
+export async function accessibleNames(page: Page): Promise<Map<number, AccessibleName> | undefined> {
+  const cdp = await cdpFor(page);
+  if (!cdp) return undefined;
+  try {
+    const [{ nodes }, { root }] = await Promise.all([
+      cdp.send("Accessibility.getFullAXTree") as Promise<{ nodes: AXNode[] }>,
+      cdp.send("DOM.getDocument", { depth: -1, pierce: true }) as Promise<{ root: DOMNode }>,
+    ]);
+    const tagged = new Map<number, number>();
+    const walk = (n: DOMNode) => {
+      const attrs = n.attributes ?? [];
+      for (let i = 0; i < attrs.length; i += 2) if (attrs[i] === "data-debutly-id") tagged.set(n.backendNodeId, Number(attrs[i + 1]));
+      for (const child of [...(n.children ?? []), ...(n.shadowRoots ?? []), ...(n.contentDocument ? [n.contentDocument] : [])]) walk(child);
+    };
+    walk(root);
+    const out = new Map<number, AccessibleName>();
+    for (const node of nodes) {
+      const id = node.backendDOMNodeId === undefined ? undefined : tagged.get(node.backendDOMNodeId);
+      if (id === undefined) continue;
+      const description = (node.description?.value ?? "").replace(/\s+/g, " ").trim();
+      out.set(id, {
+        name: (node.name?.value ?? "").replace(/\s+/g, " ").trim(),
+        role: node.role?.value ?? "",
+        hidden: node.ignored,
+        ...(description ? { description } : {}),
+      });
+    }
+    return out;
+  } catch {
+    // A page navigating away mid-read, or a detached frame: this look goes without them.
+    return undefined;
+  }
+}