browxai 0.7.0

package/dist/page/substrate-bundle-safari.js

@@ -0,0 +1,42 @@
+// The Safari `SubstrateBundle` factory (RFC 0004 D1, pattern 1). Safari is the
+// no-Playwright-Page engine, so its seven substrate selectors all read the
+// Safari-native handle (`e.session.safari!()`) instead of a Page/CDP. Each body
+// is byte-identical to its pre-fold form: the five host-build.ts Safari branches
+// (the `if (safariHandle) return new SafariXSubstrate(...)` legs), the Safari
+// snapshot selector (the `SafariSnapshotIO` {exec, currentUrl} wrapping at
+// snapshot-substrate-select.ts:46-50), and the Safari no-op network substrate.
+import { SafariActionSubstrate } from "./action-substrate.js";
+import { SafariCaptureSubstrate } from "./capture-substrate.js";
+import { SafariStorageSubstrate } from "./storage-substrate.js";
+import { SafariScriptSubstrate } from "./script-substrate.js";
+import { SafariEmulationSubstrate } from "./emulation-substrate.js";
+import { SafariClassicSnapshotSubstrate } from "./snapshot-substrate-safari.js";
+import { SafariNoopNetworkSubstrate } from "./network-substrate.js";
+/** The Safari `SubstrateBundle` — the safari engine registers this. `safari!()` is
+ *  the Safari-native WebDriver-Classic + BiDi handle, present on every safari
+ *  session by construction (the safari `BrowserSession` always supplies it). Takes
+ *  the per-server `SubstrateDeps` to honour the standardized `makeSubstrates(deps)`
+ *  contract, but ignores them: every Safari selector reads the Safari-native handle,
+ *  not the Playwright `ctxFor`/`describeTarget`/`save` deps. */
+export function safariSubstrateBundle(_deps) {
+    return {
+        actions: (e) => new SafariActionSubstrate(e.session.safari(), e.refs),
+        capture: (e) => new SafariCaptureSubstrate(e.session.safari()),
+        storage: (e) => new SafariStorageSubstrate(e.session.safari()),
+        script: (e) => new SafariScriptSubstrate(e.session.safari()),
+        emulation: (e) => new SafariEmulationSubstrate(e.session.safari()),
+        snapshot: (e) => {
+            // SafariClassicSnapshotSubstrate takes a SafariSnapshotIO seam
+            // ({ exec, currentUrl }), not the raw handle — exactly the wrapping the live
+            // snapshot-substrate-select.ts:46-50 did.
+            const handle = e.session.safari();
+            return new SafariClassicSnapshotSubstrate({
+                exec: (scriptBody, args) => handle.webDriver.executeScript(handle.sessionId, scriptBody, args),
+                currentUrl: () => handle.webDriver.currentUrl(handle.sessionId),
+            });
+        },
+        // Safari has no protocol-level network at all (no CDP tap, no BiDi network
+        // domain) — the empty no-op substrate; the network tools are capability-gated.
+        network: () => new SafariNoopNetworkSubstrate(),
+    };
+}

package/dist/page/substrate-bundle.d.ts

@@ -0,0 +1,6 @@
+import type { SubstrateBundle, SubstrateDeps } from "../engine/registry.js";
+/** The Playwright `SubstrateBundle` — the four Playwright engines register this.
+ *  `actions`/`capture` use the per-server host `deps` the composition root threads
+ *  in (closed over here, not a module-global); `storage`/`script`/`emulation` wrap
+ *  the session's Page/context; `snapshot`/`network` select by CDP presence. */
+export declare function playwrightSubstrateBundle(deps: SubstrateDeps): SubstrateBundle;

package/dist/page/substrate-bundle.js

@@ -0,0 +1,53 @@
+// The Playwright `SubstrateBundle` factory (RFC 0004 D1, pattern 1). Folds the
+// five host-build.ts selectors (actionsFor / captureFor / storageFor / scriptFor /
+// emulationFor) AND the two standalone selectors (snapshotSubstrateFor /
+// networkSubstrateFor) into one engine-owned bundle, so the four Playwright
+// engines (chromium / firefox / webkit / android) supply ONE substrate-bundle
+// factory instead of seven scattered closures. Each selector body is byte-identical
+// to its pre-fold form — only the home moves.
+//
+// The snapshot/network selectors stay capability-keyed (the engine's CDP presence,
+// not its name): chromium/android (CDP) → the verbatim CDP substrate; firefox/
+// webkit (Playwright Page, no CDP) → the page-side walker / event substrate. So a
+// future CDP-bearing Playwright engine routes correctly with no edit here.
+//
+// `actions`/`capture` need host config (`ctxFor`'s testAttributes/originPolicy/caps,
+// `describeTarget`, the screenshot `save` sink). The composition root (host-build)
+// owns those per-server locals and passes its OWN set as the `deps` argument to
+// `playwrightSubstrateBundle(deps)` — closed over here per server, NEVER a
+// module-global. A module-global would let a second `createServer()` in the same
+// process (the in-process SDK transport composes one server per transport)
+// overwrite the first server's originPolicy / workspace.root / caps, cross-
+// contaminating its sessions. Threading the deps explicitly keeps each server's
+// bundle bound to its own boundary.
+import { PlaywrightActionSubstrate } from "./action-substrate.js";
+import { PlaywrightCaptureSubstrate } from "./capture-substrate.js";
+import { PlaywrightStorageSubstrate } from "./storage-substrate.js";
+import { PlaywrightScriptSubstrate } from "./script-substrate.js";
+import { PlaywrightEmulationSubstrate } from "./emulation-substrate.js";
+import { snapshotSubstrateFor } from "./snapshot-substrate-select.js";
+import { networkSubstrateFor } from "./network-substrate-select.js";
+/** The Playwright `SubstrateBundle` — the four Playwright engines register this.
+ *  `actions`/`capture` use the per-server host `deps` the composition root threads
+ *  in (closed over here, not a module-global); `storage`/`script`/`emulation` wrap
+ *  the session's Page/context; `snapshot`/`network` select by CDP presence. */
+export function playwrightSubstrateBundle(deps) {
+    return {
+        actions: (e) => new PlaywrightActionSubstrate(() => deps.ctxFor(e), e.session.engine),
+        capture: (e) => new PlaywrightCaptureSubstrate(() => e.session.page(), e.refs, {
+            describeTarget: deps.describeTarget,
+            save: deps.save,
+        }),
+        storage: (e) => new PlaywrightStorageSubstrate(() => e.session.page().context(), () => e.session.page(), e.session.engine),
+        script: (e) => new PlaywrightScriptSubstrate(() => e.session.page(), e.session.engine),
+        emulation: (e) => new PlaywrightEmulationSubstrate(() => e.session.page().context(), () => e.session.page(), e.session.engine),
+        // Snapshot / network select by CDP presence — delegated to the existing
+        // capability-keyed selectors (chromium/android → the verbatim CDP substrate;
+        // firefox/webkit → the page-side walker / Playwright event substrate). The
+        // selectors take the session, so the bundle threads `e.session` through —
+        // byte-identical to the standalone `snapshotSubstrateFor` / `networkSubstrateFor`
+        // the session-registry used inline, now owned by the engine's bundle.
+        snapshot: (e) => snapshotSubstrateFor(e.session),
+        network: (e) => networkSubstrateFor(e.session),
+    };
+}

package/dist/page/text_search.d.ts

@@ -0,0 +1,44 @@
+import type { CDPSession } from "playwright-core";
+import { type A11yNode, type StructuralContext } from "./a11y.js";
+import type { RefRegistry } from "./refs.js";
+import type { SnapshotSubstrate } from "./snapshot-substrate.js";
+import { type VisibleRect } from "./bbox.js";
+export interface TextSearchOptions {
+    text: string;
+    /** Default false — substring (case-insensitive). When true, the match is
+     *  case-sensitive equality on the trimmed node name. */
+    exact?: boolean;
+    /** Limit the search to descendants of this ref (a prior snapshot/find result). */
+    scope?: string;
+    /** Default false — only visible (bbox-having) matches are returned. */
+    includeHidden?: boolean;
+    /** Default 20; hard cap 200. */
+    maxMatches?: number;
+    testAttributes: string[];
+}
+export interface TextSearchMatch {
+    ref: string;
+    role: string;
+    text: string;
+    context?: StructuralContext;
+    bbox: VisibleRect | null;
+    clipped: boolean;
+}
+export interface TextSearchResult {
+    count: number;
+    matches: TextSearchMatch[];
+    warnings: string[];
+}
+export declare function textSearch(substrate: SnapshotSubstrate, refs: RefRegistry, opts: TextSearchOptions, 
+/** Raw CDP handle for the visible-rect bbox fast path — chromium only.
+ *  Off Chromium the walker mints no `backendDOMNodeId`, so this is unused and
+ *  hidden/visible classification rides the bbox being null (clipped). */
+cdp?: CDPSession): Promise<TextSearchResult>;
+/**
+ * Pure-tree search: walk `root` and return nodes whose `name` matches `text`.
+ * Exported for unit testing.
+ *
+ * @param max  hard cap on the *walked* candidate count (post-filter list is
+ *             capped separately at the caller's `maxMatches`).
+ */
+export declare function searchTreeForText(root: A11yNode, text: string, exact: boolean, max?: number): A11yNode[];

package/dist/page/text_search.js

@@ -0,0 +1,90 @@
+// `text_search` read primitive.
+//
+// Verification and absence checks: "is the bad value gone?" / "did 'Saved' appear?".
+// Distinct from `find()` (which ranks actionable targets) — `text_search` simply
+// counts matches of a text query against rendered node names, optionally scoped
+// to a subtree, with structural context attached to each match.
+import { walk } from "./a11y.js";
+import { visibleRect } from "./bbox.js";
+import { findByRef } from "./snapshot.js";
+export async function textSearch(substrate, refs, opts, 
+/** Raw CDP handle for the visible-rect bbox fast path — chromium only.
+ *  Off Chromium the walker mints no `backendDOMNodeId`, so this is unused and
+ *  hidden/visible classification rides the bbox being null (clipped). */
+cdp) {
+    const { tree } = await substrate.compose(refs, opts.testAttributes);
+    if (!tree)
+        return { count: 0, matches: [], warnings: [] };
+    const warnings = [];
+    let walkRoot = tree;
+    if (opts.scope) {
+        const sub = findByRef(tree, opts.scope);
+        if (sub)
+            walkRoot = sub;
+        else
+            warnings.push(`scope=${opts.scope} not found; searching the full tree instead.`);
+    }
+    const max = Math.min(opts.maxMatches ?? 20, 200);
+    const includeHidden = opts.includeHidden ?? false;
+    const candidates = searchTreeForText(walkRoot, opts.text, opts.exact ?? false, max * 4);
+    const matches = [];
+    for (const node of candidates) {
+        if (matches.length >= max)
+            break;
+        const match = await classifyMatch(node, includeHidden, cdp);
+        if (match)
+            matches.push(match);
+    }
+    return { count: matches.length, matches, warnings };
+}
+/** Resolve one candidate node to a match, applying the visible-only filter.
+ *  A node only reaches here if it's in the NON-IGNORED a11y tree (display:none /
+ *  aria-hidden subtrees are pruned upstream). WITH a backendDOMNodeId a null bbox
+ *  means off-screen → hidden. WITHOUT one — the AX tree omits it for many inline /
+ *  StaticText nodes, which is exactly what a text query matches — we cannot prove
+ *  off-screen, so we treat the rendered node as visible rather than silently
+ *  dropping every plain-text match in the default mode. The `clipped` flag still
+ *  records that the rect was indeterminate. */
+async function classifyMatch(node, includeHidden, cdp) {
+    const bbox = cdp !== undefined && node.backendDOMNodeId !== undefined
+        ? await visibleRect(cdp, node.backendDOMNodeId)
+        : null;
+    const hasBackendId = cdp !== undefined && node.backendDOMNodeId !== undefined;
+    const visible = hasBackendId ? bbox !== null : true;
+    if (!visible && !includeHidden)
+        return null;
+    const match = {
+        ref: node.ref,
+        role: node.role,
+        text: node.name ?? "",
+        bbox,
+        clipped: !visible,
+    };
+    if (node.context)
+        match.context = node.context;
+    return match;
+}
+/**
+ * Pure-tree search: walk `root` and return nodes whose `name` matches `text`.
+ * Exported for unit testing.
+ *
+ * @param max  hard cap on the *walked* candidate count (post-filter list is
+ *             capped separately at the caller's `maxMatches`).
+ */
+export function searchTreeForText(root, text, exact, max = 200) {
+    const out = [];
+    const target = text;
+    const targetLower = text.toLowerCase();
+    for (const { node } of walk(root)) {
+        const name = (node.name ?? "").trim();
+        if (!name)
+            continue;
+        const hit = exact ? name === target : name.toLowerCase().includes(targetLower);
+        if (hit) {
+            out.push(node);
+            if (out.length >= max)
+                break;
+        }
+    }
+    return out;
+}

package/dist/page/upload.d.ts

@@ -0,0 +1,28 @@
+import type { Page } from "playwright-core";
+import type { RefRegistry } from "./refs.js";
+import { type ActionTarget } from "./locator.js";
+export interface UploadArgs {
+    target: ActionTarget;
+    /** filename presented to the page (content-mode; default "upload"). */
+    name?: string;
+    /** MIME type (content-mode; default "application/octet-stream"). */
+    mimeType?: string;
+    /** base64 file content. Mutually exclusive with `path`. */
+    content?: string;
+    /** workspace-rooted file path. Mutually exclusive with `content`. */
+    path?: string;
+}
+export interface UploadResult {
+    ok: boolean;
+    mode: "content" | "path";
+    name: string;
+    /** byte size of the file that was set. */
+    bytes: number;
+    /** MIME type — set in content-mode (path-mode lets the browser infer). */
+    mimeType?: string;
+    /** short summary of the resolved input target (ref/selector). */
+    target: string;
+    /** number of files set on the input (always 1 today). */
+    fileCount: number;
+}
+export declare function uploadFile(page: Page, refs: RefRegistry, workspaceRoot: string, args: UploadArgs): Promise<UploadResult>;

package/dist/page/upload.js

@@ -0,0 +1,62 @@
+// `upload_file` — set files on a file `<input>`.
+//
+// Setting files on a file input is a common browser-test primitive that
+// otherwise forces agents into injecting `File`/`DataTransfer` via `eval_js`
+// (arbitrary JS). This drives Playwright's `locator.setInputFiles()` directly.
+// Gated by the off-by-default `file-io` capability — the slot reserved for
+// exactly this. Works on hidden inputs (Playwright handles `display:none`).
+//
+// Two file sources:
+//   - `content` — base64 inline; no filesystem read at all (preferred for
+//     agent-generated content).
+//   - `path` — resolved **inside `$BROWX_WORKSPACE` only**; a path escaping
+//     the workspace is rejected, keeping the no-trace / no-arbitrary-fs-read
+//     posture even with `file-io` enabled. Stage the file in the workspace.
+import { resolve, sep } from "node:path";
+import { statSync } from "node:fs";
+import { locatorFor } from "./locator.js";
+function targetSummary(t) {
+    if (t.ref)
+        return `ref ${t.ref}`;
+    if (t.selector)
+        return `selector ${t.selector}`;
+    return "(unknown)";
+}
+export async function uploadFile(page, refs, workspaceRoot, args) {
+    if (args.content !== undefined && args.path !== undefined) {
+        throw new Error("upload_file: pass exactly one of `content` (base64) or `path`");
+    }
+    if (args.content === undefined && args.path === undefined) {
+        throw new Error("upload_file: requires `content` (base64) or `path`");
+    }
+    const loc = locatorFor(page, refs, args.target);
+    const target = targetSummary(args.target);
+    if (args.content !== undefined) {
+        const name = args.name ?? "upload";
+        const mimeType = args.mimeType ?? "application/octet-stream";
+        const buffer = Buffer.from(args.content, "base64");
+        await loc.setInputFiles({ name, mimeType, buffer });
+        return {
+            ok: true,
+            mode: "content",
+            name,
+            bytes: buffer.length,
+            mimeType,
+            target,
+            fileCount: 1,
+        };
+    }
+    const resolved = resolve(workspaceRoot, args.path);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error("upload_file: `path` must resolve inside $BROWX_WORKSPACE — stage the file there, or use `content` (base64)");
+    }
+    await loc.setInputFiles(resolved);
+    let bytes = 0;
+    try {
+        bytes = statSync(resolved).size;
+    }
+    catch {
+        /* best-effort size */
+    }
+    return { ok: true, mode: "path", name: args.path, bytes, target, fileCount: 1 };
+}

package/dist/page/verify.d.ts

@@ -0,0 +1,63 @@
+import type { Page, CDPSession } from "playwright-core";
+import type { RefRegistry } from "./refs.js";
+import { findByRef } from "./snapshot.js";
+import { walk } from "./a11y.js";
+import { visibleRect } from "./bbox.js";
+import { type ActionTarget } from "./locator.js";
+import { type Predicate } from "../util/predicates.js";
+import type { FailureSource as FailureSourceBase } from "../util/failure.js";
+export type FailureSource = Extract<FailureSourceBase, "app" | "browxai">;
+export interface VerifyFailure {
+    /** `app` when the predicate didn't hold against the page's actual state;
+     *  `browxai` when the verify itself couldn't run (ref no longer in the
+     *  snapshot, selector matched nothing the helper could resolve, etc). */
+    source: FailureSource;
+    /** Stable kind label — `"visible"`, `"text-equals"`, `"value-equals"`,
+     *  `"count-equals"`, `"attribute-equals"`, predicate kind for `verify_predicate`. */
+    kind: string;
+    /** Human-readable description of what should have held. */
+    expected: string;
+    /** What we actually saw — the value/state that didn't match. */
+    actual: unknown;
+    /** Optional supporting context (matched-text fragment, the ref's role,
+     *  a count breakdown). Kept small so the result fits the token budget. */
+    evidence?: Record<string, unknown>;
+}
+export interface VerifyResult {
+    ok: boolean;
+    failure?: VerifyFailure;
+}
+/** Verify that the targeted element is visible (non-zero box, not
+ *  display:none/visibility:hidden, opacity > 0). `source:"app"` on miss. */
+export declare function verifyVisible(page: Page, refs: RefRegistry, target: ActionTarget): Promise<VerifyResult>;
+/** Verify that the targeted element's visible text matches. `exact:true` →
+ *  case-sensitive equality on the trimmed innerText. Default → case-insensitive
+ *  substring. `source:"app"` on miss. */
+export declare function verifyText(page: Page, refs: RefRegistry, target: ActionTarget, text: string, exact: boolean): Promise<VerifyResult>;
+/** Verify that the targeted input/textarea/contenteditable carries the given
+ *  value (strict equality after a defensive `String()`). `source:"app"` on
+ *  miss. */
+export declare function verifyValue(page: Page, refs: RefRegistry, target: ActionTarget, value: string): Promise<VerifyResult>;
+/** Verify that exactly `n` elements match the given selector (or visible-text
+ *  search). One of `selector` or `text` is required. `source:"app"` on miss. */
+export declare function verifyCount(page: Page, cdp: CDPSession, refs: RefRegistry, opts: {
+    selector?: string;
+    text?: string;
+    n: number;
+    testAttributes: string[];
+}): Promise<VerifyResult>;
+/** Verify that the targeted element's `attr` attribute equals `value`. When
+ *  `value` is undefined, this asserts the attribute is present (any value).
+ *  `source:"app"` on miss. */
+export declare function verifyAttribute(page: Page, refs: RefRegistry, target: ActionTarget, attr: string, value: string | undefined): Promise<VerifyResult>;
+/**
+ * Evaluate a fixed-vocabulary `Predicate` against caller-supplied data
+ * (typically an `ActionResult` + optional companion `snapshot` / `evidence`).
+ *
+ * NOT arbitrary JS: the engine accepts only `kind` values from the
+ * `Predicate` enum and `key` accessor strings starting with an allow-listed
+ * root segment. Adopters supply *data* (which key, which expected value);
+ * the *vocabulary* is owned server-side. See `src/util/predicates.ts`.
+ */
+export declare function verifyPredicate(predicate: Predicate, data: unknown): VerifyResult;
+export { findByRef, walk, visibleRect };