browxai 0.7.0

package/dist/engine/tool-gate.js

@@ -0,0 +1,226 @@
+// The ENGINE-dimension tool gate. It composes with the
+// per-tool capability system in util/capabilities.ts (which answers "is this
+// tool's CAPABILITY in the active set?") by answering a second, orthogonal
+// question: "can the ENGINE backing this session run this tool at all?"
+//
+// The classification covers the ~19 CDP-hard tools plus the tools whose
+// Playwright Firefox lane has no live equivalent. All of them need the raw-CDP
+// escape hatch. On an engine that declares `deep: false` (Firefox — measured:
+// `newCDPSession` throws) they structured-refuse with a hint naming the engine,
+// exactly like the
+// `pdf_save`-on-BYOB and `extensions`-on-incognito refusals already shipped —
+// not by letting `requireCdp` throw an opaque error mid-call.
+//
+// Three tools the critic re-resolved per the spec facts, reflected in
+// the per-engine reason map below:
+//   - pdf_save        → `browsingContext.print` exists, but Playwright's
+//                       `page.pdf()` throws off-Chromium (measured: "PDF
+//                       generation is only supported for Headless Chromium").
+//                       Gated on Firefox with a Firefox-specific hint — it does
+//                       NOT crash the session.
+//   - network_emulate → spec'd over BiDi (`emulation.setNetworkConditions`) but
+//                       UNIMPLEMENTED in this Playwright/Juggler build → gated,
+//                       reason "refuse-pending".
+//   - set_user_agent  → BiDi `emulation.setUserAgentOverride` is spec'd, but the
+//                       Playwright Juggler lane has NO live UA setter (measured:
+//                       `context.setUserAgent` / `page.setUserAgent` are
+//                       undefined) and the current impl uses CDP
+//                       `Network.setUserAgentOverride` → gated on Firefox, with a
+//                       hint pointing at context-creation UA + the BiDi lane.
+import { capabilitiesFor } from "./capabilities.js";
+import { engineCapabilities } from "./capability-registry.js";
+const DEEP_TOOLS_SET = new Set();
+/** Record that a tool needs the raw-CDP (`deep`) escape hatch, from its colocated
+ *  `host.register({ deep: true })` metadata (RFC 0004 P2). The only writer of the
+ *  derived `DEEP_TOOLS` set. Idempotent. */
+export function declareDeepTool(tool) {
+    DEEP_TOOLS_SET.add(tool);
+}
+/** Lazy-collection seam (RFC 0004 P2), mirroring `installToolMetadataCollector`
+ *  in capabilities.ts: the tools layer installs a collector that runs the
+ *  registration metadata once and populates this set. `tool-gate.ts` (engine
+ *  layer) cannot import the tools layer, so the dependency is inverted here. */
+let deepToolsCollector;
+let deepToolsLoaded = false;
+/** True while the collector is mid-run — a re-entrant `DEEP_TOOLS` read during
+ *  collection tolerates the partial set without tripping the fail-safe. */
+let deepToolsCollecting = false;
+export function installDeepToolsCollector(collect) {
+    deepToolsCollector = collect;
+    deepToolsLoaded = false;
+}
+function ensureDeepToolsLoaded() {
+    if (deepToolsLoaded || deepToolsCollector === undefined)
+        return;
+    deepToolsLoaded = true;
+    deepToolsCollecting = true;
+    try {
+        deepToolsCollector();
+    }
+    finally {
+        deepToolsCollecting = false;
+    }
+}
+/**
+ * D1 fail-safe (RFC 0004 P2, SECURITY-CRITICAL): the ENGINE gate must NEVER fail
+ * OPEN. `assertEngineSupports` reads `DEEP_TOOLS.has(tool)` — an empty,
+ * unbootstrapped set makes EVERY deep tool look cross-browser, so
+ * `assertEngineSupports("perf_start", "firefox")` returns null (un-gated) when
+ * the tools-layer bootstrap never ran. Rather than silently un-gate, throw a
+ * structured error. The guaranteed bootstrap (`tool-metadata.ts`, reached by
+ * every real entry point) keeps this from firing in production; this is the
+ * backstop. Suppressed only during collection (the collector's own read sees a
+ * partial set legitimately).
+ */
+function assertEngineGateBootstrapped() {
+    if (DEEP_TOOLS_SET.size > 0 || deepToolsCollecting)
+        return;
+    throw new Error("browxai engine gate read before the tool-metadata bootstrap ran: the derived " +
+        "DEEP_TOOLS set is empty and no collector was installed. Refusing to fail OPEN " +
+        "(which would let every CDP-deep tool run on a non-deep engine). Import the package " +
+        'entry ("browxai") or call createServer before reading the engine gate. (RFC 0004 P2 / D1.)');
+}
+/** Tools that require the raw-CDP (`deep`) escape hatch and therefore cannot run
+ *  on an engine that declares `deep: false`. DERIVED (RFC 0004 P2 / D2) from each
+ *  tool's `host.register({ deep: true })` metadata; any access drives the lazy
+ *  collection. A `Proxy` over the live `Set` so membership, `.size`, and
+ *  iteration all see the derived contents (and the `ReadonlySet<string>` type is
+ *  inferred from the target, not hand-rolled). */
+/** The membership / size / iteration surfaces an external consumer reads to
+ *  answer "is this an engine-gated tool?". A read of one of these on an empty
+ *  unbootstrapped set is the fail-open hazard, so they run the D1 fail-safe;
+ *  internal/other property reads (Symbol.toStringTag, etc.) pass through. */
+const DEEP_TOOLS_GATE_READS = new Set([
+    "has",
+    "size",
+    "keys",
+    "values",
+    "entries",
+    "forEach",
+    Symbol.iterator,
+]);
+export const DEEP_TOOLS = new Proxy(DEEP_TOOLS_SET, {
+    get(target, prop) {
+        ensureDeepToolsLoaded();
+        if (DEEP_TOOLS_GATE_READS.has(prop))
+            assertEngineGateBootstrapped();
+        // Read off the real Set (not via the Proxy receiver): `size` and the iterator
+        // methods touch internal slots and throw on an incompatible receiver, and the
+        // methods must keep `this` bound to the backing Set.
+        const value = target[prop];
+        return typeof value === "function"
+            ? value.bind(target)
+            : value;
+    },
+});
+/**
+ * The pre-P2 hand-maintained `DEEP_TOOLS` block, retained verbatim BELOW as a
+ * documentation appendix — the per-tool rationale (which CDP surface each gates,
+ * the three critic-re-resolved tools) is preserved, even though the live
+ * membership now derives from each `host.register({ deep: true })` call. This
+ * block is comment-only. (Reference — not the source of truth.)
+ *
+ * export const DEEP_TOOLS: ReadonlySet<string> = new Set<string>([
+ *   // perf / tracing (CDP `Tracing.*`) — Chrome trace-event format, engine-specific
+ *   "perf_start",
+ *   "perf_stop",
+ *   "perf_insights",
+ *   "perf_audit",
+ *   "layout_thrash_trace",
+ *   // coverage (CDP `Profiler.*` / `CSS.*RuleUsageTracking`) — V8/Blink-specific
+ *   "coverage_start",
+ *   "coverage_stop",
+ *   // heap (CDP `HeapProfiler.*`) — V8 `.heapsnapshot` format
+ *   "heap_snapshot",
+ *   "heap_retainers",
+ *   "memory_diff",
+ *   // CPU throttle (CDP `Emulation.setCPUThrottlingRate`) — Blink-only
+ *   "cpu_emulate",
+ *   // network throttle — `emulation.setNetworkConditions` spec'd over BiDi but
+ *   // not implemented in this Playwright build (reason: refuse-pending)
+ *   "network_emulate",
+ *   // Service-Worker fetch interception (CDP `Fetch.*` on the SW target)
+ *   "sw_intercept_fetch",
+ *   "sw_unintercept_fetch",
+ *   // virtual time clock (CDP `Emulation.setVirtualTimePolicy`)
+ *   "clock",
+ *   // Chromium extension management (launch flags + CDP) — no Playwright Firefox API
+ *   "extensions_install",
+ *   "extensions_list",
+ *   "extensions_reload",
+ *   "extensions_trigger",
+ *   "extensions_uninstall",
+ *   // print to PDF — Playwright `page.pdf()` throws off Headless Chromium (measured)
+ *   "pdf_save",
+ *   // live locale / timezone / UA override (CDP `Emulation.*` / `Network.*`) —
+ *   // Playwright bakes these at context creation; no live off-Chromium setter
+ *   "set_locale",
+ *   "set_timezone",
+ *   "set_user_agent",
+ *   // coordinate-space wheel + the touch/gesture family (CDP `Input.dispatch*`)
+ *   "mouse_wheel",
+ *   "touch_start",
+ *   "touch_move",
+ *   "touch_end",
+ *   "gesture_pinch",
+ *   "gesture_swipe",
+ *   // closed-shadow piercing — CDP `DOM.getDocument({pierce:true})` is the only
+ *   // automation-protocol path into closed shadow roots; no off-Chromium
+ *   // equivalent (the one true feature-level loss). The open-shadow
+ *   // half is portable, but the tool's headline (closed-shadow introspection) is
+ *   // CDP-bound, so the whole tool gates off Chromium.
+ *   "shadow_trees",
+ * ]);
+ */
+/** Per-tool reason fragment appended to the refusal hint. Most tools share the
+ *  generic "needs raw CDP" reason; the three the critic re-resolved carry a
+ *  more specific note so the agent knows the per-engine path (or its absence). */
+const TOOL_REASON = {
+    network_emulate: "Link-condition throttling is spec'd over WebDriver BiDi " +
+        "(`emulation.setNetworkConditions`) but not yet implemented in this Playwright build " +
+        "— refuse-pending. Route-level `delayMs` approximations still work cross-engine.",
+    set_user_agent: "Playwright has no live user-agent setter off Chromium (the current path uses " +
+        "CDP `Network.setUserAgentOverride`). Bake the UA at session creation instead: " +
+        '`open_session({ device: { userAgent: "…" } })`. Live BiDi UA override ' +
+        "(`emulation.setUserAgentOverride`) arrives with the stock-Firefox BiDi lane.",
+    pdf_save: "Playwright `page.pdf()` is Headless-Chromium-only and throws on Firefox " +
+        "(`browsingContext.print` over BiDi is the eventual path). Open a chromium session to print.",
+    set_locale: "Live locale override uses CDP `Emulation.setLocaleOverride`. Bake it at session " +
+        "creation (`open_session({ locale })`) or use a chromium session for mid-session override.",
+    set_timezone: "Live timezone override uses CDP `Emulation.setTimezoneOverride`. Bake it at session " +
+        "creation (`open_session({ timezone })`) or use a chromium session for mid-session override.",
+};
+const GENERIC_REASON = "This tool needs the raw-CDP escape hatch (perf / coverage / heap / CPU+network " +
+    "throttle / SW interception / virtual clock / extensions / CDP input dispatch), which " +
+    "exists only on chromium. These tools are gated, not ported, per engine.";
+/** Returns a structured refusal when `tool` cannot run on `engine`, else null.
+ *  Null is the fast path on chromium (the only engine with `deep`) and on every
+ *  cross-browser tool regardless of engine — a single Set lookup + a capability
+ *  read, no allocation on the supported path. */
+export function assertEngineSupports(tool, engine) {
+    // D1 fail-safe FIRST: a `DEEP_TOOLS.has` on an empty unbootstrapped set returns
+    // false for every tool, so the early `return null` below would un-gate the
+    // whole engine matrix. Assert the gate is bootstrapped before trusting the
+    // membership read. (`DEEP_TOOLS.has` drives the lazy collection.)
+    ensureDeepToolsLoaded();
+    assertEngineGateBootstrapped();
+    if (!DEEP_TOOLS.has(tool))
+        return null;
+    // Prefer the EngineRegistry's capability record (RFC 0004 P1) — it is the source
+    // of truth post-D1 and is what gates an engine registered ONLY at runtime (e.g.
+    // the synthetic contract-test engine, whose `deep:false` is declared at
+    // registration, not in the central `capabilitiesFor` table). Fall back to the
+    // central declaration for any engine queried before its registration runs.
+    const caps = engineCapabilities(engine) ?? capabilitiesFor(engine);
+    // An engine with the deep escape hatch (chromium) runs everything; an engine
+    // whose declaration hasn't landed yet is left to the launch path to reject.
+    if (!caps || caps.deep)
+        return null;
+    const reason = TOOL_REASON[tool] ?? GENERIC_REASON;
+    return {
+        error: `tool "${tool}" is not supported on the "${engine}" engine`,
+        hint: `${reason} ` +
+            `Re-run on a chromium session (browserType:"chromium", the default), or check the ` +
+            `per-engine capability matrix in docs/ai-context/architecture/engine-adapters.md.`,
+    };
+}

package/dist/engine/types.d.ts

@@ -0,0 +1,71 @@
+import type { Browser, BrowserContext, CDPSession, Page } from "playwright-core";
+/** The browser engines this port targets. chromium / firefox / webkit are the
+ *  desktop engines. `android` is real Chrome-on-Android attached
+ *  over adb + CDP — it IS Chromium, so it reuses the CDP substrates verbatim and
+ *  declares `deep: true` (every tool, including the CDP-deep ones, works). It is
+ *  a DISTINCT kind, not `chromium`, because its launch model is attach-only
+ *  (adb socket discovery → `connectOverCDP`) and managed/ephemeral launch on a
+ *  phone is not a thing the desktop adapters' shape covers. */
+export type EngineKind = "chromium" | "firefox" | "webkit" | "android" | "safari";
+export declare const ENGINE_KINDS: readonly EngineKind[];
+/** Capability-segregated sub-interfaces of the port. An adapter declares which
+ *  ones it supports via `EngineCapabilities`; a tool that needs `deep` (CDP) is
+ *  refused on an engine that lacks it through the existing capability gate.
+ *
+ *  The method set is derived from what the session layer + tools ACTUALLY call
+ *  today — interface segregation means each sub-interface is only what real
+ *  callers need, not a speculative superset.
+ *
+ *  Today the live port surface is intentionally thin: the session layer is the
+ *  only consumer, so the port exposes the lifecycle handles the rest of the
+ *  server already builds on (`Page`, `BrowserContext`, optional `CDPSession`).
+ *  The sub-interface NAMES below are the typed map of where each engine-specific
+ *  behavior lives as adapters grow; they are documented on
+ *  `EngineCapabilities`, not yet split into separate method bundles, because
+ *  splitting before the second adapter exists would be the speculative
+ *  generality the doctrine forbids. */
+export type EngineSubInterface = "lifecycle" | "navigation" | "snapshot" | "input" | "network" | "storage" | "script" | "emulation" | "capture" | "page";
+/** Declares what an adapter supports. Composes with the existing per-tool
+ *  capability system (util/capabilities.ts) — this is the ENGINE dimension.
+ *  Chromium declares every sub-interface plus `deep`, so nothing is newly gated
+ *  today. An adapter that lacks `deep` (no CDP escape hatch) declares
+ *  `deep: false`; the ~19 CDP-hard tools are then refused on it
+ *  through the capability gate, not by throwing a vague error mid-call. */
+export interface EngineCapabilities {
+    readonly engine: EngineKind;
+    /** Sub-interfaces this adapter implements. Chromium: all of them. */
+    readonly subInterfaces: ReadonlySet<EngineSubInterface>;
+    /** Whether the adapter exposes the `Deep` (raw-CDP) escape hatch — the typed
+     *  home for the ~19 CDP-hard operations. Chromium: true. Firefox/WebKit will
+     *  declare false and gate those tools. */
+    readonly deep: boolean;
+}
+/** A live engine-backed session. The adapter owns engine selection + launch;
+ *  the rest of the server consumes these handles exactly as it did before the
+ *  seam existed — `page()` / `context()` are the cross-browser surface, `cdp()`
+ *  is the engine-specific (Chromium) escape hatch and is now OPTIONAL.
+ *
+ *  `cdp()` was a mandatory member of `BrowserSession`; that single line hard-
+ *  gated multi-engine because `newCDPSession` throws off-Chromium. It is now a
+ *  capability the adapter exposes: present + fully functional on Chromium,
+ *  absent on engines without CDP. Consumers that need it go through
+ *  `requireCdp()` (see ./session-cdp.ts), which asserts presence with a
+ *  structured, engine-naming error — never a silent failure. */
+export interface EngineSession {
+    readonly engine: EngineKind;
+    readonly capabilities: EngineCapabilities;
+    page(): Page;
+    context(): BrowserContext;
+    /** Raw CDP handle. Present only when `capabilities.deep` is true (Chromium).
+     *  Undefined on engines without a CDP escape hatch. */
+    cdp?(): CDPSession;
+    close(): Promise<void>;
+}
+/** Internal handles an adapter wires up at launch, before the session-layer
+ *  bookkeeping (buffers, bridge, policies) attaches to them. */
+export interface EngineLaunchHandles {
+    browser?: Browser;
+    context: BrowserContext;
+    page: Page;
+    cdp?: CDPSession;
+}

package/dist/engine/types.js

@@ -0,0 +1,16 @@
+// The BrowserEngine port — the seam beneath the session layer that lets browxai
+// drive engines other than Chromium without rewriting the ~139 tools that
+// already speak only Playwright's cross-browser surface. See
+// docs/ai-context/architecture/engine-adapters.md for the strangler-fig design.
+//
+// Today Chromium is the only implemented engine. The port exists so the second
+// engine (Firefox) lands as a new adapter, not a core rewrite — the proven-seam
+// test in architecture-principles.md is satisfied because Firefox/WebKit are the
+// committed next engines and every coupling seam is already named.
+export const ENGINE_KINDS = [
+    "chromium",
+    "firefox",
+    "webkit",
+    "android",
+    "safari",
+];

package/dist/helper/bridge.d.ts

@@ -0,0 +1,48 @@
+import type { BrowserContext } from "playwright-core";
+export interface BrowxSignal {
+    name: string;
+    data: unknown;
+    ts: number;
+    /** URL of the page that emitted it (best-effort). */
+    url?: string;
+}
+export declare class BrowxBridge {
+    private cap;
+    private signals;
+    private waiters;
+    private pollers;
+    private bindingOk;
+    /** track attached contexts so detach() can install in-page opt-out
+     *  markers and known-disconnect handlers can stop nagging the user with
+     *  "function not exposed" console noise after our session ends. */
+    private contexts;
+    /** once true, our exposeBinding handler quietly drops incoming
+     *  payloads and the page script's `send()` is told (via `__browx_no_binding`)
+     *  to skip the binding and use the DOM-attribute path. */
+    private detached;
+    constructor(cap?: number);
+    attach(context: BrowserContext): Promise<void>;
+    /** Stop all pollers, reject outstanding waiters, and flip the
+     *  in-page `__browx_no_binding` flag so any subsequent `__browx.signal()`
+     *  / `.confirm()` etc. from the page goes through the DOM-attribute path
+     *  instead of the now-detached `__browx_send` exposeBinding glue —
+     *  silencing the "Function `__browx_send` is not exposed" console errors
+     *  that the shared-CDP verification run flagged. */
+    detach(): Promise<void>;
+    /** test introspection — true once detach() has fired. */
+    isDetached(): boolean;
+    /**
+     * Wait for the next signal matching `name` (or any signal if `name` is omitted).
+     * `timeoutMs > 0` rejects with a timeout error; `0` waits indefinitely.
+     */
+    awaitSignal(name?: string, timeoutMs?: number): Promise<BrowxSignal>;
+    private onSignal;
+    /**
+     * DOM-attribute fallback: every ~250ms, read `documentElement.dataset.browxSignal`,
+     * and if it differs from the last seen value, dispatch + clear. Lets the in-page
+     * helper still talk to us when the CDP binding is clobbered.
+     */
+    private startPolling;
+    /** True if the CDP binding installed cleanly. (Polling fallback runs either way.) */
+    bindingHealthy(): boolean;
+}

package/dist/helper/bridge.js

@@ -0,0 +1,200 @@
+// Server-side `__browx` bridge. Wires the in-page script + the `__browx_send`
+// CDP binding, queues signals, and exposes `awaitSignal(name, timeout)` that
+// resolves on the next matching `__browx.signal()` / `proceed()` / `abort()` /
+// `done()` call from the page.
+//
+//  scope:
+//   ✓ signal queue + awaitSignal (the site-docs `manual-capture` use case is
+//     `awaitHuman({kind:"acknowledge"})` → human calls `__browx.proceed()` →
+//     server unblocks).
+//   ✓ DOM-attribute-polling fallback for environments where `exposeBinding`
+//     gets clobbered (BYOB multi-attach — Playwright #34359).
+//   ✗ Shadow-DOM banner UI; `confirm` / `choose` / `input` / `pick_element`
+//     kinds —  polish.
+import { BROWX_PAGE_SCRIPT } from "./browx-page.js";
+import { log } from "../util/logging.js";
+export class BrowxBridge {
+    cap;
+    signals = [];
+    waiters = [];
+    pollers = new Map();
+    bindingOk = false;
+    /** track attached contexts so detach() can install in-page opt-out
+     *  markers and known-disconnect handlers can stop nagging the user with
+     *  "function not exposed" console noise after our session ends. */
+    contexts = [];
+    /** once true, our exposeBinding handler quietly drops incoming
+     *  payloads and the page script's `send()` is told (via `__browx_no_binding`)
+     *  to skip the binding and use the DOM-attribute path. */
+    detached = false;
+    constructor(cap = 200) {
+        this.cap = cap;
+    }
+    async attach(context) {
+        this.contexts.push(context);
+        try {
+            await context.exposeBinding("__browx_send", (source, payload) => {
+                if (this.detached)
+                    return; // quiet drop after detach.
+                try {
+                    const o = JSON.parse(payload);
+                    if (o.kind === "signal")
+                        this.onSignal({ name: o.name, data: o.data, ts: Date.now(), url: source.page?.url() });
+                }
+                catch (e) {
+                    log.warn("browx-bridge: bad payload", {
+                        error: e instanceof Error ? e.message : String(e),
+                    });
+                }
+            });
+            this.bindingOk = true;
+        }
+        catch (e) {
+            log.warn("browx-bridge: exposeBinding failed; will use DOM-attribute polling only", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+        await context.addInitScript({ content: BROWX_PAGE_SCRIPT });
+        // Re-inject into pages that already exist.
+        for (const page of context.pages()) {
+            await page.evaluate(BROWX_PAGE_SCRIPT).catch(() => undefined);
+            this.startPolling(page);
+        }
+        context.on("page", (page) => {
+            page.evaluate(BROWX_PAGE_SCRIPT).catch(() => undefined);
+            this.startPolling(page);
+        });
+    }
+    /** Stop all pollers, reject outstanding waiters, and flip the
+     *  in-page `__browx_no_binding` flag so any subsequent `__browx.signal()`
+     *  / `.confirm()` etc. from the page goes through the DOM-attribute path
+     *  instead of the now-detached `__browx_send` exposeBinding glue —
+     *  silencing the "Function `__browx_send` is not exposed" console errors
+     *  that the shared-CDP verification run flagged. */
+    detach() {
+        this.detached = true;
+        for (const t of this.pollers.values())
+            clearInterval(t);
+        this.pollers.clear();
+        for (const w of this.waiters) {
+            if (w.timeout)
+                clearTimeout(w.timeout);
+            w.reject(new Error("bridge detached"));
+        }
+        this.waiters = [];
+        const setOptOut = () => {
+            const w = Reflect.get(globalThis, "window");
+            if (w)
+                w.__browx_no_binding = true;
+        };
+        for (const ctx of this.contexts) {
+            try {
+                for (const page of ctx.pages()) {
+                    page.evaluate(setOptOut).catch(() => undefined);
+                }
+            }
+            catch {
+                /* context already torn down */
+            }
+        }
+        this.contexts = [];
+        return Promise.resolve();
+    }
+    /** test introspection — true once detach() has fired. */
+    isDetached() {
+        return this.detached;
+    }
+    /**
+     * Wait for the next signal matching `name` (or any signal if `name` is omitted).
+     * `timeoutMs > 0` rejects with a timeout error; `0` waits indefinitely.
+     */
+    awaitSignal(name, timeoutMs = 0) {
+        // Already-queued signal? (rare — usually we install the waiter before the
+        // human acts, but acknowledge-mode might pre-fire if the human is fast.)
+        if (name) {
+            const idx = this.signals.findIndex((s) => s.name === name);
+            if (idx >= 0)
+                return Promise.resolve(this.signals.splice(idx, 1)[0]);
+        }
+        else if (this.signals.length) {
+            return Promise.resolve(this.signals.shift());
+        }
+        return new Promise((resolve, reject) => {
+            const w = { name, resolve, reject };
+            if (timeoutMs > 0) {
+                w.timeout = setTimeout(() => {
+                    const i = this.waiters.indexOf(w);
+                    if (i >= 0)
+                        this.waiters.splice(i, 1);
+                    reject(new Error(`awaitHuman timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }
+            this.waiters.push(w);
+        });
+    }
+    onSignal(sig) {
+        log.info("browx-bridge: signal", { name: sig.name, url: sig.url });
+        // Match the *first* waiter wanting this name (FIFO). If none, queue.
+        for (let i = 0; i < this.waiters.length; i++) {
+            const w = this.waiters[i];
+            if (!w.name || w.name === sig.name) {
+                this.waiters.splice(i, 1);
+                if (w.timeout)
+                    clearTimeout(w.timeout);
+                w.resolve(sig);
+                return;
+            }
+        }
+        this.signals.push(sig);
+        if (this.signals.length > this.cap)
+            this.signals.shift();
+    }
+    /**
+     * DOM-attribute fallback: every ~250ms, read `documentElement.dataset.browxSignal`,
+     * and if it differs from the last seen value, dispatch + clear. Lets the in-page
+     * helper still talk to us when the CDP binding is clobbered.
+     */
+    startPolling(page) {
+        if (this.pollers.has(page))
+            return;
+        let lastSeen = null;
+        const tick = async () => {
+            try {
+                const raw = await page.evaluate(() => {
+                    // Runs in page context; cast through unknown to keep ts happy server-side.
+                    const doc = globalThis.document;
+                    if (!doc)
+                        return null;
+                    const v = doc.documentElement.getAttribute("data-browx-signal");
+                    if (v)
+                        doc.documentElement.removeAttribute("data-browx-signal");
+                    return v;
+                });
+                if (raw && raw !== lastSeen) {
+                    lastSeen = raw;
+                    const o = JSON.parse(raw);
+                    if (o.kind === "signal")
+                        this.onSignal({ name: o.name, data: o.data, ts: o.ts, url: page.url() });
+                }
+            }
+            catch {
+                // Page may have closed / navigated mid-poll.
+            }
+        };
+        const t = setInterval(() => {
+            void tick();
+        }, 250);
+        this.pollers.set(page, t);
+        page.on("close", () => {
+            const it = this.pollers.get(page);
+            if (it) {
+                clearInterval(it);
+                this.pollers.delete(page);
+            }
+        });
+    }
+    /** True if the CDP binding installed cleanly. (Polling fallback runs either way.) */
+    bindingHealthy() {
+        return this.bindingOk;
+    }
+}

package/dist/helper/browx-page.d.ts

@@ -0,0 +1 @@
+export declare const BROWX_PAGE_SCRIPT = "(() => {\n  if (window.__browx) return;\n  function viaAttribute(kind, name, data) {\n    try {\n      document.documentElement.setAttribute(\n        \"data-browx-signal\",\n        JSON.stringify({ kind: kind, name: name, data: data == null ? null : data, ts: Date.now() })\n      );\n    } catch (_) {}\n  }\n  function send(kind, name, data) {\n    // when our bridge has detached (set window.__browx_no_binding = true),\n    // skip the now-detached __browx_send exposeBinding glue entirely \u2014 it would\n    // emit \"Function __browx_send is not exposed\" console errors on every call.\n    if (window.__browx_no_binding || typeof window.__browx_send !== \"function\") {\n      viaAttribute(kind, name, data);\n      return;\n    }\n    try { window.__browx_send(JSON.stringify({ kind: kind, name: name, data: data == null ? null : data })); }\n    catch (e) { /* binding may have been clobbered (CDP multi-attach); fall back to DOM-attribute path */\n      viaAttribute(kind, name, data);\n    }\n  }\n  window.__browx = {\n    signal: function (name, data) { send(\"signal\", name, data); },\n    proceed: function (data) { send(\"signal\", \"proceed\", data == null ? null : data); },\n    abort: function (reason) { send(\"signal\", \"abort\", reason == null ? null : reason); },\n    done: function (what, data) { send(\"signal\", \"did\", { what: what, data: data == null ? null : data }); },\n    // typed responses to await_human({kind:\"confirm|choose|input\"}). The\n    // human reads the prompt from the runbook / terminal stderr, then calls one\n    // of these from DevTools (or a future shadow-DOM banner UI will call them).\n    respond: function (value) { send(\"signal\", \"respond\", value); },\n    confirm: function (yes) { send(\"signal\", \"respond\", { kind: \"confirm\", value: !!yes }); },\n    choose: function (idx) { send(\"signal\", \"respond\", { kind: \"choose\", value: idx }); },\n    input: function (text) { send(\"signal\", \"respond\", { kind: \"input\", value: String(text == null ? \"\" : text) }); },\n    status: function () { return { state: \"ready\" }; },\n  };\n  try { console.info(\"[browxai] __browx ready. window.__browx.proceed() releases any awaiting tool. For await_human kinds: confirm(true|false) / choose(idx) / input(text).\"); } catch (_) {}\n})();";

package/dist/helper/browx-page.js

@@ -0,0 +1,47 @@
+// In-page script that defines window.__browx. Injected via addInitScript so it
+// runs on every navigation / new document, and evaluated directly on already-open
+// pages at attach time. Tiny and self-contained — no framework, no DOM banner
+// (the shadow-DOM banner UI is a polish; for now we log a one-line
+// hint to the console so a human in DevTools knows the API is there).
+//
+// stringified so it can be passed as a script source. Keep the contents
+// browser-only JS — no TS-only syntax.
+export const BROWX_PAGE_SCRIPT = `(() => {
+  if (window.__browx) return;
+  function viaAttribute(kind, name, data) {
+    try {
+      document.documentElement.setAttribute(
+        "data-browx-signal",
+        JSON.stringify({ kind: kind, name: name, data: data == null ? null : data, ts: Date.now() })
+      );
+    } catch (_) {}
+  }
+  function send(kind, name, data) {
+    // when our bridge has detached (set window.__browx_no_binding = true),
+    // skip the now-detached __browx_send exposeBinding glue entirely — it would
+    // emit "Function __browx_send is not exposed" console errors on every call.
+    if (window.__browx_no_binding || typeof window.__browx_send !== "function") {
+      viaAttribute(kind, name, data);
+      return;
+    }
+    try { window.__browx_send(JSON.stringify({ kind: kind, name: name, data: data == null ? null : data })); }
+    catch (e) { /* binding may have been clobbered (CDP multi-attach); fall back to DOM-attribute path */
+      viaAttribute(kind, name, data);
+    }
+  }
+  window.__browx = {
+    signal: function (name, data) { send("signal", name, data); },
+    proceed: function (data) { send("signal", "proceed", data == null ? null : data); },
+    abort: function (reason) { send("signal", "abort", reason == null ? null : reason); },
+    done: function (what, data) { send("signal", "did", { what: what, data: data == null ? null : data }); },
+    // typed responses to await_human({kind:"confirm|choose|input"}). The
+    // human reads the prompt from the runbook / terminal stderr, then calls one
+    // of these from DevTools (or a future shadow-DOM banner UI will call them).
+    respond: function (value) { send("signal", "respond", value); },
+    confirm: function (yes) { send("signal", "respond", { kind: "confirm", value: !!yes }); },
+    choose: function (idx) { send("signal", "respond", { kind: "choose", value: idx }); },
+    input: function (text) { send("signal", "respond", { kind: "input", value: String(text == null ? "" : text) }); },
+    status: function () { return { state: "ready" }; },
+  };
+  try { console.info("[browxai] __browx ready. window.__browx.proceed() releases any awaiting tool. For await_human kinds: confirm(true|false) / choose(idx) / input(text)."); } catch (_) {}
+})();`;

package/dist/helper/overlay-hide.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserContext } from "playwright-core";
+/** 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 declare function buildOverlayHideScript(selectors: string[]): string;
+/** 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 declare function applyOverlayHide(context: BrowserContext, selectors: string[]): Promise<void>;