debutly 0.0.0-stage → 0.2.0

package/src/browser/execute.ts

@@ -0,0 +1,401 @@
+import type { Locator, Page } from "playwright";
+import type { Action, ActionResult, InteractiveElement, Observation } from "../types";
+import { sampleFiles, sampleFor, type SampleKind } from "./samples";
+
+const DESTRUCTIVE = /\b(delete|remove|destroy|deactivate|close account|cancel (my )?(subscription|account))\b/i;
+
+// Agents never click anything named like this, whichever action would click it: a plain click,
+// the button behind an upload, or a custom dropdown and the option chosen in it.
+class Refused extends Error {}
+function refuseDestructive(name: string): void {
+  if (DESTRUCTIVE.test(name)) throw new Refused(`destructive action refused: "${name}"`);
+}
+// Every name the control goes by: Debutly's reading, and the one the browser gives assistive
+// technology, which is what the screen-reader agent sees (a button holding only an image whose alt
+// says "Delete workspace" has no name in the first and that one in the second).
+function refuseDestructiveControl(el: InteractiveElement): void {
+  refuseDestructive(el.name);
+  if (el.ax) refuseDestructive(el.ax.name);
+}
+
+export const COVERED = "another element covers it";
+export const NOT_BY_KEYBOARD = "can't be reached with the keyboard";
+const WAIT_MS = 3_000;
+const OPTION = '[role="option"]';
+
+export interface ExecuteOptions {
+  /**
+   * Keyboard only, as a screen-reader user works: a control is used by moving focus to it (as
+   * Tab would) and pressing Enter or Space, so one that isn't in the tab order can't be used.
+   * Items inside lists, menus, tab lists and radio groups are reached with arrow keys, not Tab;
+   * those are still chosen as a mouse would.
+   */
+  keyboard?: boolean;
+}
+
+// Roles reached with arrow keys inside their list, menu, tab list or group, not with Tab.
+const ARROW_KEY_ITEMS = new Set(["option", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "treeitem", "radio", "input:radio"]);
+// What Space presses; Enter presses the rest. Text fields and selects are only focused.
+const SPACE_KEY = new Set(["checkbox", "input:checkbox", "switch"]);
+// Buttons take Enter and Space alike, so a keyboard user who gets nothing from Enter tries Space.
+const BUTTON_ROLE = /^(button|input:(submit|button|reset|image))$/;
+/** How long to watch for Enter's effect before trying Space. */
+const ENTER_SETTLE_MS = 1_000;
+
+/**
+ * Presses Enter on the focused button; if nothing happened that a person would notice (the page
+ * sent nothing, kept its address and looks exactly the same), presses Space, as a keyboard user
+ * would. True when Space then did what Enter didn't: Twenty's set-up "Continue" ignores Enter and
+ * goes on with Space, and a keyboard-only agent that knew only Enter gave up there twice
+ * (2026-10-24). It goes by how the page looks, not its text, so a toggle whose change is only
+ * visual is never pressed twice.
+ */
+async function pressEnterThenSpace(page: Page, id: number): Promise<boolean> {
+  const look = () => page.screenshot({ animations: "disabled", timeout: 5_000 }).catch(() => undefined);
+  const url = page.url();
+  // The first key press on a page draws the focus ring; Shift, which presses nothing, draws it
+  // first, or Enter would always seem to have changed the page.
+  await page.keyboard.press("Shift");
+  const before = await look();
+  let sent = 0;
+  const count = () => sent++;
+  page.on("request", count);
+  try {
+    await page.keyboard.press("Enter");
+    await page.waitForTimeout(ENTER_SETTLE_MS);
+  } finally {
+    page.off("request", count);
+  }
+  const afterEnter = sent || page.url() !== url || !before ? undefined : await look();
+  if (!before || !afterEnter || !afterEnter.equals(before)) return false;
+  // Space goes to whatever has focus: only to the button that was checked before Enter, never to
+  // something Enter moved focus to unseen.
+  const stillFocused = await page.evaluate((target) => document.activeElement?.getAttribute("data-debutly-id") === target, String(id));
+  if (!stillFocused) return false;
+  await page.keyboard.press("Space");
+  await page.waitForTimeout(ENTER_SETTLE_MS);
+  if (page.url() !== url) return true;
+  const afterSpace = await look();
+  return !!afterSpace && !afterSpace.equals(before);
+}
+const FOCUS_ONLY = /^(input:(text|email|password|number|search|tel|url|date|time|datetime-local|month|week)|textarea|select|combobox)$/;
+
+// Is the focused element entirely hidden behind something else? Checks its middle and four points
+// just inside its corners: WCAG 2.4.11 asks that focus is not entirely hidden. Returns what covers it.
+const focusCoveredScript = (id: number) => `(() => {
+  const el = document.querySelector('[data-debutly-id="${id}"]');
+  if (!el) return null;
+  const r = el.getBoundingClientRect();
+  const points = [[0.5, 0.5], [0.1, 0.1], [0.9, 0.1], [0.1, 0.9], [0.9, 0.9]].map(([fx, fy]) => [r.left + r.width * fx, r.top + r.height * fy]);
+  let cover = null;
+  for (const [x, y] of points) {
+    if (x < 0 || y < 0 || x >= innerWidth || y >= innerHeight) continue;
+    const hit = document.elementFromPoint(x, y);
+    if (!hit || hit === el || el.contains(hit) || hit.contains(el)) return null;
+    cover = cover || hit;
+  }
+  if (!cover) return 'the edge of the window';
+  const classes = typeof cover.className === 'string' ? cover.className.trim().split(/\\s+/).filter(Boolean).slice(0, 2) : [];
+  const text = (cover.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 50);
+  return cover.tagName.toLowerCase() + (cover.id ? '#' + cover.id : '') + classes.map((c) => '.' + c).join('') + (text ? ' ("' + text + '")' : '');
+})()`;
+
+class NotByKeyboard extends Error {}
+/** A control a person can't use at all right now, whatever they use: said as it is. */
+class Unusable extends Error {}
+
+/** Moves focus to the control as Tab would; refuses one that isn't in the tab order. Returns what hides it, if anything. */
+async function focusByKeyboard(page: Page, locator: Locator, id: number): Promise<string | undefined> {
+  const reach = await locator.evaluate(
+    (node) => {
+      const el = node as HTMLElement & { disabled?: boolean };
+      if (el.disabled === true || el.getAttribute("aria-disabled") === "true") return "disabled";
+      return el.tabIndex >= 0 && !el.closest("[inert]") ? "tabbable" : "untabbable";
+    },
+    undefined,
+    { timeout: 5_000 },
+  );
+  // A disabled button can't take focus, so Enter went to whatever had it, and the agent was told
+  // only that nothing changed; it pressed "Create account" again and gave up (2026-10-24). A mouse
+  // click on it is told it is disabled; so is a key press.
+  if (reach === "disabled") throw new Unusable(UNUSABLE.disabled);
+  if (reach === "untabbable") throw new NotByKeyboard(`${NOT_BY_KEYBOARD}: it isn't in the tab order`);
+  await locator.focus({ timeout: 5_000 });
+  return ((await page.evaluate(focusCoveredScript(id))) as string | null) ?? undefined;
+}
+
+// Playwright's timeout message hides the cause in its call log; say it the way a person would notice it.
+export function describeFailure(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err);
+  const covered = message.match(/(<[^\n]*?>)[^\n]*?(?: from [^\n]*? subtree)? intercepts pointer events/);
+  if (covered) return `${COVERED}: ${covered[1].slice(0, 160)}`;
+  if (/element is not enabled|element is disabled/.test(message)) return "the element is disabled";
+  if (/element is not visible/.test(message)) return "the element is not visible";
+  return message.split("\n")[0];
+}
+
+// When Playwright gives up waiting on an element it says only "Timeout exceeded", and an agent
+// told that tries the same thing again. A person can see why: the field only opens for typing
+// after its edit button, or the link is in a side menu that is shut. A string, like SCAN_SCRIPT.
+const WHY_UNUSABLE_SCRIPT = (id: number) => `(() => {
+  const el = document.querySelector('[data-debutly-id="${id}"]');
+  if (!el) return 'gone';
+  if (el.disabled || el.getAttribute('aria-disabled') === 'true') return 'disabled';
+  if ((el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') && el.readOnly) return 'readonly';
+  const style = getComputedStyle(el);
+  el.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+  const r = el.getBoundingClientRect();
+  if (r.width === 0 || r.height === 0 || style.visibility === 'hidden') return 'hidden';
+  if (r.right <= 0 || r.bottom <= 0 || r.left >= innerWidth || r.top >= innerHeight) return 'offscreen';
+  return '';
+})()`;
+
+const UNUSABLE: Record<string, string> = {
+  gone: "the element is no longer on the page",
+  disabled: "the element is disabled",
+  readonly: "the field is read-only, so it can't be typed in yet; there may be a button to edit it",
+  hidden: "the element is not visible",
+  offscreen: "it is off the screen, perhaps in a menu or panel that is closed; open that first",
+};
+
+async function explainTimeout(page: Page, id: number, err: unknown): Promise<string | undefined> {
+  if (!/Timeout \d+ms exceeded/.test(err instanceof Error ? err.message : String(err))) return undefined;
+  const why = (await page.evaluate(WHY_UNUSABLE_SCRIPT(id)).catch(() => "")) as string;
+  return UNUSABLE[why];
+}
+
+// Playwright clicks an element's centre; a person clicks whatever part of it they can see.
+async function clickVisiblePart(page: Page, id: number): Promise<boolean> {
+  const locator = page.locator(`[data-debutly-id="${id}"]`);
+  await locator.scrollIntoViewIfNeeded({ timeout: 2_000 }).catch(() => {});
+  const box = await locator.boundingBox();
+  if (!box) return false;
+  for (const fy of [0.5, 0.25, 0.75]) {
+    for (const fx of [0.1, 0.3, 0.5, 0.7, 0.9]) {
+      const x = box.x + box.width * fx;
+      const y = box.y + box.height * fy;
+      const reachable = await page.evaluate(
+        ([px, py, target]) => {
+          const hit = document.elementFromPoint(px, py);
+          const el = document.querySelector(`[data-debutly-id="${target}"]`);
+          return !!(hit && el && (hit === el || el.contains(hit)));
+        },
+        [x, y, id] as const,
+      );
+      if (reachable) {
+        await page.mouse.click(x, y);
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// A native select's list is drawn outside the page, where arrow keys move a highlight the agent
+// can't see: choose the option by its label, as a person picks what they read.
+async function choose(select: Locator, text: string): Promise<void> {
+  const labels = await select.evaluate((el) => Array.from((el as HTMLSelectElement).options, (o) => o.label));
+  const label = labels[matchOption(labels, text)];
+  refuseDestructive(label);
+  await select.selectOption({ label }, { timeout: 5_000 });
+}
+
+/** The option a person would pick for `text`: the one it names, else the first containing it. */
+function matchOption(labels: string[], text: string): number {
+  const want = text.trim().toLowerCase();
+  let i = labels.findIndex((l) => l.trim().toLowerCase() === want);
+  if (i === -1) i = labels.findIndex((l) => l.toLowerCase().includes(want));
+  if (i === -1) throw new Error(`no option "${text}"; the options are ${labels.map((l) => `"${l}"`).join(", ")}`);
+  return i;
+}
+
+/** The options of the dropdown that is open now: each visible role="option", with its position. */
+async function openOptions(page: Page): Promise<{ label: string; nth: number }[]> {
+  const all = await page.locator(OPTION).evaluateAll((els) =>
+    els.map((el) => ({
+      label: (el.textContent ?? "").replace(/\s+/g, " ").trim(),
+      visible: typeof el.checkVisibility === "function" ? el.checkVisibility() : (el as HTMLElement).offsetParent !== null,
+    })),
+  );
+  return all.flatMap((o, nth) => (o.visible ? [{ label: o.label, nth }] : []));
+}
+
+// A custom dropdown (a button or div with role="combobox", as Radix and shadcn build them) takes
+// no typing: a person opens it and clicks the option they read. Agents typed into them and got
+// "Element is not an <input>" again and again, until the report called the page stuck.
+async function pick(page: Page, trigger: Locator, text: string): Promise<void> {
+  const appear = () => page.locator(OPTION).first().waitFor({ state: "visible", timeout: 2_000 }).catch(() => {});
+  if (!(await openOptions(page)).length) {
+    await trigger.click({ timeout: 5_000 });
+    await appear();
+  }
+  // Some open on a key rather than a click.
+  if (!(await openOptions(page)).length) {
+    await trigger.focus();
+    await page.keyboard.press("ArrowDown");
+    await appear();
+  }
+  const options = await openOptions(page);
+  if (!options.length) throw new Error("the dropdown shows no options");
+  let chosen: { label: string; nth: number };
+  try {
+    chosen = options[matchOption(options.map((o) => o.label), text)];
+    refuseDestructive(chosen.label);
+  } catch (err) {
+    await page.keyboard.press("Escape"); // leave it closed, as a person who found nothing would
+    throw err;
+  }
+  await page.locator(OPTION).nth(chosen.nth).click({ timeout: 5_000 });
+}
+
+// A key can click too:
+// - Enter activates the focused button or link, or the option a combobox highlights
+//   (aria-activedescendant);
+// - Enter in a form field submits its form through the form's default button, which may sit
+//   outside the form (form="…"), or with no button through the form itself;
+// - Space presses the focused button, or ticks the focused box;
+// - an arrow key moves a focused native select to the next option.
+// Each thing the key would set off is listed with every name it goes by (aria-label, the elements
+// aria-labelledby points at, labels, text, value, title) and its data-debutly-id, so the check also
+// sees the name agents see. With nothing interactive focused there is nothing: the page's own text
+// is not a button. A string, like SCAN_SCRIPT: tsx injects helpers into functions the page lacks.
+const keyTargetsScript = (key: string) => `(() => {
+  const key = ${JSON.stringify(key)};
+  const el = document.activeElement;
+  if (!el || el === document.body || el === document.documentElement) return [];
+  const targets = [];
+  const add = (e) => {
+    if (!e) return;
+    const names = [e.getAttribute('aria-label'), e.getAttribute('title')];
+    for (const ref of (e.getAttribute('aria-labelledby') || '').split(/\\s+/).filter(Boolean)) {
+      const r = document.getElementById(ref);
+      if (r) names.push(r.textContent);
+    }
+    if (e.labels) for (const l of e.labels) names.push(l.textContent);
+    if (e.tagName === 'INPUT' || e.tagName === 'BUTTON') names.push(e.value);
+    if (e.tagName === 'INPUT' && e.type === 'image') names.push(e.getAttribute('alt'));
+    if (e.tagName !== 'INPUT') names.push(e.innerText);
+    targets.push({ id: e.getAttribute('data-debutly-id'), names: names.filter((n) => n && n.trim()) });
+  };
+  if (key === 'Enter') {
+    const active = el.getAttribute('aria-activedescendant');
+    if (active) add(document.getElementById(active));
+    const field = el.tagName === 'INPUT' && !['submit', 'button', 'reset', 'image'].includes(el.type);
+    if (field && el.form) {
+      const button = Array.from(el.form.elements).find((e) =>
+        (e.tagName === 'BUTTON' && e.type === 'submit') || (e.tagName === 'INPUT' && (e.type === 'submit' || e.type === 'image')));
+      if (button) add(button);
+      else targets.push({ id: null, names: [el.form.getAttribute('aria-label'), el.form.getAttribute('name'), el.form.getAttribute('action')].filter((n) => n && n.trim()) });
+    } else if (!field && el.matches('a, button, input, summary, [role="button"], [role="link"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="tab"]')) {
+      add(el);
+    }
+  }
+  if (key === 'Space' && el.matches('button, summary, input[type="checkbox"], input[type="radio"], input[type="submit"], input[type="button"], input[type="reset"], input[type="image"], [role="button"], [role="checkbox"], [role="switch"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="tab"]')) {
+    add(el);
+  }
+  if ((key === 'ArrowDown' || key === 'ArrowUp') && el.tagName === 'SELECT') {
+    const next = el.options[el.selectedIndex + (key === 'ArrowDown' ? 1 : -1)];
+    if (next) targets.push({ id: null, names: [next.label] });
+  }
+  return targets;
+})()`;
+
+async function namesAKeyWouldActivate(page: Page, key: string, obs: Observation): Promise<string[]> {
+  const targets = (await page.evaluate(keyTargetsScript(key))) as { id: string | null; names: string[] }[];
+  return targets.flatMap((t) => [...t.names, ...obs.elements.filter((e) => t.id !== null && String(e.id) === t.id).flatMap((e) => [e.name, e.ax?.name ?? ""])]);
+}
+
+// Attach a sample file, as a person picks one from their computer. A visible file field takes it
+// directly; an upload button, label or drop zone opens the file picker, which is answered.
+// Without this an agent asked for a photo (an Instagram post needs one) could only give up.
+async function upload(page: Page, target: Locator, isFileField: boolean, wanted?: SampleKind): Promise<void> {
+  const files = await sampleFiles();
+  if (isFileField) {
+    await target.setInputFiles(files[wanted ?? sampleFor(await target.getAttribute("accept"))], { timeout: 5_000 });
+    return;
+  }
+  const chooser = page.waitForEvent("filechooser", { timeout: 5_000 }).catch(() => null);
+  await target.click({ timeout: 5_000 });
+  const picker = await chooser;
+  if (!picker) throw new Error("clicking it opened no file picker");
+  await picker.setFiles(files[wanted ?? sampleFor(await picker.element().getAttribute("accept"))]);
+}
+
+export async function execute(
+  page: Page,
+  action: Action,
+  obs: Observation,
+  origin: string,
+  // Links the agent received by email (e.g. a magic link to the auth server) may leave the app's origin.
+  allowUrl: (href: string) => boolean = () => false,
+  opts: ExecuteOptions = {},
+): Promise<ActionResult> {
+  const result: ActionResult = {};
+  try {
+    switch (action.type) {
+      case "click":
+      case "fill": {
+        const el = obs.elements.find((e) => e.id === action.id);
+        if (!el) return { error: `no element with id ${action.id}` };
+        const customDropdown = el.tag !== "select" && el.role === "combobox" && el.tag !== "input" && el.tag !== "textarea";
+        if (action.type === "click" || customDropdown) refuseDestructiveControl(el);
+        const locator = page.locator(`[data-debutly-id="${action.id}"]`);
+        const byKeyboard = opts.keyboard && !ARROW_KEY_ITEMS.has(el.role);
+        if (byKeyboard) result.focusObscured = await focusByKeyboard(page, locator, action.id);
+        if (action.type === "click" && byKeyboard) {
+          if (SPACE_KEY.has(el.role)) await page.keyboard.press("Space");
+          else if (BUTTON_ROLE.test(el.role)) {
+            if (await pressEnterThenSpace(page, action.id)) result.enterIgnored = true;
+          } else if (!FOCUS_ONLY.test(el.role)) await page.keyboard.press("Enter");
+        } else if (action.type === "click") {
+          try {
+            await locator.click({ timeout: 5_000 });
+          } catch (err) {
+            if (!describeFailure(err).startsWith(COVERED) || !(await clickVisiblePart(page, action.id))) throw err;
+          }
+        } else if (el.tag === "select") await choose(locator, action.text);
+        else if (customDropdown) await pick(page, locator, action.text);
+        else await locator.fill(action.text, { timeout: 5_000 });
+        break;
+      }
+      case "upload": {
+        const el = obs.elements.find((e) => e.id === action.id);
+        if (!el) return { error: `no element with id ${action.id}` };
+        if (el.role !== "input:file") refuseDestructiveControl(el);
+        const target = page.locator(`[data-debutly-id="${action.id}"]`);
+        // A drop zone or label a keyboard can't reach can't open the file picker for a keyboard user.
+        if (opts.keyboard && el.role !== "input:file") result.focusObscured = await focusByKeyboard(page, target, action.id);
+        await upload(page, target, el.role === "input:file", action.file);
+        break;
+      }
+      case "goto": {
+        const target = new URL(action.path, origin);
+        if (target.origin !== new URL(origin).origin && !allowUrl(target.href)) {
+          return { blocked: `off-origin navigation refused: ${target.href}` };
+        }
+        await page.goto(target.href);
+        break;
+      }
+      case "press":
+        for (const name of await namesAKeyWouldActivate(page, action.key, obs)) refuseDestructive(name);
+        await page.keyboard.press(action.key);
+        break;
+      case "wait":
+        // A few seconds more than the settle before every look (runSession) already gives.
+        await page.waitForTimeout(WAIT_MS);
+        break;
+      case "done":
+      case "check_email":
+        return {};
+    }
+    await page.waitForLoadState("domcontentloaded");
+    // Let async handlers (fetch after submit, deferred errors) surface their signals.
+    await page.waitForTimeout(300);
+    return result.focusObscured || result.enterIgnored ? result : {};
+  } catch (err) {
+    if (err instanceof Refused) return { blocked: err.message };
+    if (err instanceof NotByKeyboard || err instanceof Unusable) return { error: err.message };
+    const why = "id" in action ? await explainTimeout(page, action.id, err) : undefined;
+    return { error: why ?? describeFailure(err), ...(result.focusObscured ? { focusObscured: result.focusObscured } : {}) };
+  }
+}

package/src/browser/observe.ts

@@ -0,0 +1,62 @@
+import type { Page } from "playwright";
+import type { InteractiveElement, Observation } from "../types";
+import { accessibleNames } from "./ax";
+import { SCAN_SCRIPT } from "./scan-script";
+
+// The page's language, how much of its visible text is Arabic and the direction that Arabic is
+// laid out in, and whether it lets people zoom. The direction is measured where the Arabic is, as
+// an app may turn its own container right to left rather than <body>: one that did was reported
+// as showing Arabic left to right. A string, like SCAN_SCRIPT: tsx injects helpers into functions
+// the page lacks.
+const LANGUAGE_SCRIPT = `(() => {
+  const body = document.body;
+  const text = (body && body.innerText) || '';
+  const letters = (text.match(/\\p{L}/gu) || []).length;
+  const arabic = (text.match(/\\p{Script=Arabic}/gu) || []).length;
+  let dir = body ? getComputedStyle(body).direction : 'ltr';
+  if (arabic && body) {
+    let rtl = 0, ltr = 0;
+    const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT);
+    for (let node = walker.nextNode(), seen = 0; node && seen < 5000; node = walker.nextNode(), seen++) {
+      const count = (node.nodeValue.match(/\\p{Script=Arabic}/gu) || []).length;
+      if (!count || !node.parentElement) continue;
+      if (getComputedStyle(node.parentElement).direction === 'rtl') rtl += count;
+      else ltr += count;
+    }
+    if (rtl + ltr) dir = rtl >= ltr ? 'rtl' : 'ltr';
+  }
+  // Pinch-zoom, which people with low vision rely on on phones (WCAG 1.4.4 asks for 200%).
+  const meta = document.querySelector('meta[name="viewport"]');
+  const viewport = meta ? meta.getAttribute('content') || '' : '';
+  const setting = {};
+  for (const part of viewport.split(/[,;]/)) {
+    const [key, value] = part.split('=').map((s) => s.trim().toLowerCase());
+    if (key) setting[key] = value || '';
+  }
+  const noScaling = setting['user-scalable'] === 'no' || setting['user-scalable'] === '0';
+  const maxScale = parseFloat(setting['maximum-scale']);
+  return {
+    lang: document.documentElement.getAttribute('lang') || '',
+    dir,
+    arabicShare: letters ? Math.round((arabic / letters) * 100) / 100 : 0,
+    zoomBlocked: noScaling || maxScale < 2 ? viewport : '',
+  };
+})()`;
+
+export async function observe(page: Page): Promise<Observation> {
+  const elements = (await page.evaluate(SCAN_SCRIPT)) as InteractiveElement[];
+  const names = await accessibleNames(page);
+  if (names) for (const el of elements) {
+    const ax = names.get(el.id);
+    if (ax) el.ax = ax;
+  }
+  // Line by line, as it reads on screen, so what changed after an action can be told line by line.
+  const text = (await page.locator("body").innerText())
+    .split("\n")
+    .map((line) => line.replace(/\s+/g, " ").trim())
+    .filter(Boolean)
+    .join("\n")
+    .slice(0, 2000);
+  const language = (await page.evaluate(LANGUAGE_SCRIPT)) as Pick<Observation, "lang" | "dir" | "arabicShare" | "zoomBlocked">;
+  return { url: page.url(), title: await page.title(), elements, text, ...language };
+}

package/src/browser/reflow.ts

@@ -0,0 +1,73 @@
+import type { Page } from "playwright";
+import type { ReflowCheck } from "../types";
+
+// WCAG 1.4.10 Reflow: at 320 CSS pixels wide (a 1280-pixel screen zoomed to 400%) a page should
+// read without scrolling sideways. Each page the low-vision agent arrives on is measured where it
+// is: its window is narrowed to that width, measured and widened again before the agent looks.
+// Nothing is requested twice, so no link or form is ever replayed to measure it.
+
+export const REFLOW_WIDTH = 320;
+const MAX_PAGES = 12;
+/** Time for the page to lay itself out after each change of width. */
+const LAYOUT_MS = 300;
+
+// The page's sideways overflow, and the element reaching furthest right outside any scrolling
+// box. A string, like SCAN_SCRIPT: tsx injects helpers into functions the page lacks.
+const MEASURE_SCRIPT = `(() => {
+  const doc = document.documentElement;
+  const view = doc.clientWidth;
+  const overflowPx = Math.max(doc.scrollWidth, document.body ? document.body.scrollWidth : 0) - view;
+  if (overflowPx <= 2) return { overflowPx: 0, widest: '', exception: '' };
+  const inScroller = (el) => {
+    for (let p = el.parentElement; p && p !== document.body && p !== doc; p = p.parentElement) {
+      const x = getComputedStyle(p).overflowX;
+      if (x !== 'visible') return true;
+    }
+    return false;
+  };
+  // Past the right edge, or on a right-to-left page past the left one. (A left-to-right page
+  // can't scroll left, so menus parked off its left edge don't count.)
+  const rtl = getComputedStyle(document.body).direction === 'rtl';
+  let widest = null, furthest = 2;
+  for (const el of document.body.querySelectorAll('*')) {
+    const r = el.getBoundingClientRect();
+    const out = rtl ? -r.left : r.right - view;
+    if (r.width > 0 && out > furthest && !inScroller(el)) { widest = el; furthest = out; }
+  }
+  // WCAG lets content that needs two dimensions scroll: data tables, maps, diagrams, video, code.
+  const twoD = widest && widest.closest('table, [role="grid"], [role="table"], pre, canvas, video, iframe, svg, map');
+  const name = (el) => {
+    const classes = typeof el.className === 'string' ? el.className.trim().split(/\\s+/).filter(Boolean).slice(0, 2) : [];
+    const text = (el.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 50);
+    return el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + classes.map((c) => '.' + c).join('') + (text ? ' ("' + text + '")' : '');
+  };
+  return {
+    overflowPx: Math.round(overflowPx),
+    widest: widest ? name(widest) + ', ' + Math.round(widest.getBoundingClientRect().width) + ' px wide' : '',
+    exception: twoD ? 'it is inside ' + (twoD.tagName === 'TABLE' || /grid|table/.test(twoD.getAttribute('role') || '') ? 'a data table' : 'a ' + twoD.tagName.toLowerCase()) + ', which may scroll' : '',
+  };
+})()`;
+
+export class ReflowMeter {
+  private readonly seen = new Set<string>();
+  readonly checks: ReflowCheck[] = [];
+
+  /** Measures the page the agent is on, the first time it arrives at each address. */
+  async measure(page: Page): Promise<void> {
+    const url = page.url().split("#")[0];
+    const size = page.viewportSize();
+    if (!size || !/^https?:/.test(url) || this.seen.has(url) || this.seen.size >= MAX_PAGES) return;
+    this.seen.add(url);
+    try {
+      await page.setViewportSize({ width: REFLOW_WIDTH, height: size.height });
+      await page.waitForTimeout(LAYOUT_MS);
+      const measured = (await page.evaluate(MEASURE_SCRIPT)) as Omit<ReflowCheck, "url" | "widthPx">;
+      this.checks.push({ url, widthPx: REFLOW_WIDTH, ...measured });
+    } catch {
+      // The page changed under the measurement: this one goes without it.
+    } finally {
+      await page.setViewportSize(size).catch(() => {});
+      await page.waitForTimeout(LAYOUT_MS);
+    }
+  }
+}

package/src/browser/samples.ts

@@ -0,0 +1,119 @@
+// Files an agent can attach where an app asks for one: a photo (for a post, an avatar, a logo)
+// and a document (a CV, a brief). Made here rather than shipped, and made up: nothing real or
+// personal is ever uploaded. Written once per process to the system's temp folder.
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deflateSync } from "node:zlib";
+
+export type SampleKind = "photo" | "document";
+
+/** A square photo, large enough for social posts that refuse small images (1080 px). */
+const PHOTO_PX = 1080;
+
+let written: Promise<Record<SampleKind, string>> | undefined;
+
+/** Paths to the sample files, written on first use. */
+export function sampleFiles(): Promise<Record<SampleKind, string>> {
+  written ??= (async () => {
+    const dir = join(tmpdir(), "debutly-samples");
+    await mkdir(dir, { recursive: true });
+    const photo = join(dir, "sample-photo.png");
+    const document = join(dir, "sample-cv.pdf");
+    await writeFile(photo, png(PHOTO_PX, PHOTO_PX));
+    await writeFile(document, pdf(SAMPLE_CV));
+    return { photo, document };
+  })();
+  return written;
+}
+
+/** Which sample an upload field wants, from its `accept` attribute; a photo when it doesn't say. */
+export function sampleFor(accept: string | null | undefined): SampleKind {
+  const a = (accept ?? "").toLowerCase();
+  if (!a || /image|\.png|\.jpe?g|\.gif|\.webp/.test(a)) return "photo";
+  if (/pdf|word|document|text|\.docx?|\.txt|\.rtf/.test(a)) return "document";
+  return "photo";
+}
+
+const SAMPLE_CV = [
+  "Alex Sample - Curriculum Vitae",
+  "alex.sample@example.com - London, UK",
+  "",
+  "Experience",
+  "Marketing Coordinator, Example Ltd (2022 - present)",
+  "- Ran weekly social campaigns and reported on their results",
+  "Marketing Assistant, Sample & Co (2020 - 2022)",
+  "- Wrote newsletters and kept the company blog up to date",
+  "",
+  "Education",
+  "BA Business Studies, Example University (2017 - 2020)",
+  "",
+  "Skills",
+  "Copywriting, Social media, Google Analytics, Canva, Excel",
+];
+
+// A gradient, so image checks that refuse blank pictures accept it.
+function png(width: number, height: number): Buffer {
+  const rows: Buffer[] = [];
+  for (let y = 0; y < height; y++) {
+    const row = Buffer.alloc(1 + width * 3);
+    for (let x = 0; x < width; x++) {
+      row[1 + x * 3] = Math.round((x / width) * 200) + 30;
+      row[2 + x * 3] = Math.round((y / height) * 160) + 60;
+      row[3 + x * 3] = 170;
+    }
+    rows.push(row);
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header.set([8, 2, 0, 0, 0], 8); // 8-bit RGB
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", header),
+    chunk("IDAT", deflateSync(Buffer.concat(rows))),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+function chunk(type: string, data: Buffer): Buffer {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([length, body, crc]);
+}
+
+function crc32(bytes: Buffer): number {
+  let c = ~0;
+  for (const b of bytes) {
+    c ^= b;
+    for (let k = 0; k < 8; k++) c = c & 1 ? (c >>> 1) ^ 0xedb88320 : c >>> 1;
+  }
+  return ~c >>> 0;
+}
+
+// A one-page PDF with real text, so apps that read a CV's text find some.
+function pdf(lines: string[]): Buffer {
+  const escape = (s: string) => s.replace(/[\\()]/g, (m) => `\\${m}`);
+  const text = ["BT", "/F1 12 Tf", "16 TL", "56 780 Td", ...lines.map((l) => `(${escape(l)}) '`), "ET"].join("\n");
+  const objects = [
+    "<< /Type /Catalog /Pages 2 0 R >>",
+    "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+    "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595 842] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>",
+    `<< /Length ${Buffer.byteLength(text)} >>\nstream\n${text}\nendstream`,
+    "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+  ];
+  let out = "%PDF-1.4\n";
+  const offsets: number[] = [];
+  objects.forEach((body, i) => {
+    offsets.push(Buffer.byteLength(out));
+    out += `${i + 1} 0 obj\n${body}\nendobj\n`;
+  });
+  const xref = Buffer.byteLength(out);
+  out += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`;
+  out += offsets.map((o) => `${String(o).padStart(10, "0")} 00000 n \n`).join("");
+  out += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`;
+  return Buffer.from(out, "latin1");
+}