browxai 0.7.0

package/dist/engine/adapters/safari/bidi-client.d.ts

@@ -0,0 +1,46 @@
+/** The minimal WebSocket surface this client uses — satisfied by Node 22's global
+ *  `WebSocket` and by the test double. */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: "open" | "message" | "error" | "close", listener: (ev: {
+        data?: string;
+    }) => void): void;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+/** A BiDi event payload (`{type:"event", method, params}`) dispatched to `on()`
+ *  handlers — e.g. `log.entryAdded`, `browsingContext.load`. */
+export type BidiEventHandler = (params: Record<string, unknown>) => void;
+/** A BiDi command error (`{type:"error", error, message}`) surfaced as a
+ *  structured throw — never a silent failure. */
+export declare class BidiError extends Error {
+    readonly bidiError: string;
+    constructor(bidiError: string, message: string);
+}
+export declare class SafariBidiClient {
+    private readonly url;
+    private readonly wsFactory;
+    private readonly commandTimeoutMs;
+    private ws;
+    private nextId;
+    private readonly pending;
+    private readonly handlers;
+    constructor(opts: {
+        url: string;
+        wsFactory?: WebSocketFactory;
+        commandTimeoutMs?: number;
+    });
+    /** Open the socket. Resolves on `open`, rejects on a connect-time `error`. */
+    connect(): Promise<void>;
+    /** Send a BiDi command and await its correlated reply. Rejects with a
+     *  `BidiError` on an error reply (e.g. `unknown command` for a module Safari
+     *  does not implement) and on timeout. */
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Subscribe to BiDi events (`session.subscribe`). The corresponding `on()`
+     *  handlers then fire as events arrive. */
+    subscribe(events: string[]): Promise<void>;
+    /** Register a handler for a BiDi event method (e.g. `log.entryAdded`). */
+    on(method: string, handler: BidiEventHandler): void;
+    close(): void;
+    private onMessage;
+}

package/dist/engine/adapters/safari/bidi-client.js

@@ -0,0 +1,130 @@
+// SafariBidiClient — the WebDriver-BiDi WebSocket client beneath the
+// SafaridriverHybridAdapter. This is the ADDITIVE half of the
+// hybrid: live probing found
+// Safari 26.5 opens a real BiDi socket ONLY behind the vendor cap
+// `safari:experimentalWebSocketUrl:true`, and that socket serves a PARTIAL but
+// real surface — `script` (evaluate/callFunction/getRealms/addPreloadScript),
+// `browsingContext` navigation/lifecycle/setViewport/create/activate, and the
+// events that fired (`browsingContext.navigation*`/`load`, `log.entryAdded`).
+// It does NOT serve input/network/emulation/screenshot/locateNodes/storage — the
+// adapter routes those through WebDriver Classic (SafariWebDriverClient) or gates
+// them. Because the experimental cap can disappear in any Safari point release,
+// this client is STRICTLY OPTIONAL: the adapter runs Classic-only when there is
+// no ws:// URL, so nothing here is on the critical path.
+//
+// Node's global `WebSocket` (v22+) is the transport — no `ws` dependency, exactly
+// as the probe used. The factory is injected (`WebSocketFactory`) so the
+// request/response correlation + event dispatch unit-test without a real socket.
+/** A BiDi command error (`{type:"error", error, message}`) surfaced as a
+ *  structured throw — never a silent failure. */
+export class BidiError extends Error {
+    bidiError;
+    constructor(bidiError, message) {
+        super(`safari-bidi: ${bidiError}: ${message}`);
+        this.name = "BidiError";
+        this.bidiError = bidiError;
+    }
+}
+export class SafariBidiClient {
+    url;
+    wsFactory;
+    commandTimeoutMs;
+    ws;
+    nextId = 1;
+    pending = new Map();
+    handlers = new Map();
+    constructor(opts) {
+        this.url = opts.url;
+        // Node 22's global WebSocket is structurally a WebSocketLike.
+        this.wsFactory = opts.wsFactory ?? ((u) => new WebSocket(u));
+        this.commandTimeoutMs = opts.commandTimeoutMs ?? 10_000;
+    }
+    /** Open the socket. Resolves on `open`, rejects on a connect-time `error`. */
+    connect() {
+        return new Promise((resolve, reject) => {
+            const ws = this.wsFactory(this.url);
+            this.ws = ws;
+            ws.addEventListener("open", () => resolve());
+            ws.addEventListener("error", (ev) => reject(new Error(`safari-bidi: socket error ${describe(ev)}`)));
+            ws.addEventListener("message", (ev) => this.onMessage(ev.data));
+        });
+    }
+    /** Send a BiDi command and await its correlated reply. Rejects with a
+     *  `BidiError` on an error reply (e.g. `unknown command` for a module Safari
+     *  does not implement) and on timeout. */
+    send(method, params = {}) {
+        if (!this.ws)
+            return Promise.reject(new Error("safari-bidi: not connected"));
+        const id = this.nextId++;
+        const ws = this.ws;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`safari-bidi: command timed out after ${this.commandTimeoutMs}ms: ${method}`));
+            }, this.commandTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    /** Subscribe to BiDi events (`session.subscribe`). The corresponding `on()`
+     *  handlers then fire as events arrive. */
+    async subscribe(events) {
+        await this.send("session.subscribe", { events });
+    }
+    /** Register a handler for a BiDi event method (e.g. `log.entryAdded`). */
+    on(method, handler) {
+        let set = this.handlers.get(method);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(method, set);
+        }
+        set.add(handler);
+    }
+    close() {
+        for (const { reject, timer } of this.pending.values()) {
+            clearTimeout(timer);
+            reject(new Error("safari-bidi: client closed"));
+        }
+        this.pending.clear();
+        this.ws?.close();
+        this.ws = undefined;
+    }
+    onMessage(data) {
+        if (data === undefined)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (msg.type === "event" && msg.method) {
+            const set = this.handlers.get(msg.method);
+            if (set)
+                for (const h of set)
+                    h(msg.params ?? {});
+            return;
+        }
+        if (typeof msg.id === "number") {
+            const entry = this.pending.get(msg.id);
+            if (!entry)
+                return;
+            this.pending.delete(msg.id);
+            clearTimeout(entry.timer);
+            if (msg.type === "error") {
+                entry.reject(new BidiError(msg.error ?? "unknown error", msg.message ?? ""));
+            }
+            else {
+                entry.resolve(msg.result);
+            }
+        }
+    }
+}
+/** Best-effort description of a socket error event for the connect rejection. */
+function describe(ev) {
+    if (ev && typeof ev === "object" && "message" in ev) {
+        return String(ev.message);
+    }
+    return "";
+}

package/dist/engine/adapters/safari/launch.d.ts

@@ -0,0 +1,56 @@
+/** Canonical safaridriver path (the symlink in /usr/bin resolves into the Safari
+ *  cryptex). Overridable in tests via `SafariLaunchDeps.driverPath`. */
+export declare const SAFARIDRIVER_PATH = "/usr/bin/safaridriver";
+/** The minimal child-process surface the launcher owns. Satisfied by Node's
+ *  `ChildProcess`; the test double records the kill. */
+export interface ProcessLike {
+    readonly pid?: number;
+    kill(): boolean;
+}
+export type SpawnLike = (cmd: string, args: string[]) => ProcessLike;
+/** Raised when Safari automation cannot run on this host at all — not macOS, or
+ *  safaridriver is absent. Structured (no vague crash) per the doctrine, naming
+ *  the fix. */
+export declare class SafariUnavailableError extends Error {
+    constructor(reason: string);
+}
+/** Raised when safaridriver never reaches readiness within the poll window. */
+export declare class SafariLaunchTimeoutError extends Error {
+    constructor(ms: number);
+}
+/** Injectable IO seams (defaults shell out / probe for real). */
+export interface SafariLaunchDeps {
+    spawnImpl?: SpawnLike;
+    /** Resolve a free loopback port (defaults to adb.ts's `pickFreePort`). */
+    pickPort?: () => Promise<number>;
+    /** Probe whether a driver at `baseUrl` is ready (defaults to a real GET
+     *  /status). Injected so the poll loop tests without a driver. */
+    probeReady?: (baseUrl: string) => Promise<boolean>;
+    /** Whether the safaridriver binary exists (defaults to a real `statSync`). */
+    binaryExists?: (path: string) => boolean;
+    /** The host platform (defaults to `process.platform`). */
+    platform?: NodeJS.Platform;
+    /** Override the driver path (tests). */
+    driverPath?: string;
+    /** Sleep between readiness polls (injected so tests don't wait). */
+    sleep?: (ms: number) => Promise<void>;
+    readinessTimeoutMs?: number;
+    pollIntervalMs?: number;
+}
+/** A running safaridriver. `baseUrl` is the WebDriver HTTP endpoint; `stop()`
+ *  kills the process. */
+export interface SafariDriverProcess {
+    baseUrl: string;
+    httpPort: number;
+    process: ProcessLike;
+    stop(): void;
+}
+/** Platform + binary precheck. Throws `SafariUnavailableError` off-macOS or when
+ *  safaridriver is absent — the launch fast-fails with a clear reason rather than
+ *  spawning a doomed process. */
+export declare function assertSafariAvailable(deps?: SafariLaunchDeps): void;
+/** Spawn safaridriver and poll it to readiness. Pre-checks availability, picks a
+ *  free HTTP port (+ a BiDi port), spawns `safaridriver -p <http> --bidi <bidi>`,
+ *  then polls GET /status until ready or the timeout — killing the process if it
+ *  never comes up (no leaked driver). */
+export declare function launchSafaridriver(deps?: SafariLaunchDeps): Promise<SafariDriverProcess>;

package/dist/engine/adapters/safari/launch.js

@@ -0,0 +1,104 @@
+// safaridriver process lifecycle for the SafaridriverHybridAdapter
+// — spawn the driver, poll it to readiness, and own its teardown. Split into a
+// platform/binary precheck + the spawn/poll, with the IO seams (spawn, the
+// readiness probe, the sleep) injected so the orchestration unit-tests WITHOUT a
+// real safaridriver — the same discipline as adb.ts. The real IO path is covered
+// by the Safari-gated keystone.
+//
+// safaridriver is macOS-only and ships inside the Safari cryptex
+// (`/usr/bin/safaridriver` → `/System/Cryptexes/App/usr/bin/safaridriver`). It
+// is launched as `safaridriver -p <httpPort> --bidi <bidiPort>`: the HTTP port
+// serves WebDriver Classic + session creation; `--bidi` enables BiDi for hosted
+// sessions (the actual ws:// socket is allocated dynamically and reported in the
+// granted caps, NOT bound to the passed port value).
+import { execFile } from "node:child_process";
+import { statSync } from "node:fs";
+import { SafariWebDriverClient } from "./webdriver-client.js";
+/** Canonical safaridriver path (the symlink in /usr/bin resolves into the Safari
+ *  cryptex). Overridable in tests via `SafariLaunchDeps.driverPath`. */
+export const SAFARIDRIVER_PATH = "/usr/bin/safaridriver";
+/** Raised when Safari automation cannot run on this host at all — not macOS, or
+ *  safaridriver is absent. Structured (no vague crash) per the doctrine, naming
+ *  the fix. */
+export class SafariUnavailableError extends Error {
+    constructor(reason) {
+        super(`safari-unavailable: ${reason}. Real Safari automation needs macOS with safaridriver ` +
+            `(${SAFARIDRIVER_PATH}).`);
+        this.name = "SafariUnavailableError";
+    }
+}
+/** Raised when safaridriver never reaches readiness within the poll window. */
+export class SafariLaunchTimeoutError extends Error {
+    constructor(ms) {
+        super(`safari-launch-timeout: safaridriver did not become ready within ${ms}ms`);
+        this.name = "SafariLaunchTimeoutError";
+    }
+}
+function defaultBinaryExists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultSpawn(cmd, args) {
+    // detached:false — the driver dies with the parent; stdio ignored (we talk to
+    // it over HTTP, not its stdout).
+    return execFile(cmd, args, () => undefined);
+}
+function defaultSleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** Platform + binary precheck. Throws `SafariUnavailableError` off-macOS or when
+ *  safaridriver is absent — the launch fast-fails with a clear reason rather than
+ *  spawning a doomed process. */
+export function assertSafariAvailable(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "darwin") {
+        throw new SafariUnavailableError(`host platform is "${platform}", not macOS`);
+    }
+    const driverPath = deps.driverPath ?? SAFARIDRIVER_PATH;
+    const exists = deps.binaryExists ?? defaultBinaryExists;
+    if (!exists(driverPath)) {
+        throw new SafariUnavailableError(`safaridriver not found at ${driverPath}`);
+    }
+}
+/** Spawn safaridriver and poll it to readiness. Pre-checks availability, picks a
+ *  free HTTP port (+ a BiDi port), spawns `safaridriver -p <http> --bidi <bidi>`,
+ *  then polls GET /status until ready or the timeout — killing the process if it
+ *  never comes up (no leaked driver). */
+export async function launchSafaridriver(deps = {}) {
+    assertSafariAvailable(deps);
+    const { pickFreePort } = await import("../adb.js");
+    const pickPort = deps.pickPort ?? pickFreePort;
+    const spawnImpl = deps.spawnImpl ?? defaultSpawn;
+    const sleep = deps.sleep ?? defaultSleep;
+    const timeoutMs = deps.readinessTimeoutMs ?? 10_000;
+    const intervalMs = deps.pollIntervalMs ?? 150;
+    const driverPath = deps.driverPath ?? SAFARIDRIVER_PATH;
+    const httpPort = await pickPort();
+    const bidiPort = await pickPort();
+    const baseUrl = `http://127.0.0.1:${httpPort}`;
+    const probeReady = deps.probeReady ??
+        ((url) => new SafariWebDriverClient({ baseUrl: url }).status().then((s) => s.ready));
+    const proc = spawnImpl(driverPath, ["-p", String(httpPort), "--bidi", String(bidiPort)]);
+    const stop = () => {
+        try {
+            proc.kill();
+        }
+        catch {
+            /* already dead */
+        }
+    };
+    const deadline = timeoutMs / intervalMs;
+    for (let attempt = 0; attempt < deadline; attempt++) {
+        if (await probeReady(baseUrl)) {
+            return { baseUrl, httpPort, process: proc, stop };
+        }
+        await sleep(intervalMs);
+    }
+    stop();
+    throw new SafariLaunchTimeoutError(timeoutMs);
+}

package/dist/engine/adapters/safari/webdriver-client.d.ts

@@ -0,0 +1,102 @@
+/** The subset of the global `fetch` signature this client uses. Injected so the
+ *  unit tests pass a mock and the orchestration is exercised driver-free. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/** A WebDriver cookie (the fields the cookie tools round-trip). */
+export interface WebDriverCookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    expiry?: number;
+    sameSite?: "Lax" | "Strict" | "None";
+}
+/** The granted-capabilities shape this client cares about — `webSocketUrl` is a
+ *  real `ws://` string ONLY when the session was created with
+ *  `safari:experimentalWebSocketUrl:true` (otherwise it is a boolean placeholder
+ *  and no BiDi socket exists — see reference 06). */
+export interface NewSessionResult {
+    sessionId: string;
+    capabilities: Record<string, unknown>;
+    /** The BiDi WebSocket URL, present only when the experimental cap negotiated a
+     *  real socket. A boolean or undefined means "no BiDi" — run Classic-only. */
+    webSocketUrl: string | undefined;
+}
+/** A WebDriver protocol error surfaced as a structured throw (never a vague
+ *  mid-call failure — the doctrine's no-silent-failure rule). `error` is the W3C
+ *  error code (e.g. `session not created`, `no such element`). */
+export declare class WebDriverError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    constructor(code: string, message: string, httpStatus: number);
+}
+/** Whether a request body is an experimental-cap BiDi request (for the
+ *  capability negotiation the adapter does at session create). */
+export interface SessionCapabilities {
+    /** Request a BiDi socket. Pairs with `experimentalWebSocketUrl` on Safari. */
+    webSocketUrl?: boolean;
+    /** Safari vendor cap — REQUIRED to actually open a BiDi socket on Safari 26.5
+     *  (plain `webSocketUrl:true` returns a boolean placeholder). */
+    experimentalWebSocketUrl?: boolean;
+}
+export declare class SafariWebDriverClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(opts: {
+        baseUrl: string;
+        fetchImpl?: FetchLike;
+    });
+    /** `GET /status` — readiness probe (used by the launch poll). Never throws on a
+     *  protocol error; returns `{ready:false}` so the poll can retry. */
+    status(): Promise<{
+        ready: boolean;
+        message: string;
+    }>;
+    /** `POST /session` — create a session. On Safari, passing
+     *  `{webSocketUrl:true, experimentalWebSocketUrl:true}` negotiates a real BiDi
+     *  socket; the granted `webSocketUrl` is a `ws://` STRING when (and only when)
+     *  the experimental cap took (reference 06). A boolean/absent value => no BiDi. */
+    newSession(caps?: SessionCapabilities): Promise<NewSessionResult>;
+    deleteSession(sessionId: string): Promise<void>;
+    navigate(sessionId: string, url: string): Promise<void>;
+    /** Current document URL — the Classic substitute for `page.url()` (which the
+     *  Safari session cannot provide, having no Playwright Page). */
+    currentUrl(sessionId: string): Promise<string>;
+    /** Full-page screenshot as base64 PNG (Classic — BiDi captureScreenshot is
+     *  absent on Safari 26.5). */
+    screenshot(sessionId: string): Promise<string>;
+    /** Find the first matching element; null when none (no-such-element is a normal
+     *  "not found", not a protocol failure, so it is mapped to null). */
+    findElement(sessionId: string, using: string, value: string): Promise<string | null>;
+    findElements(sessionId: string, using: string, value: string): Promise<string[]>;
+    elementClick(sessionId: string, elementId: string): Promise<void>;
+    elementClear(sessionId: string, elementId: string): Promise<void>;
+    /** sendKeys. The W3C body carries both `text` and the legacy `value` array;
+     *  safaridriver accepts `text`. */
+    elementValue(sessionId: string, elementId: string, text: string): Promise<void>;
+    elementText(sessionId: string, elementId: string): Promise<string>;
+    /** Get Element Property — the LIVE DOM property (e.g. an input's current
+     *  `value`), as opposed to the static HTML attribute. Used to read back what a
+     *  fill landed. Returns null when the property is absent. */
+    elementProperty(sessionId: string, elementId: string, name: string): Promise<string | null>;
+    getCookies(sessionId: string): Promise<WebDriverCookie[]>;
+    addCookie(sessionId: string, cookie: WebDriverCookie): Promise<void>;
+    /** `POST /execute/sync` — run page-context JS and return its value. This is the
+     *  seam the Safari snapshot substrate ships browxai's DOM-walk PAGE_SCRIPT
+     *  through (spike-confirmed identical to Playwright frame.evaluate —
+     *  reference 07 §4). `script` is a function BODY; `args` map to `arguments`. */
+    executeScript(sessionId: string, script: string, args?: unknown[]): Promise<unknown>;
+    /** The single request primitive: POST/GET/DELETE a WebDriver endpoint, unwrap
+     *  the `{value}` envelope, and turn an error envelope into a structured
+     *  `WebDriverError`. */
+    private send;
+}

package/dist/engine/adapters/safari/webdriver-client.js

@@ -0,0 +1,175 @@
+// SafariWebDriverClient — the WebDriver-Classic HTTP client beneath the
+// SafaridriverHybridAdapter. Classic is the COMPLETE workhorse for
+// real Safari: a live probe against the shipping safaridriver
+// confirmed navigate / screenshot / findElement / element click+value+text /
+// cookies / executeScript all work on the shipping safaridriver, whereas the
+// experimental BiDi layer (SafariBidiClient) is the additive bidirectional half
+// (console + nav events) and is gated behind a vendor cap. So the adapter leans
+// on THIS client for the element/screenshot/cookie/exec surface and treats BiDi
+// as strictly optional.
+//
+// This is pure `fetch` over loopback (safaridriver's REST endpoints), with the
+// HTTP transport injected (`FetchLike`) so the orchestration unit-tests without a
+// real driver — the same IO-seam discipline as adb.ts (AdbRunner/Fetcher). It
+// implements ONLY the endpoints the adapter + the Safari snapshot/action seams
+// actually call (interface segregation), not the whole WebDriver surface.
+/** The W3C element-reference key — the property name a WebDriver server uses to
+ *  carry an element handle in JSON. safaridriver returns this key (and also the
+ *  legacy `ELEMENT`); we read either. */
+const ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";
+/** A WebDriver protocol error surfaced as a structured throw (never a vague
+ *  mid-call failure — the doctrine's no-silent-failure rule). `error` is the W3C
+ *  error code (e.g. `session not created`, `no such element`). */
+export class WebDriverError extends Error {
+    code;
+    httpStatus;
+    constructor(code, message, httpStatus) {
+        super(`safari-webdriver: ${code}: ${message}`);
+        this.name = "WebDriverError";
+        this.code = code;
+        this.httpStatus = httpStatus;
+    }
+}
+export class SafariWebDriverClient {
+    baseUrl;
+    fetchImpl;
+    constructor(opts) {
+        // Trim a trailing slash so path joins are unambiguous.
+        this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+        // globalThis.fetch is structurally assignable to FetchLike (a looser shape).
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    }
+    /** `GET /status` — readiness probe (used by the launch poll). Never throws on a
+     *  protocol error; returns `{ready:false}` so the poll can retry. */
+    async status() {
+        try {
+            const value = (await this.send("GET", "/status"));
+            return { ready: value?.ready ?? false, message: value?.message ?? "" };
+        }
+        catch {
+            return { ready: false, message: "unreachable" };
+        }
+    }
+    /** `POST /session` — create a session. On Safari, passing
+     *  `{webSocketUrl:true, experimentalWebSocketUrl:true}` negotiates a real BiDi
+     *  socket; the granted `webSocketUrl` is a `ws://` STRING when (and only when)
+     *  the experimental cap took (reference 06). A boolean/absent value => no BiDi. */
+    async newSession(caps = {}) {
+        const alwaysMatch = { browserName: "safari" };
+        if (caps.webSocketUrl)
+            alwaysMatch["webSocketUrl"] = true;
+        if (caps.experimentalWebSocketUrl)
+            alwaysMatch["safari:experimentalWebSocketUrl"] = true;
+        const value = (await this.send("POST", "/session", { capabilities: { alwaysMatch } }));
+        const granted = value.capabilities ?? {};
+        const ws = granted["webSocketUrl"];
+        return {
+            sessionId: value.sessionId,
+            capabilities: granted,
+            // ONLY a string ws:// URL counts as a live BiDi socket; the boolean
+            // placeholder (experimental cap off) means Classic-only.
+            webSocketUrl: typeof ws === "string" ? ws : undefined,
+        };
+    }
+    async deleteSession(sessionId) {
+        await this.send("DELETE", `/session/${sessionId}`);
+    }
+    async navigate(sessionId, url) {
+        await this.send("POST", `/session/${sessionId}/url`, { url });
+    }
+    /** Current document URL — the Classic substitute for `page.url()` (which the
+     *  Safari session cannot provide, having no Playwright Page). */
+    async currentUrl(sessionId) {
+        return (await this.send("GET", `/session/${sessionId}/url`));
+    }
+    /** Full-page screenshot as base64 PNG (Classic — BiDi captureScreenshot is
+     *  absent on Safari 26.5). */
+    async screenshot(sessionId) {
+        return (await this.send("GET", `/session/${sessionId}/screenshot`));
+    }
+    /** Find the first matching element; null when none (no-such-element is a normal
+     *  "not found", not a protocol failure, so it is mapped to null). */
+    async findElement(sessionId, using, value) {
+        try {
+            const v = (await this.send("POST", `/session/${sessionId}/element`, {
+                using,
+                value,
+            }));
+            return v[ELEMENT_KEY] ?? v["ELEMENT"] ?? null;
+        }
+        catch (err) {
+            if (err instanceof WebDriverError && err.code === "no such element")
+                return null;
+            throw err;
+        }
+    }
+    async findElements(sessionId, using, value) {
+        const v = (await this.send("POST", `/session/${sessionId}/elements`, {
+            using,
+            value,
+        }));
+        return v.map((e) => e[ELEMENT_KEY] ?? e["ELEMENT"]).filter((id) => Boolean(id));
+    }
+    // Click the element via execute/sync rather than the W3C `/element/{id}/click`
+    // endpoint: on the shipping safaridriver the protocol Element Click does not
+    // reliably dispatch the page's `click` handlers (a button's `onclick` never
+    // fires), whereas a script-driven `arguments[0].click()` does — the same
+    // execute/sync seam the snapshot substrate is spike-confirmed on (reference 07).
+    // The resolved element id is passed as a web-element reference so the exact
+    // element this client found is the one clicked.
+    async elementClick(sessionId, elementId) {
+        await this.executeScript(sessionId, "arguments[0].click();", [{ [ELEMENT_KEY]: elementId }]);
+    }
+    async elementClear(sessionId, elementId) {
+        await this.send("POST", `/session/${sessionId}/element/${elementId}/clear`, {});
+    }
+    /** sendKeys. The W3C body carries both `text` and the legacy `value` array;
+     *  safaridriver accepts `text`. */
+    async elementValue(sessionId, elementId, text) {
+        await this.send("POST", `/session/${sessionId}/element/${elementId}/value`, {
+            text,
+            value: text.split(""),
+        });
+    }
+    async elementText(sessionId, elementId) {
+        return (await this.send("GET", `/session/${sessionId}/element/${elementId}/text`));
+    }
+    /** Get Element Property — the LIVE DOM property (e.g. an input's current
+     *  `value`), as opposed to the static HTML attribute. Used to read back what a
+     *  fill landed. Returns null when the property is absent. */
+    async elementProperty(sessionId, elementId, name) {
+        const v = await this.send("GET", `/session/${sessionId}/element/${elementId}/property/${name}`);
+        return typeof v === "string" ? v : null;
+    }
+    async getCookies(sessionId) {
+        return (await this.send("GET", `/session/${sessionId}/cookie`));
+    }
+    async addCookie(sessionId, cookie) {
+        await this.send("POST", `/session/${sessionId}/cookie`, { cookie });
+    }
+    /** `POST /execute/sync` — run page-context JS and return its value. This is the
+     *  seam the Safari snapshot substrate ships browxai's DOM-walk PAGE_SCRIPT
+     *  through (spike-confirmed identical to Playwright frame.evaluate —
+     *  reference 07 §4). `script` is a function BODY; `args` map to `arguments`. */
+    async executeScript(sessionId, script, args = []) {
+        return await this.send("POST", `/session/${sessionId}/execute/sync`, { script, args });
+    }
+    /** The single request primitive: POST/GET/DELETE a WebDriver endpoint, unwrap
+     *  the `{value}` envelope, and turn an error envelope into a structured
+     *  `WebDriverError`. */
+    async send(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: { "Content-Type": "application/json" },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const payload = (await res.json());
+        const value = payload?.value;
+        // WebDriver signals errors with HTTP 4xx/5xx AND a `value.error` code.
+        if (!res.ok || (value && typeof value === "object" && "error" in value)) {
+            const v = (value ?? {});
+            throw new WebDriverError(v.error ?? `http ${res.status}`, v.message ?? "", res.status);
+        }
+        return value;
+    }
+}

package/dist/engine/adapters/safari.engine.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine/adapters/safari.engine.js

@@ -0,0 +1,52 @@
+// Safari engine registration (RFC 0004 D1 + D5). Safari is the first
+// non-Playwright, no-Page engine — real Safari.app over safaridriver. Its
+// `EngineEntry` is what closes the Safari LSP leak: the engine declares no `page`
+// sub-interface (capabilities.ts), supplies the Safari `SubstrateBundle` (every
+// selector reads the Safari-native handle, never a Page/CDP), and its `postWire`
+// attaches ONLY the BiDi console bridge — omitting every Playwright-only step. So
+// the 17 scattered `sess.engine !== "safari"` guards have no reason to exist, and
+// the `page()`-throws fallback in safari-session.ts is never reached on the
+// relocated path.
+import { log } from "../../util/logging.js";
+import { registerEngine } from "../registry.js";
+import { capabilitiesFor } from "../capabilities.js";
+import { SafaridriverHybridAdapter } from "./safaridriver-hybrid.js";
+import { buildSafariSession } from "../../session/safari-session.js";
+import { safariSubstrateBundle } from "../../page/substrate-bundle-safari.js";
+import { safariPostWire } from "../../session/safari-post-wire.js";
+async function makeSafariAdapter(opts) {
+    const mode = opts.launchMode ?? "managed";
+    if (mode === "incognito") {
+        // safari runs ISOLATED automation windows via the default managed session
+        // (safaridriver already isolates each session). Incognito (a separate
+        // in-browser context) is a Playwright concept safaridriver has no equivalent
+        // for, so refuse rather than silently launch a managed window.
+        throw new Error("safari-incognito-not-supported: the safari engine runs isolated automation windows via the " +
+            "default managed session (safaridriver isolates each session by construction). Incognito (a " +
+            "separate browser context) is a Playwright concept safaridriver has no equivalent for. Open a " +
+            "managed session instead.");
+    }
+    if (mode === "byob") {
+        // safari cannot attach to a live browser at all — safaridriver hard-isolates
+        // each session into a clean ephemeral automation window. Surface the adapter's
+        // structured `safari-attach-not-supported`.
+        await new SafaridriverHybridAdapter().attach();
+        throw new Error("unreachable: safari attach always refuses");
+    }
+    // managed IS the safari model (no headless Safari, no separate-context
+    // incognito) — an isolated automation window over safaridriver, whose page()
+    // throws; Safari-capable tools route through session.safari().
+    const handle = await new SafaridriverHybridAdapter().launchManaged();
+    log.info("session.managed: safari session ready", {
+        sessionId: handle.sessionId,
+        hasBidi: handle.hasBidi,
+    });
+    return buildSafariSession(handle);
+}
+registerEngine({
+    kind: "safari",
+    capabilities: capabilitiesFor("safari"),
+    makeAdapter: makeSafariAdapter,
+    makeSubstrates: (deps) => safariSubstrateBundle(deps),
+    postWire: (entry, deps) => safariPostWire(entry, deps),
+});