browxai 0.7.0

package/dist/helper/overlay-hide.js

@@ -0,0 +1,49 @@
+// Server-side overlay neutraliser. Dev-build chrome (HMR widgets, devtools
+// iframes), cookie/consent banners and similar overlays intercept coordinate
+// clicks and pollute the snapshot. Rather than have every agent hand-roll
+// node removal in `eval_js` each session, the operator declares the offending
+// selectors once (config `hideOverlaySelectors`) and the server injects a
+// CSS-only init script that neutralises them on every navigation.
+//
+// Non-destructive by design: a `<style>` rule sets `pointer-events:none;
+// display:none` — no node removal, no agent-supplied JS. The selectors come
+// from operator-managed config (config.json / set_config), never the page.
+import { log } from "../util/logging.js";
+const STYLE_ID = "__browx_overlay_hide";
+/** Build the init-script body for the given selectors. Selectors are embedded
+ *  as JSON string literals (no expression interpolation) and written via
+ *  `style.textContent` (not parsed as HTML), so a hostile selector can at
+ *  worst break its own CSS rule — it cannot escape into script. */
+export function buildOverlayHideScript(selectors) {
+    return `(() => {
+  var SELS = ${JSON.stringify(selectors)};
+  if (!SELS.length) return;
+  var css = SELS.map(function (s) {
+    return s + "{pointer-events:none !important;display:none !important;}";
+  }).join("\\n");
+  var ID = ${JSON.stringify(STYLE_ID)};
+  var inject = function () {
+    if (document.getElementById(ID)) return;
+    var st = document.createElement("style");
+    st.id = ID;
+    st.textContent = css;
+    (document.head || document.documentElement).appendChild(st);
+  };
+  inject();
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", inject);
+  }
+})();`;
+}
+/** Register the overlay-hide init script on a context and apply it to any
+ *  already-open pages. No-op when `selectors` is empty (feature off). */
+export async function applyOverlayHide(context, selectors) {
+    if (!selectors.length)
+        return;
+    const script = buildOverlayHideScript(selectors);
+    await context.addInitScript({ content: script });
+    for (const page of context.pages()) {
+        await page.evaluate(script).catch(() => undefined);
+    }
+    log.info("overlay-hide: active", { count: selectors.length });
+}

package/dist/helper/stealth.d.ts

@@ -0,0 +1,10 @@
+import type { BrowserContext } from "playwright-core";
+/** Build the page-side init script that applies the stealth patches. Pure —
+ *  takes no input, returns the script string. Wrapped in an IIFE so the
+ *  helpers don't leak into the page's globals. Idempotent: an early-return
+ *  guard skips re-application if it ran in the same realm. */
+export declare function buildStealthScript(): string;
+/** Register the stealth init script on a context and apply it to any
+ *  already-open pages. Mirrors the overlay-hide pattern: `addInitScript`
+ *  for future navigations + `page.evaluate` for the currently-loaded page. */
+export declare function applyStealth(context: BrowserContext): Promise<void>;

package/dist/helper/stealth.js

@@ -0,0 +1,88 @@
+// Stealth-mode init-script patches (capability `stealth`).
+//
+// Many sites detect Playwright/Puppeteer-driven browsers via a small set of
+// well-known fingerprint giveaways the automation framework leaves on the
+// page-side `navigator` / `window` objects. The most commonly-checked surface:
+//
+//   - `navigator.webdriver === true`               — the WebDriver protocol flag
+//   - `navigator.plugins.length === 0`             — headless / fresh-profile tell
+//   - `window.chrome` undefined / missing `runtime` — non-Chrome user-agent tell
+//   - `navigator.languages` empty                  — headless Chromium default
+//
+// What this module does: registers a per-context `addInitScript` that overrides
+// the above accessors BEFORE any page script runs. We do NOT bundle a
+// general-purpose anti-fingerprinting library (e.g. puppeteer-extra-stealth) —
+// that surface is vast and an arms race; the four patches above cover the
+// observed default detectors and are the conservative minimum.
+//
+// Posture: same class as `eval` / `network-body` / `secrets` / `extensions` —
+// off-by-default capability, loud-warned at boot. Legal/ToS exposure is real:
+// many sites' terms of service explicitly prohibit "circumventing automated-
+// access detection". The loud warning names that explicitly.
+//
+// Non-destructive within the running page: `Object.defineProperty` with
+// `configurable:true` so a page that wants to inspect or replace the override
+// still can (we're spoofing detection, not lying to legitimate code).
+import { log } from "../util/logging.js";
+const SCRIPT_TAG = "__browx_stealth";
+/** Build the page-side init script that applies the stealth patches. Pure —
+ *  takes no input, returns the script string. Wrapped in an IIFE so the
+ *  helpers don't leak into the page's globals. Idempotent: an early-return
+ *  guard skips re-application if it ran in the same realm. */
+export function buildStealthScript() {
+    return `(() => {
+  if (window.${SCRIPT_TAG}) return;
+  Object.defineProperty(window, ${JSON.stringify(SCRIPT_TAG)}, { value: true, configurable: true });
+  // 1. navigator.webdriver — the load-bearing Playwright fingerprint.
+  try {
+    Object.defineProperty(navigator, "webdriver", {
+      get: function () { return false; },
+      configurable: true,
+    });
+  } catch (e) { /* best-effort */ }
+  // 2. navigator.plugins — headless / fresh-profile tell. Surface a
+  //    plausible non-empty PluginArray-like (length 1 with a "Chrome PDF
+  //    Viewer" entry mirrors real Chrome defaults).
+  try {
+    var fake = [{ name: "Chrome PDF Viewer", filename: "internal-pdf-viewer", description: "Portable Document Format" }];
+    Object.defineProperty(navigator, "plugins", {
+      get: function () { return fake; },
+      configurable: true,
+    });
+  } catch (e) { /* best-effort */ }
+  // 3. navigator.languages — headless Chromium emits []; real browsers
+  //    populate at least the page-locale entry.
+  try {
+    if (!navigator.languages || navigator.languages.length === 0) {
+      Object.defineProperty(navigator, "languages", {
+        get: function () { return ["en-US", "en"]; },
+        configurable: true,
+      });
+    }
+  } catch (e) { /* best-effort */ }
+  // 4. window.chrome — non-Chrome UA tell. Many detectors check
+  //    \`typeof window.chrome === "object" && !!window.chrome.runtime\`.
+  try {
+    if (!window.chrome) {
+      Object.defineProperty(window, "chrome", {
+        value: { runtime: {} },
+        configurable: true,
+        writable: true,
+      });
+    } else if (!window.chrome.runtime) {
+      try { window.chrome.runtime = {}; } catch (e) { /* best-effort */ }
+    }
+  } catch (e) { /* best-effort */ }
+})();`;
+}
+/** Register the stealth init script on a context and apply it to any
+ *  already-open pages. Mirrors the overlay-hide pattern: `addInitScript`
+ *  for future navigations + `page.evaluate` for the currently-loaded page. */
+export async function applyStealth(context) {
+    const script = buildStealthScript();
+    await context.addInitScript({ content: script });
+    for (const page of context.pages()) {
+        await page.evaluate(script).catch(() => undefined);
+    }
+    log.info("stealth: active (navigator.webdriver / plugins / languages / chrome patches engaged)");
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import "./tools/tool-metadata.js";
+export { createServer, NAME, VERSION } from "./server.js";
+export type { StartOptions } from "./server.js";
+export { resolveWorkspace } from "./util/workspace.js";
+export type { BrowserSession, SessionOptions, SessionMode } from "./session/types.js";
+export { createBrowxai, NOT_EXPOSED_ERROR, resolveEndpointPath } from "./sdk/index.js";
+export type { BrowxaiArgs, BrowxaiClient, BrowxaiContentItem, BrowxaiResult, BrowxaiSdkOptions, } from "./sdk/index.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+// Public exports. Most users want the CLI (`browxai` bin) — see cli.ts. This module
+// is for embedding the MCP server programmatically or pulling in types.
+// RFC 0004 P2: install the tool-metadata collector so the derived `TOOL_CAPABILITY`
+// / `DEEP_TOOLS` maps populate for any package consumer (notably the SDK client's
+// capability gate, which reads `TOOL_CAPABILITY` without first building a server).
+// Importing this side-effecting module is the composition-root install point; the
+// collection is cached, so loading it here is cheap and idempotent.
+import "./tools/tool-metadata.js";
+export { createServer, NAME, VERSION } from "./server.js";
+export { resolveWorkspace } from "./util/workspace.js";
+// Typed SDK surface — see src/sdk/types.ts. Importing this from
+// `browxai` gives consumers a programmatic driver over the same
+// tool registry the MCP path exposes, with identical capability gating and
+// identical egress hygiene.
+export { createBrowxai, NOT_EXPOSED_ERROR, resolveEndpointPath } from "./sdk/index.js";

package/dist/page/a11y.d.ts

@@ -0,0 +1,81 @@
+import type { CDPSession } from "playwright-core";
+import { RefRegistry } from "./refs.js";
+export declare const MAX_WALK_DEPTH = 2000;
+export interface A11yNode {
+    ref: string;
+    role: string;
+    name?: string;
+    value?: string;
+    /** CDP node IDs to resolve back into actions / element handles. */
+    backendDOMNodeId?: number;
+    /** Test-attribute value if we found one (`data-testid` etc.). */
+    testId?: string;
+    /** Attribute *name* that yielded `testId` — preserves which convention matched. */
+    testIdAttr?: string;
+    /** Where this node came from. Default = "a11y" for the CDP-a11y path; "dom" for the
+     *  DOM-walk fallback (see dom-walk.ts) and "both" when a node was independently
+     *  discovered by both paths. #7 / #8 plumbing. */
+    source?: "a11y" | "dom" | "both";
+    /** Tag name (DOM-walk only — informational for the agent). */
+    tag?: string;
+    /**  selectorHint tier-4 source: HTML `id=` attribute if present. */
+    id?: string;
+    /**  selectorHint tier-3 source: trimmed text content (truncated, single-line),
+     *  set when distinct from `name` and stable-looking. DOM-walk fills this in. */
+    text?: string;
+    /** State flags as reported by CDP (selected subset — see fmtState). */
+    disabled?: boolean;
+    checked?: boolean | "mixed";
+    pressed?: boolean | "mixed";
+    selected?: boolean;
+    expanded?: boolean;
+    focused?: boolean;
+    /** Structural neighbourhood when this node lives inside a repeated container
+     *  (table row, listitem, repeated card). Populated by `annotateStructuralContext`
+     *  during snapshot composition; null when the node isn't in a recognised
+     *  repeated structure. */
+    context?: StructuralContext;
+    children: A11yNode[];
+}
+/**
+ * Structural neighbourhood metadata for nodes living in repeated layouts.
+ * Lets callers answer "what row/column is this in?" without re-walking the
+ * tree themselves. Detection is generic — driven by semantic ARIA roles
+ * (`table` / `row` / `cell` / `columnheader`, `list` / `listitem`, etc.),
+ * not by app-specific markers.
+ */
+export interface StructuralContext {
+    /** Role of the collection this node sits inside. Typical values: `table`,
+     *  `grid`, `list`, `feed`, or `<row-role>-list` when the parent role isn't
+     *  one of the canonical collection roles. */
+    collection: string;
+    /** Best-effort identifier for the row/item — the first non-empty visible
+     *  text within the row, capped. Stable enough to disambiguate sibling rows
+     *  by display label. */
+    rowKey?: string;
+    /** Column header text (from the table's header row, aligned by cell index).
+     *  Populated only for semantic-table / grid descendants. */
+    column?: string;
+    /** Concatenated visible text of the entire row, capped at 200 chars.
+     *  Cheap "what does this row say overall?" probe for the caller. */
+    rowText?: string;
+}
+/**
+ * Get the cleaned a11y tree for the current page, with refs assigned through `refs`.
+ * Refs are *stable* across calls: a node that persists keeps its `eN`.
+ *
+ * `testIdAttributes` is the list of HTML attributes to read off the DOM node as
+ * the node's `testId` (preference-order-friendly for `find()`'s selectorHint).
+ * Sourced from `BROWX_TEST_ATTRIBUTES` via `resolveConfig()`; defaults to
+ * `["data-testid", "data-test", "data-cy", "data-qa"]`. Order-sensitive: the
+ * **first** match on a node wins. The matched attribute *name* is preserved on
+ * the node as `testIdAttr` so selectorHint can emit the right selector.
+ */
+export declare function getA11yTree(cdp: CDPSession, refs: RefRegistry, testIdAttributes?: string[]): Promise<A11yNode | null>;
+/**
+ * Walk a tree depth-first, yielding (node, depth) pairs. Used by serialiser + find().
+ */
+export declare function walk(root: A11yNode): Generator<{
+    node: A11yNode;
+    depth: number;
+}>;

package/dist/page/a11y.js

@@ -0,0 +1,219 @@
+// CDP-backed accessibility-tree extraction. playwright-core dropped page.accessibility
+// so we go via CDP (Accessibility.getFullAXTree) directly. The shape we expose is
+// agentic-first: a tidy tree with role/name/value/state and refs assigned by stable
+// element key (see refs.ts), plus a `walk()` helper for serialiser/find() reuse.
+import { elementKey } from "./refs.js";
+// L7 (bounded everything) — the a11y tree-walk depth cap. The audit flagged
+// `walk` as iterative (an explicit stack, so no native stack-overflow risk) but
+// carrying NO declared depth cap: a pathological tree was bounded only by memory.
+// This makes the bound explicit and tested. 2000 is far beyond any real
+// accessibility tree (a deeply-nested SPA is rarely past ~60 levels), so it never
+// trips in practice — it is a containment ceiling against an adversarial /
+// malformed tree, matching the `secrets.ts` `depth > 8` exemplar one layer up.
+// Nodes BELOW the cap are simply not descended into (the tree is truncated, not
+// rejected), so the walk always terminates within `MAX_WALK_DEPTH` levels.
+export const MAX_WALK_DEPTH = 2000;
+/**
+ * CDP returns AX node values as `{ type, value: unknown }`. In practice the
+ * `value` is a primitive (string | number | boolean | null), but the CDP type
+ * is `any` and downstream code consumes a `string | undefined`. Coerce by
+ * type so a hypothetical structured value renders as JSON rather than
+ * `[object Object]`.
+ */
+/** Map the CDP AX boolean/tri-state properties onto the node. The two tri-state
+ *  props (`checked`/`pressed`) carry `boolean | "mixed"`; the rest are plain
+ *  booleans. Each property is independent, so a lookup table keeps the cyclomatic
+ *  complexity flat. */
+const BOOL_AX_PROPS = ["disabled", "selected", "expanded", "focused"];
+const TRISTATE_AX_PROPS = ["checked", "pressed"];
+function applyAxProperties(node, properties) {
+    for (const p of properties) {
+        const v = p.value?.value;
+        if (BOOL_AX_PROPS.includes(p.name)) {
+            node[p.name] = !!v;
+        }
+        else if (TRISTATE_AX_PROPS.includes(p.name)) {
+            node[p.name] = v;
+        }
+    }
+}
+function stringifyAxValue(v) {
+    if (v === undefined)
+        return undefined;
+    if (v === null)
+        return "null";
+    switch (typeof v) {
+        case "string":
+            return v;
+        case "number":
+        case "boolean":
+        case "bigint":
+            return String(v);
+        case "symbol":
+            return v.toString();
+        default:
+            return JSON.stringify(v);
+    }
+}
+/**
+ * Get the cleaned a11y tree for the current page, with refs assigned through `refs`.
+ * Refs are *stable* across calls: a node that persists keeps its `eN`.
+ *
+ * `testIdAttributes` is the list of HTML attributes to read off the DOM node as
+ * the node's `testId` (preference-order-friendly for `find()`'s selectorHint).
+ * Sourced from `BROWX_TEST_ATTRIBUTES` via `resolveConfig()`; defaults to
+ * `["data-testid", "data-test", "data-cy", "data-qa"]`. Order-sensitive: the
+ * **first** match on a node wins. The matched attribute *name* is preserved on
+ * the node as `testIdAttr` so selectorHint can emit the right selector.
+ */
+export async function getA11yTree(cdp, refs, testIdAttributes = ["data-testid", "data-test", "data-cy", "data-qa"]) {
+    // Enable is idempotent; safe to call repeatedly.
+    await cdp.send("Accessibility.enable");
+    const { nodes } = (await cdp.send("Accessibility.getFullAXTree"));
+    if (!nodes.length)
+        return null;
+    const byId = new Map(nodes.map((n) => [n.nodeId, n]));
+    const root = nodes.find((n) => !n.parentId || !byId.has(n.parentId)) ?? nodes[0];
+    // We resolve testId attributes per-node lazily — only the ones that have a
+    // backendDOMNodeId and are roles we care about (interactives). For we
+    // hold off on a batched DOM.getAttributes call and just attach testIds when
+    // they show up as CDP properties; a future cycle can switch to a batch fetch
+    // if the attribute coverage isn't enough.
+    const convert = (raw, path) => {
+        if (raw.ignored)
+            return null;
+        const role = raw.role?.value ?? "generic";
+        const name = raw.name?.value;
+        const node = {
+            ref: "", // filled in below
+            role,
+            name,
+            value: stringifyAxValue(raw.value?.value),
+            backendDOMNodeId: raw.backendDOMNodeId,
+            children: [],
+        };
+        applyAxProperties(node, raw.properties ?? []);
+        // testId attaches later in enrichTestIds if we batch-fetch attributes.
+        node.ref = refs.forKey(elementKey({ role, name, path, testId: node.testId }), {
+            role,
+            name,
+            testId: node.testId,
+            source: "a11y",
+        });
+        let i = 0;
+        for (const cid of raw.childIds ?? []) {
+            const c = byId.get(cid);
+            if (!c)
+                continue;
+            const cv = convert(c, `${path}/${c.role?.value ?? "generic"}[${i}]`);
+            if (cv)
+                node.children.push(cv);
+            i++;
+        }
+        return node;
+    };
+    const tree = convert(root, root.role?.value ?? "root");
+    if (!tree)
+        return null;
+    await enrichTestIds(cdp, tree, testIdAttributes, refs);
+    return tree;
+}
+/**
+ * Walk a tree depth-first, yielding (node, depth) pairs. Used by serialiser + find().
+ */
+export function* walk(root) {
+    const stack = [{ node: root, depth: 0 }];
+    while (stack.length) {
+        const next = stack.pop();
+        yield next;
+        // L7: bounded depth — children below MAX_WALK_DEPTH are not pushed, so a
+        // pathological tree is truncated at the cap rather than walked to exhaustion.
+        // Real trees are orders of magnitude shallower, so this never truncates in
+        // practice; it is the containment ceiling the bounded-resource test pins.
+        if (next.depth >= MAX_WALK_DEPTH)
+            continue;
+        for (let i = next.node.children.length - 1; i >= 0; i--) {
+            stack.push({ node: next.node.children[i], depth: next.depth + 1 });
+        }
+    }
+}
+/**
+ * For nodes with a `backendDOMNodeId`, read off the configured test-attribute(s) in
+ * preference order via CDP, attaching the first match to `node.testId`. Also
+ * re-keys the node's ref through `refs` so the testId is part of the stable key
+ * (testId-bearing nodes keep their refs across snapshots even if neighbourhood text
+ * shifts).
+ *
+ * Batched in one `DOM.getDocument` walk would be cheaper, but per-node
+ * `DOM.resolveNode`+`DOM.describeNode` is simpler and doesn't need to be
+ * perf-tuned. If this dominates snapshot latency, switch to a batched approach.
+ */
+async function enrichTestIds(cdp, root, attrs, refs) {
+    for (const { node } of walk(root)) {
+        if (node.backendDOMNodeId === undefined)
+            continue;
+        // Only enrich roles the agent's likely to act on (interactive / structural).
+        if (!INTERACTIVE_ROLES.has(node.role) && !STRUCTURAL_ROLES.has(node.role))
+            continue;
+        try {
+            const { attributes } = await cdp.send("DOM.getAttributes", {
+                nodeId: node.backendDOMNodeId,
+            });
+            // attributes is a flat ["name", "value", "name", "value", ...] array.
+            const attrMap = new Map();
+            for (let i = 0; i < attributes.length; i += 2) {
+                attrMap.set(attributes[i], attributes[i + 1] ?? "");
+            }
+            for (const a of attrs) {
+                const v = attrMap.get(a);
+                if (v) {
+                    node.testId = v;
+                    node.testIdAttr = a;
+                    // Refresh the registry's locator inputs so action tools can resolve
+                    // the ref back to a data-testid-bearing Playwright locator.
+                    refs.augmentLocator(node.ref, { testId: node.testId, testIdAttr: a });
+                    break;
+                }
+            }
+        }
+        catch {
+            // Node may be detached / not in DOM tree; that's fine, no testId then.
+        }
+    }
+}
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "link",
+    "textbox",
+    "searchbox",
+    "combobox",
+    "checkbox",
+    "radio",
+    "switch",
+    "slider",
+    "spinbutton",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "tab",
+    "treeitem",
+    "listbox",
+]);
+const STRUCTURAL_ROLES = new Set([
+    "dialog",
+    "alertdialog",
+    "navigation",
+    "main",
+    "form",
+    "search",
+    "region",
+    "tablist",
+    "menu",
+    "menubar",
+    "tree",
+    "grid",
+    "table",
+    "alert",
+    "status",
+]);

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

@@ -0,0 +1,64 @@
+import type { ActionContext, ActionResult } from "./actionresult.js";
+import type { RefRegistry } from "./refs.js";
+import type { SafariSessionHandle } from "../engine/index.js";
+import * as actions from "./actions.js";
+/** The action capability port. One instance wraps one session's engine handle;
+ *  the methods carry no engine type, so the handlers above this seam are
+ *  engine-blind. Mirrors the SnapshotSubstrate / NetworkSubstrate shape. */
+export interface ActionSubstrate {
+    readonly engine: string;
+    navigate(args: actions.NavigateArgs): Promise<ActionResult>;
+    click(args: actions.ClickArgs): Promise<ActionResult>;
+    fill(args: actions.FillArgs): Promise<ActionResult>;
+    press(args: actions.PressArgs): Promise<ActionResult>;
+    hover(args: actions.HoverArgs): Promise<ActionResult>;
+    select(args: actions.SelectArgs): Promise<ActionResult>;
+    scroll(args: actions.ScrollArgs): Promise<ActionResult>;
+    goBack(args: actions.GoBackArgs): Promise<ActionResult>;
+    goForward(args: actions.GoForwardArgs): Promise<ActionResult>;
+    chooseOption(args: actions.ChooseOptionArgs): Promise<ActionResult>;
+    setViewport(args: actions.SetViewportArgs): Promise<ActionResult>;
+    waitFor(args: actions.WaitForArgs): Promise<ActionResult>;
+}
+/** Playwright engines — delegates each action to the existing `actions.*` over a
+ *  freshly-built ActionContext (the `ctx` thunk captures the session entry, the
+ *  same per-call construction the handlers did before this seam). No behaviour
+ *  change. */
+export declare class PlaywrightActionSubstrate implements ActionSubstrate {
+    private readonly ctx;
+    readonly engine: string;
+    constructor(ctx: () => ActionContext, engine?: string);
+    navigate(args: actions.NavigateArgs): Promise<ActionResult>;
+    click(args: actions.ClickArgs): Promise<ActionResult>;
+    fill(args: actions.FillArgs): Promise<ActionResult>;
+    press(args: actions.PressArgs): Promise<ActionResult>;
+    hover(args: actions.HoverArgs): Promise<ActionResult>;
+    select(args: actions.SelectArgs): Promise<ActionResult>;
+    scroll(args: actions.ScrollArgs): Promise<ActionResult>;
+    goBack(args: actions.GoBackArgs): Promise<ActionResult>;
+    goForward(args: actions.GoForwardArgs): Promise<ActionResult>;
+    chooseOption(args: actions.ChooseOptionArgs): Promise<ActionResult>;
+    setViewport(args: actions.SetViewportArgs): Promise<ActionResult>;
+    waitFor(args: actions.WaitForArgs): Promise<ActionResult>;
+}
+/** Safari — the WebDriver-Classic action path. The curated subset is real;
+ *  everything else refuses cleanly here (the gating is in the adapter, not the
+ *  handler). */
+export declare class SafariActionSubstrate implements ActionSubstrate {
+    private readonly handle;
+    private readonly refs;
+    readonly engine = "safari";
+    constructor(handle: SafariSessionHandle, refs: RefRegistry);
+    navigate(args: actions.NavigateArgs): Promise<ActionResult>;
+    click(args: actions.ClickArgs): Promise<ActionResult>;
+    fill(args: actions.FillArgs): Promise<ActionResult>;
+    press(args: actions.PressArgs): Promise<ActionResult>;
+    hover(): Promise<ActionResult>;
+    select(): Promise<ActionResult>;
+    scroll(): Promise<ActionResult>;
+    goBack(): Promise<ActionResult>;
+    goForward(): Promise<ActionResult>;
+    chooseOption(): Promise<ActionResult>;
+    setViewport(): Promise<ActionResult>;
+    waitFor(): Promise<ActionResult>;
+}

package/dist/page/action-substrate.js

@@ -0,0 +1,118 @@
+// The ActionSubstrate interface — the engine-agnostic seam beneath the action
+// tools (navigate / click / fill / press / hover / select / scroll / …). It is
+// the action side of the engine-agnostic seam: a tool handler asks a substrate
+// to perform an action and gets back the universal `ActionResult`; an engine-specific
+// implementation does the work. The handler never names Playwright, CDP, or an
+// engine — it calls `actionsFor(e).click(args)`, the same shape as
+// `snapshotSubstrateFor(e.session).compose(...)`.
+//
+// Dependency direction (architecture doctrine §1): tool handler → ActionSubstrate
+// (this interface) → implementation → Playwright | safaridriver. Two impls today:
+//   - PlaywrightActionSubstrate (chromium / firefox / webkit / android): wraps the
+//     existing `actions.*` over a Playwright ActionContext — byte-identical to the
+//     pre-seam path, so the four engines' keystones stay green unchanged.
+//   - SafariActionSubstrate (safari): wraps `safari-actions.*` over the WebDriver
+//     Classic client (no Playwright Page). The curated subset (navigate/click/
+//     fill/press) is real; the rest refuse cleanly IN THE ADAPTER — so the gating
+//     lives here, not as `if (engine === "safari")` branches scattered through the
+//     handlers.
+import * as actions from "./actions.js";
+import { safariNavigate, safariClick, safariFill, safariPress, safariUnsupportedAction, } from "./safari-actions.js";
+/** Playwright engines — delegates each action to the existing `actions.*` over a
+ *  freshly-built ActionContext (the `ctx` thunk captures the session entry, the
+ *  same per-call construction the handlers did before this seam). No behaviour
+ *  change. */
+export class PlaywrightActionSubstrate {
+    ctx;
+    engine;
+    constructor(ctx, engine = "chromium") {
+        this.ctx = ctx;
+        this.engine = engine;
+    }
+    navigate(args) {
+        return actions.navigate(this.ctx(), args);
+    }
+    click(args) {
+        return actions.click(this.ctx(), args);
+    }
+    fill(args) {
+        return actions.fill(this.ctx(), args);
+    }
+    press(args) {
+        return actions.press(this.ctx(), args);
+    }
+    hover(args) {
+        return actions.hover(this.ctx(), args);
+    }
+    select(args) {
+        return actions.select(this.ctx(), args);
+    }
+    scroll(args) {
+        return actions.scroll(this.ctx(), args);
+    }
+    goBack(args) {
+        return actions.goBack(this.ctx(), args);
+    }
+    goForward(args) {
+        return actions.goForward(this.ctx(), args);
+    }
+    chooseOption(args) {
+        return actions.chooseOption(this.ctx(), args);
+    }
+    setViewport(args) {
+        return actions.setViewport(this.ctx(), args);
+    }
+    waitFor(args) {
+        return actions.waitFor(this.ctx(), args);
+    }
+}
+/** Safari — the WebDriver-Classic action path. The curated subset is real;
+ *  everything else refuses cleanly here (the gating is in the adapter, not the
+ *  handler). */
+export class SafariActionSubstrate {
+    handle;
+    refs;
+    engine = "safari";
+    constructor(handle, refs) {
+        this.handle = handle;
+        this.refs = refs;
+    }
+    navigate(args) {
+        return safariNavigate(this.handle, args.url);
+    }
+    click(args) {
+        return safariClick(this.handle, this.refs, args.target);
+    }
+    fill(args) {
+        return safariFill(this.handle, this.refs, args.target, args.value);
+    }
+    press(args) {
+        return args.target
+            ? safariPress(this.handle, this.refs, args.target, args.key)
+            : Promise.resolve(safariUnsupportedAction("press"));
+    }
+    hover() {
+        return Promise.resolve(safariUnsupportedAction("hover"));
+    }
+    select() {
+        return Promise.resolve(safariUnsupportedAction("select"));
+    }
+    scroll() {
+        return Promise.resolve(safariUnsupportedAction("scroll"));
+    }
+    goBack() {
+        return Promise.resolve(safariUnsupportedAction("goBack"));
+    }
+    goForward() {
+        return Promise.resolve(safariUnsupportedAction("goForward"));
+    }
+    chooseOption() {
+        return Promise.resolve(safariUnsupportedAction("chooseOption"));
+    }
+    setViewport() {
+        return Promise.resolve(safariUnsupportedAction("setViewport"));
+    }
+    waitFor() {
+        return Promise.resolve(safariUnsupportedAction("waitFor"));
+    }
+}