@specific.dev/spectest 0.66.0 → 0.68.0

package/dist/locator-hints.js

@@ -0,0 +1,403 @@
+// "Did you mean…" for a locator that matched nothing.
+//
+// `locator-errors.ts` turns a playwright timeout into one sentence about the
+// element. This module answers the next question, which that sentence cannot:
+// *what IS on the page?* A locator that matches nothing usually misses by a
+// little — the accessible name carries a suffix, an `aria-label` overrides the
+// visible text, the control is a `combobox` and not the `button` it looks
+// like — and every one of those costs a full edit/run round trip to discover.
+//
+// Two sources, both authoritative, neither guessed at:
+//
+//   * **The ARIA snapshot** (`page.ariaSnapshot()`) — playwright's own
+//     accessibility tree, so the accessible names here are exactly the ones
+//     `getByRole(role, { name })` matches against. We never compute an
+//     accessible name ourselves.
+//   * **One DOM pass** for the facts the snapshot drops: visible text of leaf
+//     elements, test ids, placeholders, labels, and — the case that prompted
+//     this — every interactive element whose visible text and name-giving
+//     attribute disagree.
+//
+// Nothing is printed on trust. Each candidate carries the locator that would
+// select it, and `nearMissHints` runs that locator before the line reaches the
+// author: a suggestion that resolves to nothing is dropped rather than sent
+// out to be tried. The whole pass runs only on the failure path, inside a
+// budget, and any error in it is swallowed — a diagnostic must never replace
+// the failure it is explaining.
+import { escapeInvisible, normalizeWhiteSpace } from "./text-match.js";
+export const EMPTY_DOM_FACTS = {
+    texts: [],
+    testIds: [],
+    placeholders: [],
+    labels: [],
+    titles: [],
+    alts: [],
+    mismatches: [],
+};
+// ── Similarity ────────────────────────────────────────────────────────────
+/** Levenshtein distance, with an early exit once `max` is passed. */
+function distance(a, b, max) {
+    if (Math.abs(a.length - b.length) > max)
+        return max + 1;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        let best = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const v = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+            cur.push(v);
+            if (v < best)
+                best = v;
+        }
+        if (best > max)
+            return max + 1;
+        prev = cur;
+    }
+    return prev[b.length];
+}
+function key(s) {
+    return normalizeWhiteSpace(s).toLowerCase();
+}
+/**
+ * How close `candidate` is to what the author asked for, from 0 (unrelated)
+ * to 4 (the same string). Everything at or above `NEAR` is worth showing.
+ */
+export function closeness(query, candidate) {
+    const q = key(query);
+    const c = key(candidate);
+    if (!q || !c)
+        return 0;
+    if (q === c)
+        return 4;
+    // A name that carries a suffix or a prefix ("Spara" vs "Spara ändringar")
+    // is the single most common near miss, and `{ exact: false }` or a
+    // substring query would already have matched it.
+    if (c.includes(q) || q.includes(c))
+        return 3;
+    const max = Math.max(2, Math.floor(Math.max(q.length, c.length) * 0.34));
+    const d = distance(q, c, max);
+    if (d > max)
+        return 0;
+    return 2 - d / (max + 1);
+}
+/** The score at which a candidate is close enough to show. */
+const NEAR = 1;
+/** How many lines an author can absorb below a failure. */
+const MAX_SUGGESTIONS = 3;
+// ── Ranking ───────────────────────────────────────────────────────────────
+/** A page string, quoted for reading — with its invisible characters spelled
+ *  out. A suggestion whose only difference from what the author typed is a
+ *  no-break space would otherwise print as the very string that just failed. */
+function quoted(s) {
+    return escapeInvisible(JSON.stringify(s));
+}
+function code(loc) {
+    switch (loc.m) {
+        case "getByRole":
+            return `getByRole(${quoted(loc.role)}, { name: ${quoted(loc.name)} })`;
+        case "getByTestId":
+            return `getByTestId(${quoted(loc.id)})`;
+        default:
+            return `${loc.m}(${quoted(loc.text)})`;
+    }
+}
+/** Render one verified suggestion as the line the author reads. */
+export function suggestionLine(s, matches) {
+    const extra = matches > 1 ? ` (matches ${matches} elements)` : "";
+    return `  - ${s.fact} → ${code(s.locator)}${extra}`;
+}
+function byScore(a, b) {
+    return b.score - a.score;
+}
+/** Drop repeats of the same proposed locator, keeping the best-scoring one. */
+function dedupe(items) {
+    const seen = new Map();
+    for (const s of items.slice().sort(byScore)) {
+        const k = code(s.locator);
+        if (!seen.has(k))
+            seen.set(k, s);
+    }
+    return [...seen.values()];
+}
+function fromValues(query, values, make, fact) {
+    const out = [];
+    for (const v of values) {
+        const score = closeness(query, v);
+        if (score >= NEAR)
+            out.push({ fact: fact(v), locator: make(v), score });
+    }
+    return out;
+}
+/**
+ * Rank what the page holds against what the author asked for. Pure: the
+ * caller collects `aria`/`dom` and verifies the winners.
+ */
+export function buildSuggestions(target, aria, dom) {
+    const q = target.query;
+    if (!q)
+        return [];
+    const out = [];
+    if (target.kind === "role") {
+        const role = target.role ?? "";
+        for (const c of aria) {
+            const score = closeness(q, c.name);
+            if (score < NEAR)
+                continue;
+            if (c.role === role) {
+                // Same role, near name: the everyday miss.
+                out.push({
+                    fact: `${c.role} ${quoted(c.name)}`,
+                    locator: { m: "getByRole", role: c.role, name: c.name },
+                    score: score + 1,
+                });
+            }
+            else {
+                // The name is right and the role is not — a `combobox` styled as a
+                // button, a `link` that looks like one. Worth saying out loud,
+                // because the author's own reading of the page is what is wrong.
+                out.push({
+                    fact: `${c.role} ${quoted(c.name)} — this is a ${c.role}, not a ${role}`,
+                    locator: { m: "getByRole", role: c.role, name: c.name },
+                    score,
+                });
+            }
+        }
+        // An element whose visible text is what the author typed, but whose
+        // accessible name — the thing `getByRole` matches — is something else.
+        for (const m of dom.mismatches) {
+            const score = closeness(q, m.text);
+            if (score < NEAR)
+                continue;
+            out.push({
+                fact: `<${m.tag}> shows ${quoted(m.text)} but its accessible name is ${quoted(m.name)} (from ${m.from})`,
+                locator: { m: "getByRole", role: role || "button", name: m.name },
+                score: score + 0.5,
+            });
+        }
+    }
+    if (target.kind === "text") {
+        out.push(...fromValues(q, dom.texts, (v) => ({ m: "getByText", text: v }), (v) => `text ${quoted(v)}`));
+        for (const c of aria) {
+            const score = closeness(q, c.name);
+            if (score >= NEAR) {
+                out.push({
+                    fact: `${c.role} ${quoted(c.name)}`,
+                    locator: { m: "getByRole", role: c.role, name: c.name },
+                    score,
+                });
+            }
+        }
+    }
+    if (target.kind === "testId") {
+        out.push(...fromValues(q, dom.testIds, (v) => ({ m: "getByTestId", id: v }), (v) => `testid ${quoted(v)}`));
+    }
+    if (target.kind === "label") {
+        out.push(...fromValues(q, dom.labels, (v) => ({ m: "getByLabel", text: v }), (v) => `label ${quoted(v)}`));
+    }
+    if (target.kind === "placeholder") {
+        out.push(...fromValues(q, dom.placeholders, (v) => ({ m: "getByPlaceholder", text: v }), (v) => `placeholder ${quoted(v)}`));
+    }
+    if (target.kind === "title") {
+        out.push(...fromValues(q, dom.titles, (v) => ({ m: "getByTitle", text: v }), (v) => `title ${quoted(v)}`));
+    }
+    if (target.kind === "altText") {
+        out.push(...fromValues(q, dom.alts, (v) => ({ m: "getByAltText", text: v }), (v) => `alt ${quoted(v)}`));
+    }
+    return dedupe(out).sort(byScore).slice(0, MAX_SUGGESTIONS);
+}
+// ── Page-side collection ──────────────────────────────────────────────────
+/**
+ * Pull `- button "Save"` lines out of an ARIA snapshot.
+ *
+ * The snapshot is YAML, but only its leading token carries what we need, so
+ * this reads it line by line rather than pulling in a parser. A line we do not
+ * recognise is skipped — the worst case is one fewer suggestion.
+ */
+export function parseAriaSnapshot(yaml) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of yaml.split("\n")) {
+        // `- role "name" [level=1]:` — the role is a bare word, the name a
+        // double-quoted string, and both the name and the trailing parts are
+        // optional. A quoted name may contain escaped quotes.
+        const m = /^\s*-\s+([a-zA-Z]+)(?:\s+"((?:[^"\\]|\\.)*)")?/.exec(raw);
+        if (!m)
+            continue;
+        const role = m[1];
+        if (m[2] === undefined)
+            continue; // No accessible name: nothing to match.
+        const name = m[2].replace(/\\(.)/g, "$1");
+        const k = `${role} "${name}"`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push({ role, name });
+        if (out.length >= 400)
+            break;
+    }
+    return out;
+}
+/**
+ * Read the page facts the ARIA snapshot does not carry.
+ *
+ * Runs in the browser, so it must stay self-contained (no closure over
+ * anything here) and cheap: it walks a bounded number of elements and caps
+ * every list it fills.
+ */
+/* c8 ignore start — executes in the browser, not under bun test */
+function domFactsScript() {
+    const MAX_ELEMENTS = 4000;
+    const MAX_ITEMS = 200;
+    const norm = (s) => (s ?? "").replace(/[\u200b\u00ad]/g, "").trim().replace(/\s+/g, " ").slice(0, 120);
+    const push = (arr, v) => {
+        if (v && arr.length < MAX_ITEMS && !arr.includes(v))
+            arr.push(v);
+    };
+    const out = {
+        texts: [],
+        testIds: [],
+        placeholders: [],
+        labels: [],
+        titles: [],
+        alts: [],
+        mismatches: [],
+    };
+    const visible = (el) => {
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0)
+            return false;
+        const st = getComputedStyle(el);
+        return st.visibility !== "hidden" && st.display !== "none";
+    };
+    const INTERACTIVE = "a,button,summary,select,textarea,input,[role],[onclick],[tabindex]";
+    let n = 0;
+    for (const el of Array.from(document.querySelectorAll("*"))) {
+        if (++n > MAX_ELEMENTS)
+            break;
+        const tag = el.tagName.toLowerCase();
+        if (tag === "script" || tag === "style" || tag === "head")
+            continue;
+        push(out.testIds, norm(el.getAttribute("data-testid")));
+        push(out.placeholders, norm(el.getAttribute("placeholder")));
+        push(out.titles, norm(el.getAttribute("title")));
+        push(out.alts, norm(el.getAttribute("alt")));
+        const ariaLabel = norm(el.getAttribute("aria-label"));
+        push(out.labels, ariaLabel);
+        if (tag === "label")
+            push(out.labels, norm(el.innerText));
+        if (el.children.length === 0 && visible(el)) {
+            push(out.texts, norm(el.innerText || el.textContent));
+        }
+        if (!el.matches(INTERACTIVE) || !visible(el))
+            continue;
+        const text = norm(el.innerText || el.textContent);
+        let name = ariaLabel;
+        let from = "aria-label";
+        if (!name) {
+            const ids = (el.getAttribute("aria-labelledby") ?? "").split(/\s+/).filter(Boolean);
+            const parts = [];
+            for (const id of ids) {
+                const ref = document.getElementById(id);
+                if (ref)
+                    parts.push(norm(ref.innerText || ref.textContent));
+            }
+            if (parts.length) {
+                name = norm(parts.join(" "));
+                from = "aria-labelledby";
+            }
+        }
+        if (!name && el.getAttribute("title")) {
+            name = norm(el.getAttribute("title"));
+            from = "title";
+        }
+        if (!name && tag === "input" && el.getAttribute("value")) {
+            name = norm(el.getAttribute("value"));
+            from = "value";
+        }
+        if (name && text && name !== text && out.mismatches.length < 50) {
+            out.mismatches.push({ tag, text, name, from });
+        }
+    }
+    return out;
+}
+/* c8 ignore stop */
+/** Build the playwright locator a suggestion proposes, for verification. */
+function resolve(page, loc) {
+    switch (loc.m) {
+        case "getByRole":
+            return page.getByRole(loc.role, {
+                name: loc.name,
+                exact: true,
+            });
+        case "getByTestId":
+            return page.getByTestId(loc.id);
+        case "getByText":
+            return page.getByText(loc.text, { exact: true });
+        case "getByLabel":
+            return page.getByLabel(loc.text, { exact: true });
+        case "getByPlaceholder":
+            return page.getByPlaceholder(loc.text, { exact: true });
+        case "getByAltText":
+            return page.getByAltText(loc.text, { exact: true });
+        case "getByTitle":
+            return page.getByTitle(loc.text, { exact: true });
+    }
+}
+/** How long the whole diagnostic may take. It runs after a failure that has
+ *  already waited seconds, so a short budget costs nothing and a hung page
+ *  cannot make a failing test hang. */
+const HINT_BUDGET_MS = 2_000;
+async function withBudget(work, fallback) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(fallback), HINT_BUDGET_MS);
+            }),
+        ]);
+    }
+    catch {
+        return fallback;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * The lines to append to a "no element matches" failure — at most
+ * {@link MAX_SUGGESTIONS}, each verified against the live page, and empty
+ * whenever the page holds nothing close.
+ */
+export async function nearMissHints(page, target) {
+    if (!target.query)
+        return [];
+    const collected = await withBudget((async () => {
+        const [snapshot, dom] = await Promise.all([
+            page.ariaSnapshot().catch(() => ""),
+            page.evaluate(domFactsScript).catch(() => EMPTY_DOM_FACTS),
+        ]);
+        return { aria: parseAriaSnapshot(snapshot), dom };
+    })(), { aria: [], dom: EMPTY_DOM_FACTS });
+    const suggestions = buildSuggestions(target, collected.aria, collected.dom);
+    if (!suggestions.length)
+        return [];
+    // Verify before printing. A suggestion nobody can use is worse than none:
+    // it sends the author to try a locator we invented.
+    const lines = await withBudget(Promise.all(suggestions.map(async (s) => {
+        const matches = await resolve(page, s.locator)
+            .count()
+            .catch(() => 0);
+        return matches > 0 ? suggestionLine(s, matches) : undefined;
+    })), []);
+    return lines.filter((l) => l !== undefined);
+}
+/** The block appended under a failure sentence, or `""` when there is
+ *  nothing to add. */
+export function formatHints(lines) {
+    if (!lines.length)
+        return "";
+    return `\nClose matches on the page:\n${lines.join("\n")}`;
+}

package/dist/locator.d.ts

@@ -1,6 +1,7 @@
 import type { Page, Locator as PWLocator } from "playwright-core";
 import type { RecordableFields } from "./browser.js";
 import type { Wrapped } from "./inspect.js";
+import { type HintTarget } from "./locator-hints.js";
 /** Default deadline for a locator action/read's target to become actionable.
  *  Playwright's own default is 30s — far too slow-failing for tests; 5s
  *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
@@ -115,6 +116,18 @@ export declare function isLocator(x: unknown): x is Locator;
  *  Nested spectest locators (`filter({has})`, `and`, `or`) are lowered
  *  recursively against the same page. */
 export declare function lower(page: Page, chain: Chain): PWLocator;
+/**
+ * What a chain asked for, in the terms the near-miss diagnostic reasons in
+ * (see locator-hints.ts). `undefined` when this chain must not produce
+ * suggestions.
+ *
+ * **Single-step chains only, deliberately.** A suggestion is verified against
+ * the whole page, so for a scoped chain (`locator("#form").getByRole(…)`) a
+ * page-wide match could resolve outside the scope — a suggestion that does not
+ * work where the author is looking is worse than no suggestion. A RegExp query
+ * is skipped for the same reason: a pattern has no near miss to speak of.
+ */
+export declare function hintTargetFromChain(chain: Chain): HintTarget | undefined;
 /** Short human label for a chain, e.g.
  *  `role button "15" ‹ filter(has: text "July 2026") ‹ css .calendar`.
  *  Root first; narrowing steps appended in reading order. */
@@ -143,8 +156,17 @@ export interface LocatorProbe {
     readonly label: string;
     isVisible(): Promise<boolean>;
     textContent(timeout?: number): Promise<string | null>;
+    innerText(timeout?: number): Promise<string>;
+    /** Every match's text — the array forms of `toHaveText`/`toContainText`,
+     *  which are about a list of elements and so must not go through the
+     *  single-element (strict) reads above. */
+    allTextContents(): Promise<string[]>;
+    allInnerTexts(): Promise<string[]>;
     inputValue(timeout?: number): Promise<string>;
     count(): Promise<number>;
+    /** The "did you mean…" block for a locator that matched nothing, or `""`.
+     *  See locator-hints.ts. */
+    nearMiss(): Promise<string>;
     isEnabled(timeout?: number): Promise<boolean>;
     isChecked(timeout?: number): Promise<boolean>;
     /** After the silent poll settles, emit the single settled browser step this

package/dist/locator.js

@@ -22,7 +22,8 @@
 // author-facing call is exactly one recorded browser event (with its rrweb
 // drain), whatever playwright work it composes underneath.
 import { Buffer } from "node:buffer";
-import { rewriteLocatorError } from "./locator-errors.js";
+import { rewriteLocatorErrorWithHints } from "./locator-errors.js";
+import { formatHints, nearMissHints } from "./locator-hints.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 /** Default deadline for a locator action/read's target to become actionable.
@@ -149,6 +150,45 @@ function stepLabel(step) {
             return `.nth(${step.args[0]})`;
     }
 }
+/**
+ * What a chain asked for, in the terms the near-miss diagnostic reasons in
+ * (see locator-hints.ts). `undefined` when this chain must not produce
+ * suggestions.
+ *
+ * **Single-step chains only, deliberately.** A suggestion is verified against
+ * the whole page, so for a scoped chain (`locator("#form").getByRole(…)`) a
+ * page-wide match could resolve outside the scope — a suggestion that does not
+ * work where the author is looking is worse than no suggestion. A RegExp query
+ * is skipped for the same reason: a pattern has no near miss to speak of.
+ */
+export function hintTargetFromChain(chain) {
+    if (chain.steps.length !== 1)
+        return undefined;
+    const step = chain.steps[0];
+    const textQuery = (v) => typeof v === "string" ? v : undefined;
+    switch (step.m) {
+        case "getByRole": {
+            const name = step.args[1]?.name;
+            if (name === undefined)
+                return undefined; // Only a role: nothing to be near.
+            return { kind: "role", role: step.args[0], query: textQuery(name) };
+        }
+        case "getByText":
+            return { kind: "text", query: textQuery(step.args[0]) };
+        case "getByLabel":
+            return { kind: "label", query: textQuery(step.args[0]) };
+        case "getByPlaceholder":
+            return { kind: "placeholder", query: textQuery(step.args[0]) };
+        case "getByAltText":
+            return { kind: "altText", query: textQuery(step.args[0]) };
+        case "getByTitle":
+            return { kind: "title", query: textQuery(step.args[0]) };
+        case "getByTestId":
+            return { kind: "testId", query: step.args[0] };
+        default:
+            return undefined;
+    }
+}
 /** Short human label for a chain, e.g.
  *  `role button "15" ‹ filter(has: text "July 2026") ‹ css .calendar`.
  *  Root first; narrowing steps appended in reading order. */
@@ -351,38 +391,52 @@ function lowerInputFiles(files) {
 export function makeLocator(backend, strategy, chain) {
     const label = chainLabel(chain);
     const extend = (step) => makeLocator(backend, strategy, { steps: [...chain.steps, step] });
+    /** The "did you mean…" block for a locator that matched nothing. Empty
+     *  for a chain that must not suggest (see {@link hintTargetFromChain}) and
+     *  for a page that holds nothing close. */
+    const hintBlock = async (page) => {
+        const target = hintTargetFromChain(chain);
+        if (!target)
+            return "";
+        return formatHints(await nearMissHints(page, target));
+    };
     // Every terminal op runs through this: playwright's actionability timeouts
     // say "Timeout 5000ms exceeded" and hide what actually went wrong in a call
     // log, so they are rewritten into a sentence naming the element and its
-    // state (see locator-errors.ts). Applied INSIDE `pageOp`, so the recorded
-    // step carries the readable message too — not just the thrown error.
-    const readable = async (fn) => {
+    // state (see locator-errors.ts), and a failure that found NO element asks
+    // the page what it does hold. Applied INSIDE `pageOp`, so the recorded step
+    // carries the readable message too — not just the thrown error.
+    const readable = async (page, fn) => {
         try {
             return await fn();
         }
         catch (err) {
-            throw rewriteLocatorError(err, label);
+            throw await rewriteLocatorErrorWithHints(err, label, () => hintBlock(page));
         }
     };
     // One recorded event, result NOT wrapped (void/action).
-    const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(() => fn(lower(page, chain), page)));
+    const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(page, () => fn(lower(page, chain), page)));
     // One recorded event whose fields the action itself finishes filling in:
     // `rec` is the very object the recorder spreads once `fn` resolves (the
     // same mutate-in-flight seam `screenshot`'s artifact id rides), so the
     // click family can stamp the point it acted on. See stampActionPoint.
     const actAt = (action, fn) => {
         const rec = { selector: label };
-        return backend.pageOp(action, rec, (page) => readable(() => fn(lower(page, chain), rec)));
+        return backend.pageOp(action, rec, (page) => readable(page, () => fn(lower(page, chain), rec)));
     };
     // One recorded event, result provenance-wrapped for expect().
-    const read = (action, fn, fields = {}) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(() => fn(lower(page, chain))), { wrap: true });
+    const read = (action, fn, fields = {}) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(page, () => fn(lower(page, chain))), { wrap: true });
     // Silent, non-recorded reads for expect(locator) matchers to poll.
     const probe = {
         label,
         isVisible: () => backend.silentRead((page) => lower(page, chain).isVisible()),
         textContent: (timeout) => backend.silentRead((page) => lower(page, chain).textContent({ timeout })),
+        innerText: (timeout) => backend.silentRead((page) => lower(page, chain).innerText({ timeout })),
+        allTextContents: () => backend.silentRead((page) => lower(page, chain).allTextContents()),
+        allInnerTexts: () => backend.silentRead((page) => lower(page, chain).allInnerTexts()),
         inputValue: (timeout) => backend.silentRead((page) => lower(page, chain).inputValue({ timeout })),
         count: () => backend.silentRead((page) => lower(page, chain).count()),
+        nearMiss: () => backend.silentRead((page) => hintBlock(page)),
         isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
         isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
         settle: async (action, waitedMs, error, opts) => {
@@ -471,7 +525,7 @@ export function makeLocator(backend, strategy, chain) {
                 out.push(extend({ m: "nth", args: [i] }));
             return out;
         },
-        evaluate: (description, fn, arg) => backend.pageOp("evaluate", { selector: label, description }, (page) => readable(() => lower(page, chain).evaluate(fn, arg)), { wrap: true }),
+        evaluate: (description, fn, arg) => backend.pageOp("evaluate", { selector: label, description }, (page) => readable(page, () => lower(page, chain).evaluate(fn, arg)), { wrap: true }),
         waitFor: (opts) => act("waitFor", {}, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
     };
     // Attach the silent-read probe under its symbol (kept off the typed literal

package/dist/page-snapshot.d.ts

@@ -0,0 +1,42 @@
+import type { Page } from "playwright-core";
+/** One child frame's tree. The main frame's tree leads the document. */
+export interface FrameStructure {
+    /** The frame's `name` attribute, or `""` when it has none. */
+    name: string;
+    url: string;
+    tree: string;
+}
+/** Everything the document is rendered from. Split out from the capture so the
+ *  formatting is testable without a browser. */
+export interface PageStructure {
+    /** The session's name — `ctx.browser("alice")` — or `""` for the default. */
+    session: string;
+    kind: "browser" | "mobile";
+    /** The step that failed (`click`, `goto`, `toBeVisible`, …). */
+    action: string;
+    /** Its failure message; only the first line is kept. */
+    error: string;
+    url: string;
+    title: string;
+    tree: string;
+    frames: FrameStructure[];
+}
+/** The document is a debugging aid, and a pathological page must not grow the
+ *  `/run` reply (the vm-agent caps a proxied daemon response at 16 MB). Real
+ *  pages are far below this: the biggest thing measured while building it was
+ *  38 KB. */
+export declare const MAX_DOCUMENT_BYTES: number;
+/**
+ * Capture the page behind a failed step, or `undefined` when there is nothing
+ * to show.
+ *
+ * Everything here is best-effort: a page that is closed, navigating or wedged
+ * yields a partial record rather than an error, because the caller is already
+ * reporting a failure and must not report this one instead.
+ */
+export declare function capturePageStructure(page: Page, meta: Pick<PageStructure, "session" | "kind" | "action" | "error">): Promise<string | undefined>;
+/** Render the document. Pure, so its shape is testable without a browser. */
+export declare function formatPageStructure(s: PageStructure): string;
+/** Cut the document to {@link MAX_DOCUMENT_BYTES}, on a line boundary, and say
+ *  so — a silently short tree reads as a page that ends there. */
+export declare function truncate(doc: string): string;