browxai 0.7.0

package/dist/page/export-playwright-script.js

@@ -0,0 +1,304 @@
+// Trace-export: lower a session's recorded action trace into a runnable
+// `@playwright/test` spec file. Adjacent to `export_session_report` (which
+// bundles QA evidence) and to `end_recording` (which emits the site-docs
+// flow-file YAML); this one emits TypeScript a code-as-action consumer can
+// run as the seed for a skill-compilation loop.
+//
+// Lowering principles:
+//   - Each recorded step lowers to ONE Playwright call. We deliberately do not
+//     re-synthesise the wider browxai action envelope (ActionResult /
+//     snapshotDelta / network slice) — a `.spec.ts` is a single deterministic
+//     walk, not an observed session.
+//   - Locator strings reuse the recorded `selectorHint` (the BEST stable
+//     selector resolved at action time). Mirrors `parseSelectorHint` in
+//     `./locator.ts` so an exported call resolves the same way browxai itself
+//     would: attribute → `page.locator('[attr="..."]')`, role+name → `page
+//     .getByRole('role', { name: '...' })`, role-only → `page.getByRole('role')`,
+//     anything else → `page.locator('<raw>')`.
+//   - Selector stability is surfaced in-source. A recorded `stability: "low"`
+//     (or any step where the recorder had to fall back to tier-5 / role-only)
+//     gets a `// TODO: fragile selector — review before relying on this in
+//     CI` comment above the call, so the consumer SEES the brittle spots
+//     rather than having to cross-reference the YAML.
+//   - Coords-mode actions are not recorded by the action window (see
+//     actions.ts: NON_TARGETED_ACTIONS / hasReplayableTarget), so the export
+//     never has to lower a non-replayable target — by construction.
+//
+// Output shape: a single `.spec.ts` source string. The caller can return it
+// inline AND/OR write it to a workspace-rooted path (same posture as
+// `dump_storage_state` — workspace-rooted, escape-rejected).
+/** Lower a recorded trace to a Playwright spec source string. Pure; the
+ *  caller decides whether to write it to disk. */
+export function lowerTraceToSpec(flowName, steps) {
+    const body = [];
+    let handled = 0;
+    let unhandled = 0;
+    let fragile = 0;
+    if (steps.length === 0) {
+        body.push("    // No steps recorded. Run actions while a recording is active,");
+        body.push("    // then re-export to populate this spec.");
+    }
+    for (const step of steps) {
+        const lowered = lowerStep(step);
+        if (lowered.fragile) {
+            fragile += 1;
+            body.push("    // TODO: fragile selector — review before relying on this in CI " +
+                "(recorded stability: " +
+                (step.stability ?? "unknown") +
+                ").");
+        }
+        for (const line of lowered.lines) {
+            body.push("    " + line);
+        }
+        if (lowered.handled)
+            handled += 1;
+        else
+            unhandled += 1;
+    }
+    const source = renderSpec(flowName, body);
+    return {
+        source,
+        stats: { steps: steps.length, handled, unhandled, fragile },
+    };
+}
+/** Pure step lowering. Exported for the unit tests. */
+/** Navigation/history actions need no target. Returns null for non-nav types. */
+function lowerNavigation(a) {
+    switch (a.type) {
+        case "navigate":
+            return handledLines([`await page.goto(${jsString(a.url ?? "")});`]);
+        case "goBack":
+            return handledLines(["await page.goBack();"]);
+        case "goForward":
+            return handledLines(["await page.goForward();"]);
+        default:
+            return null;
+    }
+}
+export function lowerStep(step) {
+    const a = step.action;
+    const nav = lowerNavigation(a);
+    if (nav)
+        return nav;
+    switch (a.type) {
+        case "click":
+            return targeted(step, (loc) => [`await ${loc}.click();`]);
+        case "fill":
+            return targeted(step, (loc) => [`await ${loc}.fill(${jsString(a.value ?? "")});`]);
+        case "hover":
+            return targeted(step, (loc) => [`await ${loc}.hover();`]);
+        case "select":
+            return lowerSelect(step, a.value ?? "");
+        case "press":
+            return lowerPress(step, a.value ?? "");
+        case "waitFor":
+            return lowerWaitFor(step, a.value ?? "");
+        case "chooseOption":
+            return lowerChooseOption(step, a.value ?? "");
+        default:
+            // Unknown action type — emit a TODO placeholder so the spec still parses,
+            // and bump the `unhandled` counter so the caller sees the gap.
+            return {
+                lines: [
+                    `// TODO: unhandled action type "${a.type}" — no Playwright lowering wired. ` +
+                        `Original descriptor: ${JSON.stringify(a)}.`,
+                ],
+                fragile: false,
+                handled: false,
+            };
+    }
+}
+/** `select` records values as a comma-joined string; lower to `selectOption([...])`
+ *  (the array form is unambiguous and accepts a single value too). */
+function lowerSelect(step, value) {
+    const values = value
+        .split(",")
+        .map((v) => v.trim())
+        .filter((v) => v.length > 0);
+    const literal = "[" + values.map(jsString).join(", ") + "]";
+    return targeted(step, (loc) => [`await ${loc}.selectOption(${literal});`]);
+}
+/** `press` may target an element (`locator.press`) or the page (`page.keyboard.press`). */
+function lowerPress(step, key) {
+    if (step.selectorHint) {
+        return targeted(step, (loc) => [`await ${loc}.press(${jsString(key)});`]);
+    }
+    return handledLines([`await page.keyboard.press(${jsString(key)});`]);
+}
+/** `waitFor` lowers to a page-level visible-text wait (`text:<...>`) or an
+ *  element-visible wait. */
+function lowerWaitFor(step, value) {
+    if (value.startsWith("text:")) {
+        const text = value.slice("text:".length);
+        return handledLines([
+            `await page.getByText(${jsString(text)}).first().waitFor({ state: "visible" });`,
+        ]);
+    }
+    return targeted(step, (loc) => [`await ${loc}.waitFor({ state: "visible" });`]);
+}
+/** `choose_option` is a compound (open-trigger → click-option) emitted as two
+ *  clicks with a review-the-wait comment. */
+function lowerChooseOption(step, optionText) {
+    const loc = locatorExprFor(step);
+    return {
+        lines: [
+            "// choose_option lowered as trigger-click + option-click; review the wait between them.",
+            `await ${loc}.click();`,
+            `await page.getByRole("option", { name: ${jsString(optionText)} }).first().click();`,
+        ],
+        fragile: isFragile(step),
+        handled: true,
+    };
+}
+function targeted(step, build) {
+    if (!step.selectorHint) {
+        // The recorder only stores a step without a selectorHint for
+        // navigation-class actions, which are handled above. If we land here
+        // it's a target-shaped action whose target the recorder couldn't
+        // resolve (extremely unusual — guard anyway).
+        return {
+            lines: [
+                `// TODO: target action "${step.action.type}" has no recorded selectorHint — ` +
+                    `cannot lower to a Playwright locator; replace this line manually.`,
+            ],
+            fragile: true,
+            handled: false,
+        };
+    }
+    const loc = locatorExprFor(step);
+    return { lines: build(loc), fragile: isFragile(step), handled: true };
+}
+function handledLines(lines) {
+    return { lines, fragile: false, handled: true };
+}
+function isFragile(step) {
+    const s = step.stability;
+    return s === "low";
+}
+/** Lower a recorded `selectorHint` into a Playwright locator expression
+ *  rooted at the `page` identifier. Mirrors `parseSelectorHint` in
+ *  `./locator.ts`. */
+export function locatorExprFor(step) {
+    const hint = step.selectorHint ?? "";
+    return locatorExprFromHint(hint);
+}
+/** Pure; exported for unit tests. */
+export function locatorExprFromHint(hint) {
+    const s = hint.trim();
+    // Attribute form — `[data-testid="..."]` and the wider attribute family
+    // find() emits (`data-cy`, `data-test`, etc.). Pass the whole hint through
+    // as a CSS selector; Playwright's `.locator()` handles it natively.
+    const attrMatch = s.match(/^\[([a-zA-Z][a-zA-Z0-9-]*)=("([^"]*)"|'([^']*)')\]$/);
+    if (attrMatch) {
+        return `page.locator(${jsString(s)})`;
+    }
+    // Role + name form — `role=button[name="Submit"]`. Lower to `getByRole`
+    // with the unescaped name; same parse used by `parseSelectorHint`.
+    const roleNameMatch = s.match(/^role=([a-zA-Z][a-zA-Z0-9-]*)\[name=("((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)')\]$/);
+    if (roleNameMatch) {
+        const role = roleNameMatch[1];
+        const rawName = roleNameMatch[3] ?? roleNameMatch[4] ?? "";
+        const name = rawName.replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\\\\/g, "\\");
+        return `page.getByRole(${jsString(role)}, { name: ${jsString(name)} })`;
+    }
+    // Role-only — `role=button`. Tier-5 / low-stability shape.
+    const roleOnlyMatch = s.match(/^role=([a-zA-Z][a-zA-Z0-9-]*)$/);
+    if (roleOnlyMatch) {
+        return `page.getByRole(${jsString(roleOnlyMatch[1])})`;
+    }
+    // Fallthrough — raw locator string.
+    return `page.locator(${jsString(s)})`;
+}
+/** TypeScript double-quoted string literal. Escapes the JSON-unsafe subset
+ *  plus `$` and backticks (not needed for double quotes, but cheap to be
+ *  conservative — the output round-trips through `JSON.stringify` which
+ *  already handles `"` and `\`). */
+function jsString(value) {
+    return JSON.stringify(value);
+}
+/** Render the final `.spec.ts` source. Body lines are inserted verbatim
+ *  (already indented by the caller). */
+function renderSpec(flowName, bodyLines) {
+    const safeName = flowName.replace(/[\r\n]/g, " ").replace(/`/g, "\\`");
+    const lines = [
+        `import { test, expect } from "@playwright/test";`,
+        ``,
+        `// Generated by browxai \`export_playwright_script\`. Each step below was`,
+        `// lowered from a recorded browxai action; selectors come from the`,
+        `// recorder's selectorHint at the time of the call. \`// TODO: fragile`,
+        `// selector\` comments flag tier-5 / role-only fallbacks — review before`,
+        `// relying on this spec in CI.`,
+        `//`,
+        `// \`expect\` is imported so adding assertions does not require editing`,
+        `// the import line; the generated body does not assert by itself.`,
+        `void expect;`,
+        ``,
+        `test(${jsString(safeName)}, async ({ page }) => {`,
+        ...bodyLines,
+        `});`,
+        ``,
+    ];
+    return lines.join("\n");
+}
+/** Skip a comment or string token starting at `i`; returns the index just past
+ *  it, or `i` unchanged when `i` doesn't start a comment/string. */
+function skipCommentOrString(source, i) {
+    const c = source[i];
+    if (c === "/" && source[i + 1] === "/") {
+        const nl = source.indexOf("\n", i);
+        return nl === -1 ? source.length : nl + 1;
+    }
+    if (c === "/" && source[i + 1] === "*") {
+        const end = source.indexOf("*/", i + 2);
+        return end === -1 ? source.length : end + 2;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < source.length && source[j] !== c)
+            j += source[j] === "\\" ? 2 : 1;
+        return j + 1;
+    }
+    return i;
+}
+const OPEN_DELIMS = { "(": "paren", "{": "brace", "[": "bracket" };
+const CLOSE_DELIMS = { ")": "paren", "}": "brace", "]": "bracket" };
+/** Apply one character's delimiter effect to `depth`. */
+function applyDelimiter(c, depth) {
+    const open = OPEN_DELIMS[c];
+    if (open)
+        depth[open] += 1;
+    const close = CLOSE_DELIMS[c];
+    if (close)
+        depth[close] -= 1;
+}
+export function parseCheck(source) {
+    if (!source.startsWith('import { test, expect } from "@playwright/test";')) {
+        return { ok: false, reason: "missing @playwright/test import header" };
+    }
+    if (!/\ntest\(/.test(source)) {
+        return { ok: false, reason: "missing test(...) shell" };
+    }
+    // matched-delimiter pass — strings + comments are skipped so a `{` inside a
+    // string literal isn't a false positive.
+    let i = 0;
+    const depth = { paren: 0, brace: 0, bracket: 0 };
+    while (i < source.length) {
+        const skipped = skipCommentOrString(source, i);
+        if (skipped !== i) {
+            i = skipped;
+            continue;
+        }
+        applyDelimiter(source[i], depth);
+        if (depth.paren < 0 || depth.brace < 0 || depth.bracket < 0) {
+            return { ok: false, reason: `unbalanced delimiter at offset ${i}` };
+        }
+        i += 1;
+    }
+    if (depth.paren !== 0 || depth.brace !== 0 || depth.bracket !== 0) {
+        return {
+            ok: false,
+            reason: `unbalanced delimiters at EOF (paren=${depth.paren}, brace=${depth.brace}, bracket=${depth.bracket})`,
+        };
+    }
+    return { ok: true };
+}

package/dist/page/extract-resolve.d.ts

@@ -0,0 +1,22 @@
+import type { Locator, Page } from "playwright-core";
+import { type A11yNode } from "./a11y.js";
+import type { RefRegistry } from "./refs.js";
+import type { ExtractSchema, ExtractEvidence } from "./extract-types.js";
+/** Pure-ish resolution entry point. Exported for unit testing — `extract()`
+ *  composes the snapshot and resolves scope, then delegates here. */
+export declare function resolveAgainstTree(args: {
+    schema: ExtractSchema;
+    page: Page;
+    scopeTree: A11yNode;
+    scopeLocator?: Locator;
+}): Promise<{
+    data: unknown;
+    evidence: ExtractEvidence;
+    requiredMisses: string[];
+}>;
+export declare function scanTreeForBestMatch(tree: A11yNode, query: string): A11yNode | undefined;
+export declare function coerceLeaf(raw: unknown, type: ExtractSchema["type"]): unknown;
+/** Best-effort Locator for a ref — mirrors the lighter case in locator.ts
+ *  without hard-coupling here; we don't need full provenance routing for
+ *  extraction (the tree-walk does most of the work). */
+export declare function locatorForRef(page: Page, refs: RefRegistry, ref: string): Locator | undefined;

package/dist/page/extract-resolve.js

@@ -0,0 +1,341 @@
+// Deterministic extraction resolution engine — resolves an `ExtractSchema`
+// against a captured a11y subtree (+ optional backing Locators). Split out of
+// extract.ts to keep that file under the size budget; behavior-identical, and
+// the public entry points are re-exported through `./extract.js`.
+import { walk } from "./a11y.js";
+import { IMPLICIT_QUERY } from "./extract-types.js";
+import { warnExplicitNlQueryRetired } from "./extract-warnings.js";
+import { collectUnknownHintKeys } from "./extract-schema.js";
+/** Pure-ish resolution entry point. Exported for unit testing — `extract()`
+ *  composes the snapshot and resolves scope, then delegates here. */
+export async function resolveAgainstTree(args) {
+    const evidence = { refsUsed: [], selectorsUsed: [], partialMisses: [] };
+    const requiredMisses = [];
+    // Surface unknown `x-browx-source` keys up-front so the agent sees the
+    // typo before deciding whether the silently-wrong leaf value is "good
+    // enough". Pure additive diagnostic — does not change `ok` outcome.
+    collectUnknownHintKeys(args.schema, "", evidence.partialMisses);
+    const data = await resolveSchema({
+        schema: args.schema,
+        path: "",
+        page: args.page,
+        scopeTree: args.scopeTree,
+        scopeLocator: args.scopeLocator,
+        evidence,
+        requiredMisses,
+    });
+    return { data, evidence, requiredMisses };
+}
+async function resolveSchema(ctx) {
+    const { schema } = ctx;
+    switch (schema.type) {
+        case "object":
+            return resolveObject(ctx);
+        case "array":
+            return resolveArray(ctx);
+        case "string":
+        case "number":
+        case "boolean":
+            return resolveLeaf(ctx);
+    }
+}
+async function resolveObject(ctx) {
+    const out = {};
+    const props = ctx.schema.properties ?? {};
+    for (const [name, subSchema] of Object.entries(props)) {
+        const subPath = ctx.path ? `${ctx.path}.${name}` : name;
+        // implicit query = the property name; merged with explicit hint if any.
+        const childSchema = { ...subSchema };
+        if (!childSchema["x-browx-source"]?.query &&
+            !childSchema["x-browx-source"]?.selector &&
+            !childSchema["x-browx-source"]?.collection) {
+            const hint = { ...(childSchema["x-browx-source"] ?? {}), query: name };
+            // Mark the implicit-lowering case so resolveLeaf knows this query
+            // came from the property name (not a user-authored prose query) and
+            // skips the RETIRED-query warning. The marker is a module-private
+            // Symbol — won't leak into serialised schemas.
+            hint[IMPLICIT_QUERY] = true;
+            childSchema["x-browx-source"] = hint;
+        }
+        const value = await resolveSchema({
+            ...ctx,
+            schema: childSchema,
+            path: subPath,
+        });
+        if (value !== MISS) {
+            out[name] = value;
+        }
+        else if (subSchema.default !== undefined) {
+            out[name] = subSchema.default;
+        }
+    }
+    return out;
+}
+const MISS = Symbol.for("browxai.extract.miss");
+async function resolveArray(ctx) {
+    const hint = ctx.schema["x-browx-source"];
+    if (!hint?.collection) {
+        ctx.evidence.partialMisses.push(`${ctx.path}: array needs \`x-browx-source.collection\` ` +
+            `(a CSS selector or NL query for the row container; ` +
+            `each match becomes a per-row scope for \`items\`)`);
+        if (ctx.schema.required)
+            ctx.requiredMisses.push(ctx.path);
+        return [];
+    }
+    const items = ctx.schema.items;
+    // Try CSS selector first; if it doesn't match, fall back to a tree-scan
+    // by query (find()-style ranking restricted to repeated containers).
+    const collectionLocators = await resolveCollection(ctx.page, ctx.scopeLocator, ctx.scopeTree, hint.collection);
+    ctx.evidence.selectorsUsed.push(hint.collection);
+    if (collectionLocators.length === 0) {
+        ctx.evidence.partialMisses.push(`${ctx.path}: collection "${hint.collection}" matched 0 elements`);
+        if (ctx.schema.required)
+            ctx.requiredMisses.push(ctx.path);
+        return [];
+    }
+    const out = [];
+    for (let i = 0; i < collectionLocators.length; i++) {
+        const entry = collectionLocators[i];
+        const itemValue = await resolveSchema({
+            ...ctx,
+            schema: items,
+            path: `${ctx.path}[${i}]`,
+            scopeTree: entry.subTree ?? ctx.scopeTree,
+            scopeLocator: entry.loc,
+        });
+        if (itemValue !== MISS)
+            out.push(itemValue);
+    }
+    return out;
+}
+async function resolveCollection(page, scope, scopeTree, collection) {
+    // Try as a CSS selector first.
+    const root = scope ?? page;
+    try {
+        const loc = root.locator(collection);
+        const count = await loc.count();
+        if (count > 0) {
+            const out = [];
+            for (let i = 0; i < count; i++)
+                out.push({ loc: loc.nth(i) });
+            return out;
+        }
+    }
+    catch {
+        /* fall through to tree-scan */
+    }
+    // Fallback: tree-scan for nodes matching the query (containers in repeated
+    // structures pick up `context.collection`). No backing Locator — the
+    // sub-schema resolves over the subtree alone. Adopters needing
+    // attr/prop reads inside a list should use the CSS-selector form.
+    const matches = scanTreeForCollection(scopeTree, collection);
+    return matches.map((node) => ({ subTree: node }));
+}
+/** Shared a11y-tree search combinator (RFC 0004 P3 / D4). Folds `visit` over
+ *  every node `walk` yields, threading an accumulator — the one traversal both
+ *  `scanTreeForCollection` (accumulate all matches) and `scanTreeForBestMatch`
+ *  (score and keep the best) drive, instead of two hand-rolled `for … of walk`
+ *  loops. `walk` is already the shared depth-first generator; this names the fold
+ *  on top of it so a third tree query reuses the same shape. */
+function treeSearch(tree, initial, visit) {
+    let acc = initial;
+    for (const { node } of walk(tree))
+        acc = visit(acc, node);
+    return acc;
+}
+function scanTreeForCollection(tree, query) {
+    const lower = query.toLowerCase();
+    return treeSearch(tree, [], (out, node) => {
+        const hay = `${node.role}|${node.name ?? ""}|${node.testId ?? ""}`.toLowerCase();
+        if (hay.includes(lower))
+            out.push(node);
+        return out;
+    });
+}
+async function resolveLeaf(ctx) {
+    const hint = ctx.schema["x-browx-source"] ?? {};
+    // 1. selector path: resolve a Locator directly within scope.
+    if (hint.selector) {
+        ctx.evidence.selectorsUsed.push(hint.selector);
+        const root = ctx.scopeLocator ?? ctx.page;
+        let loc;
+        try {
+            loc = root.locator(hint.selector).first();
+        }
+        catch {
+            return missLeaf(ctx);
+        }
+        return readLeafFromLocator(ctx, loc, hint);
+    }
+    // 2. query path: tree-scan within scopeTree.
+    const query = hint.query ?? "";
+    // Collection-item leaf with no selector/query (e.g. `{text:true}` / `{attr}`):
+    // read directly from the per-item Locator that `resolveCollection` scoped onto
+    // this item, instead of treating "no selector" as a definitive miss. Without
+    // this, an array whose items are `{type:string, x-browx-source:{text:true}}`
+    // resolves every element to a partialMiss even though the collection matched.
+    if (!query && ctx.scopeLocator) {
+        return readLeafFromLocator(ctx, ctx.scopeLocator, hint);
+    }
+    if (!query)
+        return missLeaf(ctx);
+    // R-5 (v0.3.3): explicit per-field `query` is RETIRED. The implicit
+    // name-as-query lowering still flows through here (marked via
+    // IMPLICIT_QUERY) and works fine on testid-rich pages; the prose-style
+    // explicit query path is the unreliable one we're deprecating. Emit a
+    // one-shot warn + a per-call partialMisses entry that names the field,
+    // so the caller / authoring LLM gets a concrete signal — then fall
+    // through to the existing tree-scan resolution (graceful deprecation,
+    // never hard-break adopters).
+    const isImplicit = hint[IMPLICIT_QUERY] === true;
+    if (!isImplicit) {
+        warnExplicitNlQueryRetired();
+        ctx.evidence.partialMisses.push(`${ctx.path}: \`x-browx-source.query\` is RETIRED (v0.3.3) — ` +
+            "the NL tree-scan ranker is unreliable for explicit per-field " +
+            "queries. Use `x-browx-source.selector` (raw CSS) instead.");
+    }
+    ctx.evidence.selectorsUsed.push(query);
+    const node = scanTreeForBestMatch(ctx.scopeTree, query);
+    if (!node)
+        return missLeaf(ctx);
+    ctx.evidence.refsUsed.push(node.ref);
+    // Without a Locator we can only read the a11y-derived text/value. The
+    // overwhelming majority of deterministic extract use-cases land here —
+    // it's why the tree-walk is the primary path.
+    return readLeafFromNode(ctx, node, hint);
+}
+function missLeaf(ctx) {
+    ctx.evidence.partialMisses.push(ctx.path);
+    if (ctx.schema.required)
+        ctx.requiredMisses.push(ctx.path);
+    return MISS;
+}
+/** Pick the best node in the tree for a `query` — exact-name wins, else
+ *  testId-equals, else substring on name/testId. */
+/** Relevance score of one node for a lowercased query — exact name/testId wins,
+ *  then testId/name substring, role-equals, then per-token substring. */
+function scoreMatch(node, q) {
+    const name = (node.name ?? "").toLowerCase();
+    const tid = (node.testId ?? "").toLowerCase();
+    const role = node.role.toLowerCase();
+    let s = 0;
+    if (name === q || tid === q)
+        s += 100;
+    if (tid && tid.includes(q))
+        s += 30;
+    if (name && name.includes(q))
+        s += 20;
+    if (role === q)
+        s += 5;
+    for (const t of q.split(/\s+/).filter((x) => x.length >= 2)) {
+        if (tid.includes(t))
+            s += 5;
+        if (name.includes(t))
+            s += 3;
+    }
+    return s;
+}
+export function scanTreeForBestMatch(tree, query) {
+    const q = query.toLowerCase();
+    const best = treeSearch(tree, undefined, (acc, node) => {
+        const s = scoreMatch(node, q);
+        if (s > 0 && (!acc || s > acc.score))
+            return { node, score: s };
+        return acc;
+    });
+    return best?.node;
+}
+async function readLeafFromLocator(ctx, loc, hint) {
+    try {
+        const count = await loc.count();
+        if (count === 0)
+            return missLeaf(ctx);
+        if (hint.attr) {
+            const v = await loc.getAttribute(hint.attr);
+            if (v === null)
+                return missLeaf(ctx);
+            return coerceLeaf(v, ctx.schema.type);
+        }
+        if (hint.prop || hint.value) {
+            const propName = hint.prop ?? "value";
+            const v = await loc.evaluate((el, p) => el[p], propName);
+            if (v === undefined || v === null)
+                return missLeaf(ctx);
+            return coerceLeaf(v, ctx.schema.type);
+        }
+        // Default: visible text.
+        const text = (await loc.innerText().catch(() => "")).trim();
+        if (!text)
+            return missLeaf(ctx);
+        return coerceLeaf(text, ctx.schema.type);
+    }
+    catch {
+        return missLeaf(ctx);
+    }
+}
+function readLeafFromNode(ctx, node, hint) {
+    // No live Locator; the tree-only path covers what the snapshot carries.
+    if (hint.attr || hint.prop) {
+        // Annotation needs a page; record the miss so the caller knows the
+        // tree-walk couldn't satisfy it. (The locator path would have, given
+        // an explicit selector.)
+        return missLeaf(ctx);
+    }
+    // value-bearing nodes carry CDP-side `value` on the a11y node.
+    if (hint.value && node.value !== undefined) {
+        return coerceLeaf(node.value, ctx.schema.type);
+    }
+    const txt = (node.name ?? node.value ?? node.text ?? "").toString().trim();
+    if (!txt)
+        return missLeaf(ctx);
+    return coerceLeaf(txt, ctx.schema.type);
+}
+const TRUTHY_TOKENS = new Set(["true", 1, "1", "yes", "on"]);
+const FALSY_TOKENS = new Set(["false", 0, "0", "no", "off"]);
+function coerceNumber(raw) {
+    if (typeof raw === "number")
+        return raw;
+    const n = Number(String(raw).replace(/[^0-9.\-eE]/g, ""));
+    return Number.isFinite(n) ? n : null;
+}
+function coerceBoolean(raw) {
+    if (typeof raw === "boolean")
+        return raw;
+    if (TRUTHY_TOKENS.has(raw))
+        return true;
+    if (FALSY_TOKENS.has(raw))
+        return false;
+    return Boolean(raw);
+}
+export function coerceLeaf(raw, type) {
+    switch (type) {
+        case "string":
+            return typeof raw === "string" ? raw : String(raw);
+        case "number":
+            return coerceNumber(raw);
+        case "boolean":
+            return coerceBoolean(raw);
+        case "object":
+        case "array":
+            return raw;
+    }
+}
+/** Best-effort Locator for a ref — mirrors the lighter case in locator.ts
+ *  without hard-coupling here; we don't need full provenance routing for
+ *  extraction (the tree-walk does most of the work). */
+export function locatorForRef(page, refs, ref) {
+    const inputs = refs.locatorOf(ref);
+    if (!inputs)
+        return undefined;
+    if (inputs.testId) {
+        const attr = inputs.testIdAttr ?? "data-testid";
+        return page.locator(`[${attr}=${JSON.stringify(inputs.testId)}]`).first();
+    }
+    if (inputs.cssPath)
+        return page.locator(inputs.cssPath).first();
+    if (inputs.name)
+        return page
+            .getByRole(inputs.role, { name: inputs.name })
+            .first();
+    return page.getByRole(inputs.role).first();
+}

package/dist/page/extract-schema.d.ts

@@ -0,0 +1,20 @@
+import type { ExtractSchema, ExtractFailure, ExtractResult } from "./extract-types.js";
+export declare function fail(failure: ExtractFailure): ExtractResult;
+export declare function dedupe<T>(arr: T[]): T[];
+export declare function applySchemaRelaxations(schema: ExtractSchema, path: string, notes: string[]): void;
+/** Deep clone the caller-supplied schema before in-place mutation, so we
+ *  don't surprise an adopter holding a reference. Uses JSON for the
+ *  round-trip — schemas are plain data (no functions, no Dates). */
+export declare function cloneSchema(schema: unknown): ExtractSchema;
+/** Pure-tree validation. Returns a description of the first invariant
+ *  violation, or null when the schema is well-formed enough to attempt. */
+export declare function validateSchema(schema: ExtractSchema | undefined, path: string): string | null;
+/** Walk the schema tree and emit one diagnostic per unknown
+ *  `x-browx-source` key. Pure inspection — does not modify the schema.
+ *  Adopters who use, e.g., `attribute` instead of `attr` today see the
+ *  schema "succeed" with silently-wrong leaf values (wrightxai trial-1
+ *  turn 6: `url` came back as the title text because `attribute:"href"`
+ *  was silently dropped). The diagnostic surfaces the typo in
+ *  `evidence.partialMisses` so the agent can self-correct on the next
+ *  turn without a third "what shape does this take?" probe. */
+export declare function collectUnknownHintKeys(schema: ExtractSchema, path: string, out: string[]): void;