browxai 0.7.0

package/dist/page/extract-schema.js

@@ -0,0 +1,200 @@
+// Extract schema helpers — validation, dialect relaxations, unknown-key
+// diagnostics, and the small result/dedup utilities. Pure functions over the
+// schema tree; shared by the `extract` orchestrator and the resolution engine.
+// Split out of extract.ts to keep it (and extract-resolve.ts) under the size
+// budget, and to break the orchestrator↔resolver import cycle. Re-exported
+// through `./extract.js` so callers + tests import unchanged.
+import { estimateTokens } from "../util/tokens.js";
+export function fail(failure) {
+    const body = { ok: false, failure };
+    return { ...body, tokensEstimate: estimateTokens(JSON.stringify(body)) };
+}
+export function dedupe(arr) {
+    return [...new Set(arr)];
+}
+/** Supported `type` values. The list is closed: JSON-Schema's `integer`,
+ *  `null`, `any`, and union types are NOT supported and will be rejected
+ *  with a "Did you mean...?" hint when the rejection corresponds to a
+ *  known alias (e.g. `integer` → `number`). */
+const SUPPORTED_TYPES = ["object", "array", "string", "number", "boolean"];
+/** Known `x-browx-source` keys — used for unknown-key diagnostics. The
+ *  resolver only reads these; any other key is silently dropped today,
+ *  which costs adopters debugging time when (say) `attribute` is used
+ *  instead of `attr`. */
+const KNOWN_HINT_KEYS = [
+    "query",
+    "selector",
+    "attr",
+    "prop",
+    "text",
+    "value",
+    "collection",
+];
+/** Closest known type for a rejected type — used to power "Did you mean?"
+ *  hints in the validator error. Conservative: only suggests when there's
+ *  a clear high-confidence alias (e.g. `integer`/`int` → `number`). */
+function suggestType(t) {
+    const s = String(t).toLowerCase();
+    if (s === "integer" || s === "int" || s === "float" || s === "double" || s === "long")
+        return "number";
+    if (s === "bool")
+        return "boolean";
+    if (s === "str" || s === "text")
+        return "string";
+    if (s === "list" || s === "tuple")
+        return "array";
+    if (s === "dict" || s === "map" || s === "record")
+        return "object";
+    return null;
+}
+/** Closest known hint-key for a rejected key — symmetric to `suggestType`.
+ *  Powers the unknown-hint-key diagnostic ("did you mean `attr`?"). */
+function suggestHintKey(k) {
+    const s = k.toLowerCase();
+    if (s === "attribute")
+        return "attr";
+    if (s === "property")
+        return "prop";
+    if (s === "css" || s === "cssselector" || s === "css_selector")
+        return "selector";
+    if (s === "label" || s === "name" || s === "search")
+        return "query";
+    if (s === "container" || s === "items_selector" || s === "rows" || s === "list")
+        return "collection";
+    // `transform`, `format`, `regex`, `parser` are NOT supported at all.
+    return null;
+}
+/** Walk the schema tree and (1) coerce `type:"integer"` → `type:"number"`
+ *  in place, recording an educational `partialMisses`-bound note per
+ *  coercion site, and (2) promote `x-browx-source.selector` to
+ *  `x-browx-source.collection` on array schemas that lack `collection`
+ *  (the selector key on an array is meaningless today — no leaf-`selector`
+ *  semantics applies — so the alias is a no-op-overlap promotion).
+ *
+ *  Proposal A (v0.2.3): `integer` is now accepted as a schema-dialect
+ *  alias for `number`. The leaf coercer already returns JS numbers; a
+ *  consumer wanting an enforced integer can `Math.trunc()` themselves.
+ *  The educational note preserves the diagnostic trail for adopters
+ *  still on the agent-learning curve.
+ *
+ *  Proposal B (v0.2.3): `selector` on an array is treated as an alias
+ *  for `collection`. If both are present, `collection` wins (the
+ *  canonical name) — `selector` is dropped from the merged hint so the
+ *  resolver doesn't see a stale key. We deliberately do NOT emit a
+ *  partialMisses note for this case: the alias is idiomatic and the
+ *  resolver already explains `collection` semantics elsewhere, so the
+ *  extra noise would dilute the diagnostic surface.
+ *
+ *  Pure-additive on the call's outcome — the v0.2.2 `collectUnknownHintKeys`
+ *  diagnostics still fire (the strict-env opt-in is what changes those
+ *  into hard rejections), and validateSchema runs AFTER this pass, so a
+ *  schema that was previously rejected for `integer` now resolves. */
+/** (B) On an array schema, alias `x-browx-source.selector` to `collection`
+ *  (the canonical key) — `collection` wins if both are present; the redundant
+ *  `selector` is dropped so the resolver never sees a stale key. */
+function aliasArraySelectorToCollection(schema) {
+    const hint = schema["x-browx-source"];
+    if (!hint || typeof hint !== "object")
+        return;
+    const h = hint;
+    if (typeof h.selector !== "string")
+        return;
+    if (!h.collection)
+        h.collection = h.selector;
+    delete h.selector;
+}
+export function applySchemaRelaxations(schema, path, notes) {
+    // (A) integer → number — in place.
+    if (schema.type === "integer") {
+        schema.type = "number";
+        notes.push(`${path || "<root>"}: schema 'integer' coerced to 'number' for forward-compat; use 'number' explicitly in future schemas`);
+    }
+    // (B) array `selector` aliased to `collection` — in place.
+    if (schema.type === "array")
+        aliasArraySelectorToCollection(schema);
+    // Recurse — into object properties and array items.
+    if (schema.type === "object" && schema.properties) {
+        for (const [k, v] of Object.entries(schema.properties)) {
+            applySchemaRelaxations(v, path ? `${path}.${k}` : k, notes);
+        }
+    }
+    else if (schema.type === "array" && schema.items) {
+        applySchemaRelaxations(schema.items, `${path}[]`, notes);
+    }
+}
+/** 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 function cloneSchema(schema) {
+    return JSON.parse(JSON.stringify(schema));
+}
+const VALID_TYPES = new Set(["object", "array", "string", "number", "boolean"]);
+/** Validate the `type` field is one of the supported set, with a "did you mean?"
+ *  hint for known aliases. Returns the violation message or null. */
+function validateType(t, path) {
+    if (VALID_TYPES.has(t))
+        return null;
+    const suggestion = suggestType(t);
+    const hint = suggestion ? ` — did you mean "${suggestion}"?` : "";
+    return `${path || "<root>"}: unsupported \`type\` ${JSON.stringify(t)} (supported: ${SUPPORTED_TYPES.join(", ")})${hint}`;
+}
+/** Validate an object schema's `properties` map and recurse into each. */
+function validateObjectChildren(schema, path) {
+    if (!schema.properties || typeof schema.properties !== "object") {
+        return `${path || "<root>"}: object schema requires \`properties\` (a map of property-name → sub-schema)`;
+    }
+    for (const [k, v] of Object.entries(schema.properties)) {
+        const e = validateSchema(v, path ? `${path}.${k}` : k);
+        if (e)
+            return e;
+    }
+    return null;
+}
+/** Pure-tree validation. Returns a description of the first invariant
+ *  violation, or null when the schema is well-formed enough to attempt. */
+export function validateSchema(schema, path) {
+    if (!schema || typeof schema !== "object")
+        return `${path || "<root>"}: schema must be an object`;
+    const typeError = validateType(schema.type, path);
+    if (typeError)
+        return typeError;
+    if (schema.type === "object")
+        return validateObjectChildren(schema, path);
+    if (schema.type === "array") {
+        if (!schema.items) {
+            return `${path || "<root>"}: array schema requires \`items\` (the per-row sub-schema)`;
+        }
+        return validateSchema(schema.items, `${path}[]`);
+    }
+    return 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 function collectUnknownHintKeys(schema, path, out) {
+    const hint = schema["x-browx-source"];
+    if (hint && typeof hint === "object") {
+        for (const k of Object.keys(hint)) {
+            if (!KNOWN_HINT_KEYS.includes(k)) {
+                const suggestion = suggestHintKey(k);
+                const hintTxt = suggestion
+                    ? `; did you mean \`${suggestion}\`?`
+                    : ` (known: ${KNOWN_HINT_KEYS.join(", ")})`;
+                out.push(`${path || "<root>"}: unknown \`x-browx-source\` key \`${k}\`${hintTxt}`);
+            }
+        }
+    }
+    if (schema.type === "object" && schema.properties) {
+        for (const [k, v] of Object.entries(schema.properties)) {
+            collectUnknownHintKeys(v, path ? `${path}.${k}` : k, out);
+        }
+    }
+    else if (schema.type === "array" && schema.items) {
+        collectUnknownHintKeys(schema.items, `${path}[]`, out);
+    }
+}

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

@@ -0,0 +1,127 @@
+/** Private marker stamped on a hint when the implicit name-as-query lowering ran
+ *  (so the per-leaf resolver knows the query is internal, not user-supplied — and
+ *  skips the retirement warning). Module-private symbol; never surfaces in
+ *  serialised schemas. */
+export declare const IMPLICIT_QUERY: unique symbol;
+export type HintWithMarker = ExtractSourceHint & {
+    [IMPLICIT_QUERY]?: true;
+};
+/** Mode toggle. `"deterministic"` is the only supported value. The legacy
+ *  `"llm-assisted"` literal is retained in the union so that runtime callers
+ *  passing it (pre-v0.3.2 adopters) still type-check at the page-layer boundary;
+ *  the SDK type no longer exposes it. At runtime it is tolerated with a
+ *  `console.warn` and falls through to deterministic. */
+export type ExtractMode = "deterministic" | "llm-assisted";
+/** A JSON-Schema-flavoured shape. We accept the subset that has a clear
+ *  selector-lowering: object, array, string, number, boolean. `properties`
+ *  / `items` recurse; the `x-browx-source` extension is the explicit DSL. */
+export interface ExtractSchema {
+    type: "object" | "array" | "string" | "number" | "boolean";
+    /** Property map for `type:"object"`. Keys are property names; the property
+     *  name *is* the implicit query unless overridden via x-browx-source. */
+    properties?: Record<string, ExtractSchema>;
+    /** Item schema for `type:"array"`. Required when `type:"array"`. */
+    items?: ExtractSchema;
+    /** Per-property explicit source annotation. Overrides the implicit
+     *  "property name = query" rule. All fields optional; the first present
+     *  field wins in source-resolution order. */
+    "x-browx-source"?: ExtractSourceHint;
+    /** Optional fallback default when extraction misses. The result still
+     *  records the miss in `evidence.partialMisses` — the default keeps the
+     *  data shape sane without lying about ground truth. */
+    default?: unknown;
+    /** Whether the field is required. Default false. Required misses surface
+     *  in `failure.partialMisses`; optional misses only emit `partialMiss`
+     *  evidence. */
+    required?: boolean;
+}
+export interface ExtractSourceHint {
+    /** RETIRED in v0.3.3 — the NL tree-scan ranker is unreliable for
+     *  explicit prose-style per-field queries (uniform null/0 across rows
+     *  with no partialMiss surfaced; see R-5). The typed SDK no longer
+     *  exposes this field; passing it at runtime emits a one-shot warn and
+     *  records a partialMisses entry so the diagnostic surfaces. Use
+     *  `selector` (raw CSS) instead — the implicit property-name lowering
+     *  still works for testid-friendly pages. Retained on the page-layer
+     *  type so the internal implicit-name path keeps compiling. */
+    query?: string;
+    /** Raw CSS / selectorHint, resolved against the current scope. */
+    selector?: string;
+    /** When set, read this HTML attribute (e.g. "href", "data-state") from
+     *  the matched element. Mutually exclusive with `prop` / `text` / `value`. */
+    attr?: string;
+    /** When set, read this DOM property (e.g. "value", "checked") via the
+     *  page-side. Mutually exclusive with `attr` / `text` / `value`. */
+    prop?: string;
+    /** When `true`, read the trimmed visible text. The default behaviour
+     *  when no read-mode hint is set. */
+    text?: boolean;
+    /** When `true`, read the form-control value (alias for `prop:"value"`). */
+    value?: boolean;
+    /** For `type:"array"` only — the collection container selector OR query
+     *  whose matches each get a per-row scope. */
+    collection?: string;
+}
+export interface ExtractOptions {
+    /** JSON-schema input. Must be a top-level object or array. Accepts an
+     *  already-typed `ExtractSchema` (internal callers) or a raw wire object
+     *  (the MCP `extract` tool passes the untrusted payload straight through);
+     *  `extract()` validates it via `validateSchema` and returns a structured
+     *  `invalid-schema` failure when it is malformed. */
+    schema: ExtractSchema | Record<string, unknown>;
+    /** Scope to a ref's subtree (from a prior snapshot/find). */
+    ref?: string;
+    /** Scope to a CSS selector match. Mutually exclusive with `ref`. */
+    scope?: string;
+    /** Default `"deterministic"` (the only supported path). RETIRED in
+     *  v0.3.2 — `"llm-assisted"` is tolerated at runtime for back-compat
+     *  (warn + treat as deterministic) but is no longer in the SDK type.
+     *  Drop the arg from new code. */
+    mode?: ExtractMode;
+    testAttributes: string[];
+    /** When true, v0.2.2's unknown-`x-browx-source`-key diagnostics are
+     *  promoted from `evidence.partialMisses` entries to hard `ok:false`
+     *  `invalid-schema` rejections — adopters who want first-class typo
+     *  detection enable this. Defaults to `process.env.BROWX_EXTRACT_STRICT`
+     *  being set when undefined. The integer→number coerce and the
+     *  selector-as-collection alias are NOT promoted by this flag — those
+     *  are educational signals, not typo-like errors. */
+    strictUnknownHintKeys?: boolean;
+}
+export interface ExtractEvidence {
+    /** Refs (stable `eN`) the extractor drew from, deduped. Lets the caller
+     *  pin them via `name_ref` or cache the lookup. */
+    refsUsed: string[];
+    /** Selectors / queries the extractor actually resolved against — useful
+     *  for adopters debugging "why did this property come back empty?". */
+    selectorsUsed: string[];
+    /** Property paths that had no match and (when required) caused the
+     *  extraction to fail. Each entry is the dotted path through the schema
+     *  ("rows[3].price"). */
+    partialMisses: string[];
+}
+export interface ExtractFailure {
+    /** `"app"` when the schema didn't fit the page (missing required fields);
+     *  `"browxai"` when extract itself couldn't run (invalid scope, invalid
+     *  schema). */
+    source: "app" | "browxai";
+    /** Stable kind label. `"llm-assisted-not-implemented"` is retained in the
+     *  union as a RETIRED kind — v0.3.2 stopped emitting it (the `mode` arg
+     *  is tolerated with a warn instead). New code should not narrow on it. */
+    kind: "invalid-schema" | "scope-not-found" | "required-miss" | "llm-assisted-not-implemented";
+    expected: string;
+    actual: unknown;
+    evidence?: Partial<ExtractEvidence> & Record<string, unknown>;
+    /** When `required-miss`: the missing property paths. */
+    partialMisses?: string[];
+}
+export type ExtractResult = {
+    ok: true;
+    data: unknown;
+    evidence: ExtractEvidence;
+    tokensEstimate: number;
+} | {
+    ok: false;
+    failure: ExtractFailure;
+    tokensEstimate: number;
+};

package/dist/page/extract-types.js

@@ -0,0 +1,8 @@
+// Extraction type vocabulary — the schema/hint/evidence/result types shared by
+// the `extract` orchestrator and the resolution engine. Split out of extract.ts
+// so neither file carries the other's bulk; re-exported through `./extract.js`.
+/** Private marker stamped on a hint when the implicit name-as-query lowering ran
+ *  (so the per-leaf resolver knows the query is internal, not user-supplied — and
+ *  skips the retirement warning). Module-private symbol; never surfaces in
+ *  serialised schemas. */
+export const IMPLICIT_QUERY = Symbol.for("browxai.extract.implicitQuery");

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

@@ -0,0 +1,8 @@
+export declare function warnLlmAssistedRetired(): void;
+/** Test-only hook — resets the one-shot guard so the warn-emission can be
+ *  re-asserted in isolation. Not exported from `index.ts`. */
+export declare function __resetLlmAssistedWarnedForTests(): void;
+export declare function warnExplicitNlQueryRetired(): void;
+/** Test-only hook — resets the one-shot guard so the warn-emission can be
+ *  re-asserted in isolation. Not exported from `index.ts`. */
+export declare function __resetExplicitNlQueryWarnedForTests(): void;

package/dist/page/extract-warnings.js

@@ -0,0 +1,56 @@
+// One-shot deprecation warnings for the retired extract options. Module state so
+// adopters don't spam stderr on every call; the test-only reset hooks let the
+// regression suite re-assert the warn fires. Split out of extract.ts.
+/** One-shot warn for the RETIRED `mode:"llm-assisted"` arg (v0.3.2). Module
+ *  state so adopters don't spam stderr on every extract call. */
+let __llmAssistedWarned = false;
+export function warnLlmAssistedRetired() {
+    if (__llmAssistedWarned)
+        return;
+    __llmAssistedWarned = true;
+    console.warn('browxai: extract({ mode: "llm-assisted" }) is RETIRED as of v0.3.2 — ' +
+        "the `mode` arg is no longer part of the SDK type. Treating as " +
+        'mode:"deterministic" (the only supported path). Drop the arg from ' +
+        "your call site to silence this warning.");
+}
+/** Test-only hook — resets the one-shot guard so the warn-emission can be
+ *  re-asserted in isolation. Not exported from `index.ts`. */
+export function __resetLlmAssistedWarnedForTests() {
+    __llmAssistedWarned = false;
+}
+/** One-shot warn for the RETIRED `x-browx-source.query` per-field hint
+ *  (v0.3.3). The natural-language tree-scan ranker is unreliable in
+ *  production — wrightxai's smoke trial saw the LLM author a prose query
+ *  for a per-row numeric field on Hacker News, and the resolver returned
+ *  null for every row (one stale ref re-used across all 30 row scopes,
+ *  no partialMiss surfaced — the agent burned 14 revisions). Same shape
+ *  of defect as R-1's `mode:"llm-assisted"`: advertised in the typed SDK,
+ *  unreliable at runtime. Retired at the typed boundary; tolerated at
+ *  runtime with a one-shot warn + per-call `partialMisses` entry so the
+ *  caller sees the actionable diagnostic.
+ *
+ *  Note: this guards the EXPLICIT user-supplied `query`. The implicit
+ *  "property-name as query" lowering path (`resolveObject` stamps
+ *  `{ query: name }` for an un-hinted property) is unchanged — the bare
+ *  property-name case still works on testid-rich pages and is the
+ *  documented primary path. */
+let __explicitNlQueryWarned = false;
+export function warnExplicitNlQueryRetired() {
+    if (__explicitNlQueryWarned)
+        return;
+    __explicitNlQueryWarned = true;
+    console.warn("browxai: extract() — explicit per-field `x-browx-source.query` is " +
+        "RETIRED as of v0.3.3. The NL tree-scan ranker is unreliable on " +
+        "prose-style queries (uniform null/0 across rows, no partialMiss " +
+        "surfaced — see R-5 / wrightxai smoke trial). Use " +
+        "`x-browx-source.selector` (raw CSS / selectorHint) for per-field " +
+        "targeting; the implicit property-name lowering still works for " +
+        "testid-friendly pages. The runtime still attempts resolution and " +
+        "records a partialMisses entry so the diagnostic surfaces in " +
+        "evidence — drop explicit `query:` to silence this warning.");
+}
+/** Test-only hook — resets the one-shot guard so the warn-emission can be
+ *  re-asserted in isolation. Not exported from `index.ts`. */
+export function __resetExplicitNlQueryWarnedForTests() {
+    __explicitNlQueryWarned = false;
+}

package/dist/page/extract.d.ts

@@ -0,0 +1,9 @@
+import type { Page } from "playwright-core";
+import type { RefRegistry } from "./refs.js";
+import type { SnapshotSubstrate } from "./snapshot-substrate.js";
+import type { ExtractResult, ExtractOptions } from "./extract-types.js";
+export type { ExtractSchema, ExtractSourceHint, ExtractEvidence, ExtractFailure, ExtractResult, ExtractOptions, ExtractMode, } from "./extract-types.js";
+export { __resetLlmAssistedWarnedForTests, __resetExplicitNlQueryWarnedForTests, } from "./extract-warnings.js";
+export { resolveAgainstTree, scanTreeForBestMatch, coerceLeaf } from "./extract-resolve.js";
+export { applySchemaRelaxations, cloneSchema, validateSchema, collectUnknownHintKeys, } from "./extract-schema.js";
+export declare function extract(page: Page, substrate: SnapshotSubstrate, refs: RefRegistry, opts: ExtractOptions): Promise<ExtractResult>;

package/dist/page/extract.js

@@ -0,0 +1,174 @@
+// Structured schema-driven extract primitive.
+//
+// The schema-as-contract primitive every browxai
+// adopter currently rebuilds the same "parse this table into rows" loop on
+// top of `snapshot()`. Stagehand `extract`, Skyvern, browser-use all ship
+// this. browxai's version is **deterministic only** (selector-only —
+// schema fields lower to `find()` / selector queries scoped to a subtree).
+//
+// The `mode` arg is RETIRED as of v0.3.2 — deterministic is the supported
+// path. `mode:"llm-assisted"` is tolerated for back-compat (warn + fall
+// through to deterministic) but is no longer in the typed SDK surface.
+//
+// The schema is the contract: invalid input / partial matches surface in
+// `failure.partialMisses`, never silently coerced into a malformed object.
+//
+// Schema-to-query lowering. Two paths, deliberately layered:
+//
+//   1. **Implicit (the simple rule):** the property *name* is the find()
+//      query. `{type:"string"}` property `"price"` → look for a node
+//      matching "price" within the current scope and read its visible
+//      text. Works on testid-rich pages where the property names line up
+//      with `data-testid` tokens / accessible names.
+//
+//   2. **Explicit (the escape hatch):** a property may carry an
+//      `x-browx-source` annotation overriding any of {query, selector,
+//      attr, prop, text, value}. This is the richer DSL the design
+//      called out as a tension — we ship both rules and document the
+//      simple one as the primary path. The escape hatch covers the cases
+//      where the name doesn't carry enough signal (`"theFirstThing":
+//      <selector>`) or where the value isn't innerText (an attribute,
+//      a DOM property, a form-control value).
+//
+// Arrays lower to a collection probe: `{type:"array", items:<inner>,
+// "x-browx-source":{collection:<selectorOrQuery>}}` finds the container
+// elements and runs the inner schema scoped to each. Without an explicit
+// collection, an array property is rejected as `partialMiss: "array needs
+// x-browx-source.collection"` — there's no defensible implicit default
+// (the empty list is a lie).
+//
+// Nested objects recurse — each sub-property resolves within the parent's
+// scope, exactly the same lowering rule.
+//
+// Refs used during extraction land in `evidence.refsUsed` so the caller
+// can audit / cache / pin (`name_ref`) the elements the result drew from.
+import { findByRef } from "./snapshot.js";
+import { estimateTokens } from "../util/tokens.js";
+import { warnLlmAssistedRetired } from "./extract-warnings.js";
+import { resolveAgainstTree, locatorForRef } from "./extract-resolve.js";
+import { fail, dedupe, cloneSchema, applySchemaRelaxations, validateSchema, collectUnknownHintKeys, } from "./extract-schema.js";
+export { __resetLlmAssistedWarnedForTests, __resetExplicitNlQueryWarnedForTests, } from "./extract-warnings.js";
+export { resolveAgainstTree, scanTreeForBestMatch, coerceLeaf } from "./extract-resolve.js";
+export { applySchemaRelaxations, cloneSchema, validateSchema, collectUnknownHintKeys, } from "./extract-schema.js";
+/** Clone + relax the schema, then validate it (and, under strict mode, reject
+ *  unknown `x-browx-source` keys). Returns the relaxed schema + the educational
+ *  relaxation notes, or a structured `invalid-schema` failure. */
+function prepareSchema(opts) {
+    // Clone first so we never mutate the caller-supplied object; relaxation notes
+    // ride through to evidence.partialMisses on the successful path.
+    const schema = cloneSchema(opts.schema);
+    const relaxationNotes = [];
+    applySchemaRelaxations(schema, "", relaxationNotes);
+    const schemaError = validateSchema(schema, "");
+    if (schemaError) {
+        return failPrepared("invalid-schema", "a JSON schema whose root is object or array", schemaError);
+    }
+    // Strict mode: promote unknown-`x-browx-source`-key diagnostics from soft
+    // `partialMisses` notes to a hard `invalid-schema` rejection. Default off;
+    // opt-in via env or call-arg.
+    const strict = opts.strictUnknownHintKeys ?? process.env.BROWX_EXTRACT_STRICT === "1";
+    if (strict) {
+        const unknown = [];
+        collectUnknownHintKeys(schema, "", unknown);
+        if (unknown.length > 0) {
+            return failPrepared("invalid-schema", "every `x-browx-source` key to be one of the known set (BROWX_EXTRACT_STRICT=1 is on)", unknown.join(" | "));
+        }
+    }
+    return { ok: true, value: { schema, relaxationNotes } };
+}
+function failPrepared(kind, expected, actual) {
+    return { ok: false, failure: fail({ source: "browxai", kind, expected, actual }) };
+}
+/** Compose the snapshot and resolve the requested scope (whole tree, a ref
+ *  subtree, or a CSS-selector scope), validating the empty-scope invariant. */
+async function resolveScope(page, substrate, refs, opts) {
+    if (opts.ref && opts.scope) {
+        return failPrepared("invalid-schema", "exactly one of `ref` or `scope`", "both provided");
+    }
+    const tree = (await substrate.compose(refs, opts.testAttributes)).tree;
+    if (!tree) {
+        return {
+            ok: false,
+            failure: fail({
+                source: "app",
+                kind: "scope-not-found",
+                expected: "a non-empty accessibility tree",
+                actual: "empty",
+            }),
+        };
+    }
+    if (opts.ref) {
+        const sub = findByRef(tree, opts.ref);
+        if (!sub) {
+            return failPrepared("scope-not-found", `ref "${opts.ref}" to resolve in the current snapshot`, "no matching ref");
+        }
+        return {
+            ok: true,
+            value: { scopeTree: sub, scopeLocator: locatorForRef(page, refs, opts.ref) },
+        };
+    }
+    if (opts.scope) {
+        const scopeLocator = page.locator(opts.scope).first();
+        const count = await page
+            .locator(opts.scope)
+            .count()
+            .catch(() => 0);
+        if (count === 0) {
+            return failPrepared("scope-not-found", `scope selector "${opts.scope}" to match ≥1 element`, "0 matches");
+        }
+        return { ok: true, value: { scopeTree: tree, scopeLocator } };
+    }
+    return { ok: true, value: { scopeTree: tree } };
+}
+export async function extract(page, substrate, refs, opts) {
+    // The `mode` arg is RETIRED as of v0.3.2 — deterministic is the only supported
+    // path. Tolerate `mode:"llm-assisted"` at runtime (graceful deprecation): emit
+    // a one-shot console.warn and fall through to deterministic.
+    if (opts.mode === "llm-assisted")
+        warnLlmAssistedRetired();
+    const prepared = prepareSchema(opts);
+    if (!prepared.ok)
+        return prepared.failure;
+    const { schema: relaxedSchema, relaxationNotes } = prepared.value;
+    const scoped = await resolveScope(page, substrate, refs, opts);
+    if (!scoped.ok)
+        return scoped.failure;
+    const { scopeTree, scopeLocator } = scoped.value;
+    const { data, evidence, requiredMisses } = await resolveAgainstTree({
+        schema: relaxedSchema,
+        page,
+        scopeTree,
+        scopeLocator,
+    });
+    // Educational A/B notes ride at the head of partialMisses so the agent
+    // sees them on the same observation as the resolved data.
+    if (relaxationNotes.length > 0) {
+        evidence.partialMisses = [...relaxationNotes, ...evidence.partialMisses];
+    }
+    if (requiredMisses.length > 0) {
+        return fail({
+            source: "app",
+            kind: "required-miss",
+            expected: "all required schema properties to resolve",
+            actual: `${requiredMisses.length} required field(s) missing`,
+            evidence: {
+                refsUsed: dedupe(evidence.refsUsed),
+                selectorsUsed: dedupe(evidence.selectorsUsed),
+                partialMisses: evidence.partialMisses,
+            },
+            partialMisses: requiredMisses,
+        });
+    }
+    const out = {
+        ok: true,
+        data,
+        evidence: {
+            refsUsed: dedupe(evidence.refsUsed),
+            selectorsUsed: dedupe(evidence.selectorsUsed),
+            partialMisses: evidence.partialMisses,
+        },
+        tokensEstimate: 0,
+    };
+    out.tokensEstimate = estimateTokens(JSON.stringify(out));
+    return out;
+}

package/dist/page/fill-form.d.ts

@@ -0,0 +1,58 @@
+import type { Locator, Page } from "playwright-core";
+import { type ActionContext, type ActionResult, type ActionWindowOptions } from "./actionresult.js";
+import { type ActionTarget } from "./locator.js";
+export interface FillFormField {
+    target: ActionTarget;
+    value: string;
+}
+export interface FillFormArgs extends ActionWindowOptions {
+    fields: FillFormField[];
+    /** Optional submit target. Clicked after every field has filled
+     *  successfully. Skipped when any field fails (atomic submit semantics —
+     *  we don't submit a partially-filled form). */
+    submit?: ActionTarget;
+}
+/** Per-field resolution outcome surfaced when the atomic pre-resolution
+ *  step fails. `index` lines up with the input `fields[]` order. */
+export interface FieldResolution {
+    index: number;
+    /** Compact identification of which target shape was passed — for
+     *  agent-facing error messages. */
+    targetSummary: string;
+    ok: boolean;
+    error?: string;
+}
+/** Per-field dispatch outcome included in the result's `elements` slot is
+ *  the post-fill `ElementProbe`. When the atomic resolution step rejected
+ *  the call, `elements` is omitted and `fieldResolution` (on the result
+ *  envelope as an extension) carries the per-field outcomes. */
+export interface FillFormResult extends ActionResult {
+    /** Per-field resolution outcomes — only present when the atomic
+     *  resolution step rejected the call (`ok:false`, no fills landed). */
+    fieldResolution?: FieldResolution[];
+    /** When a per-field fill failed mid-loop, the 0-based index of the
+     *  offending field and a list of skipped indices. Distinguishes
+     *  "rejected atomically" from "started filling then hit an app error". */
+    fillFailure?: {
+        atIndex: number;
+        skipped: number[];
+    };
+}
+/** Pure helper: render a one-line summary of an ActionTarget so the
+ *  resolution-failure envelope is human-readable. Exported for unit tests. */
+export declare function summariseTarget(t: ActionTarget): string;
+/** Pure helper: validate the args shape before touching the page. Throws
+ *  on structural problems (empty fields, coord targets for fill — which
+ *  Playwright can't drive). Exported for unit tests. */
+export declare function validateFillFormArgs(args: FillFormArgs): void;
+export declare function resolveFieldsAtomically(page: Page, refs: ActionContext["refs"], fields: FillFormField[], submit?: ActionTarget): Promise<{
+    ok: true;
+    locators: Locator[];
+    submitLocator?: Locator;
+    resolutions: FieldResolution[];
+} | {
+    ok: false;
+    resolutions: FieldResolution[];
+    submitResolution?: FieldResolution;
+}>;
+export declare function fillForm(ctx: ActionContext, args: FillFormArgs): Promise<FillFormResult>;