browxai 0.7.0

package/dist/engine/adapters/android-cdp.js

@@ -0,0 +1,110 @@
+// AndroidCdpAdapter — the FOURTH BrowserEngine adapter. The
+// surviving full-fidelity real-profile BYOB lane: real Chrome-on-Android attached
+// over adb + CDP. The KEY property is that Android Chrome speaks FULL CDP, so this
+// adapter:
+//   - declares `deep: true` (ANDROID_CAPABILITIES) — every tool works, including
+//     the CDP-deep ones (perf / coverage / heap / cpu / clock / CDP input);
+//   - mints an eager CDP session on attach, just like the Chromium adapter;
+//   - reuses the EXISTING CdpSnapshotSubstrate / CdpNetworkSubstrate verbatim
+//     (the substrate selectors key on CDP presence, so Android falls into the
+//     chromium-substrate path automatically — NO new substrate code).
+//
+// This is the smallest, lowest-risk adapter precisely because it adds no new
+// substrate. The only genuinely new code is the adb plumbing (./adb.ts) — device
+// discovery, socket forward, /json/version → wsUrl, port management, cleanup.
+//
+// ATTACH is the real path: discover the Chrome DevTools socket on a connected
+// device (`adb forward tcp:<port> localabstract:chrome_devtools_remote`), GET
+// http://127.0.0.1:<port>/json/version → webSocketDebuggerUrl, then
+// `chromium.connectOverCDP(wsUrl)`. This attaches to the user's REAL Chrome-on-
+// Android — the BYOB win. The forwarded socket is loopback (adb forwards to
+// 127.0.0.1), so byob.ts's loopback / not-owned policy applies verbatim.
+//
+// connectOverCDP vs `playwright._android`: we PREFER connectOverCDP. Both reach
+// the same CDP. `_android` is a separate experimental device API
+// (`playwright._android.devices()` → `AndroidDevice`) that owns its own adb
+// orchestration and returns a device-shaped object, NOT a `Browser`/`CDPSession`
+// pair the rest of browxai is built on. connectOverCDP returns the exact
+// `Browser` + `newCDPSession` handles the Chromium adapter already wires
+// (attachOverCdp in playwright-chromium.ts), so the substrate selectors, the
+// network tap, the a11y substrate, and teardown all work UNCHANGED. We keep the
+// adb orchestration explicit (./adb.ts) rather than hand it to `_android`, which
+// reuses the most existing code and keeps the seam at the same boundary as the
+// desktop BYOB path. (Measured against the installed Playwright 1.60:
+// `chromium.connectOverCDP` is a function; `_android` is an experimental device
+// API, not a `connectOverCDP` substitute.)
+//
+// LAUNCH is not a thing on Android the same way: managed/ephemeral launch means
+// "spawn a browser process we own", which on a phone the user controls makes no
+// sense — the user opens Chrome on their device. So launch returns a structured
+// `android-launch-not-supported`; Android is attach-only.
+import { resolveBrowserType } from "../select.js";
+import { capabilitiesFor } from "../capabilities.js";
+import { defaultAdbRunner, defaultFetcher, pickFreePort, devicesArgs, forwardArgs, forwardRemoveArgs, parseDevices, selectDevice, versionUrl, extractWsUrl, } from "./adb.js";
+export class AndroidCdpAdapter {
+    engine = "android";
+    capabilities;
+    runAdb;
+    fetchJson;
+    pickPort;
+    constructor(deps = {}) {
+        // android always has a declaration (see capabilities.ts).
+        this.capabilities = capabilitiesFor("android");
+        this.runAdb = deps.runAdb ?? defaultAdbRunner;
+        this.fetchJson = deps.fetchJson ?? defaultFetcher;
+        this.pickPort = deps.pickPort ?? pickFreePort;
+    }
+    /** Discover a ready device. Lists devices via adb, parses, and selects (the
+     *  requested serial if given, else the single ready one — structured errors
+     *  otherwise). Surfaces `adb-missing` / `no-device` without a device crash. */
+    async discoverDevice(serial) {
+        const stdout = await this.runAdb(devicesArgs());
+        const device = selectDevice(parseDevices(stdout), serial);
+        return device.serial;
+    }
+    /** The real BYOB path: discover device → forward the Chrome DevTools socket to
+     *  a free loopback port → GET /json/version → webSocketDebuggerUrl →
+     *  `chromium.connectOverCDP(wsUrl)`. Returns the `Browser` + eager `CDPSession`
+     *  the session layer wires its bookkeeping onto, exactly like the Chromium
+     *  attach, plus the forward-teardown handle. On any failure after the forward
+     *  is established, the forward is removed before the error propagates (no leaked
+     *  adb forwards). */
+    async attach(opts = {}) {
+        const serial = await this.discoverDevice(opts.serial);
+        const localPort = await this.pickPort();
+        await this.runAdb(forwardArgs(localPort, serial));
+        const removeForward = async () => {
+            await this.runAdb(forwardRemoveArgs(localPort, serial)).catch(() => undefined);
+        };
+        try {
+            const versionBody = await this.fetchJson(versionUrl(localPort));
+            const wsUrl = extractWsUrl(versionBody);
+            // `android` resolves to the chromium BrowserType — connectOverCDP returns
+            // the exact Browser the desktop BYOB path uses (attachOverCdp), so the
+            // eager CDP session, the substrates, and teardown all work unchanged.
+            const browserType = resolveBrowserType(this.engine);
+            const browser = await browserType.connectOverCDP(wsUrl);
+            const context = browser.contexts()[0] ?? (await browser.newContext());
+            const page = context.pages()[0] ?? (await context.newPage());
+            const cdp = await context.newCDPSession(page);
+            return { browser, page, cdp, localPort, serial, removeForward };
+        }
+        catch (err) {
+            await removeForward();
+            throw err;
+        }
+    }
+    /** Managed / ephemeral LAUNCH is not supported on Android. A phone's Chrome is
+     *  the user's to open; browxai cannot spawn a browser process it owns on the
+     *  device. Per the doctrine's no-silent-no-op rule this rejects with a
+     *  structured, RFC-naming error rather than pretending. Promise-returning (not
+     *  `async`) so the eslint require-await rule is honest — there is no awaited
+     *  work, it is a structured refusal. */
+    launch() {
+        return Promise.reject(new Error("android-launch-not-supported: the android engine is ATTACH-ONLY. managed / ephemeral " +
+            "launch means spawning a browser process browxai owns, which is not a thing on a phone " +
+            "the user controls — the user opens Chrome on their device, and browxai attaches over " +
+            'adb + CDP. Open the session with mode:"attached" (BROWX_ATTACH_CDP ' +
+            "is loopback-enforced; the adb forward is loopback by construction)."));
+    }
+}

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

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

package/dist/engine/adapters/android.engine.js

@@ -0,0 +1,31 @@
+// Android engine registration (RFC 0004 D1). Android is real Chrome-on-Android
+// attached over adb + CDP — it IS Chromium, so it reuses the shared Playwright
+// substrate bundle (CDP present → the verbatim CDP snapshot/network substrates)
+// and the full Playwright post-wire. It is ATTACH-ONLY: managed / incognito launch
+// (spawning a browser we own) is not a thing on the user's phone, so those modes
+// surface the adapter's structured `android-launch-not-supported`. BYOB attaches
+// over adb via `openAndroidByobSession` (endpoint discovered, not URL-configured).
+import { registerEngine } from "../registry.js";
+import { capabilitiesFor } from "../capabilities.js";
+import { AndroidCdpAdapter } from "./android-cdp.js";
+import { playwrightSubstrateBundle } from "../../page/substrate-bundle.js";
+import { playwrightPostWire } from "../../session/playwright-post-wire.js";
+import { openAndroidByobSession } from "../../session/byob-attach.js";
+async function makeAndroidAdapter(opts) {
+    const mode = opts.launchMode ?? "managed";
+    if (mode === "byob") {
+        return openAndroidByobSession();
+    }
+    // managed / incognito — spawning a browser we own is not a thing on a phone;
+    // the adapter's launch path returns the structured `android-launch-not-supported`
+    // refusal (it throws, never returns).
+    await new AndroidCdpAdapter().launch();
+    throw new Error("unreachable: android launch always refuses");
+}
+registerEngine({
+    kind: "android",
+    capabilities: capabilitiesFor("android"),
+    makeAdapter: makeAndroidAdapter,
+    makeSubstrates: (deps) => playwrightSubstrateBundle(deps),
+    postWire: (entry, deps) => playwrightPostWire(entry, deps),
+});

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

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

package/dist/engine/adapters/chromium.engine.js

@@ -0,0 +1,44 @@
+// Chromium engine registration (RFC 0004 D1). Registers the one `EngineEntry`
+// for the chromium engine — the byte-identity-critical path. No adapter LOGIC
+// moves here: the Playwright launch calls stay in `PlaywrightChromiumAdapter`,
+// the substrate selection delegates to the existing CDP/Playwright selectors, and
+// the post-wire is the full Playwright bookkeeping set (the always-true branch the
+// three factories ran for every non-Safari engine). This is pure wiring
+// relocation behind the registry — the chromium CDP path is verbatim.
+import { registerEngine } from "../registry.js";
+import { capabilitiesFor } from "../capabilities.js";
+import { playwrightSubstrateBundle } from "../../page/substrate-bundle.js";
+import { playwrightPostWire } from "../../session/playwright-post-wire.js";
+import { buildManagedLaunch, buildIncognitoContextOptions, buildIncognitoLaunchOptions, finalizeManagedSession, finalizeIncognitoSession, } from "../../session/launch-options.js";
+import { PlaywrightChromiumAdapter } from "./playwright-chromium.js";
+import { attachByobChromium } from "../../session/byob-attach.js";
+/** Build a chromium `BrowserSession` for the requested launch mode. The
+ *  per-engine launch dispatch the three factories carried (`engine === "…"`)
+ *  collapses to this one method; the mode is threaded via `opts.launchMode`
+ *  (defaulting to managed). Every option-built value + adapter call is the verbatim
+ *  pre-seam chromium path, so the chromium keystone stays byte-identical. */
+async function makeChromiumAdapter(opts) {
+    const mode = opts.launchMode ?? "managed";
+    if (mode === "byob") {
+        return attachByobChromium(opts);
+    }
+    if (mode === "incognito") {
+        const adapter = new PlaywrightChromiumAdapter();
+        const { browser, context, page, cdp } = await adapter.launchEphemeral({
+            launchOptions: buildIncognitoLaunchOptions("chromium", opts),
+            contextOptions: buildIncognitoContextOptions(opts),
+        });
+        return finalizeIncognitoSession("chromium", { browser, context, page, cdp });
+    }
+    const { profileDir, options } = buildManagedLaunch("chromium", opts);
+    const adapter = new PlaywrightChromiumAdapter();
+    const { context, page, cdp } = await adapter.launchPersistent({ profileDir, options });
+    return finalizeManagedSession("chromium", opts, profileDir, { context, page, cdp });
+}
+registerEngine({
+    kind: "chromium",
+    capabilities: capabilitiesFor("chromium"),
+    makeAdapter: makeChromiumAdapter,
+    makeSubstrates: (deps) => playwrightSubstrateBundle(deps),
+    postWire: (entry, deps) => playwrightPostWire(entry, deps),
+});

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

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

package/dist/engine/adapters/firefox.engine.js

@@ -0,0 +1,43 @@
+// Firefox engine registration (RFC 0004 D1). Registers the one `EngineEntry` for
+// the firefox engine. No adapter logic moves: the Juggler launch stays in
+// `PlaywrightFirefoxAdapter`; the substrate bundle is the shared Playwright one
+// (firefox has a Page, no CDP → the page-side snapshot walker + Playwright network
+// substrate are selected by CDP-absence); the post-wire is the full Playwright set.
+// BYOB attach surfaces the adapter's structured `firefox-attach-not-supported`.
+import { registerEngine } from "../registry.js";
+import { capabilitiesFor } from "../capabilities.js";
+import { PlaywrightFirefoxAdapter, firefoxChannelFromEnv } from "./playwright-firefox.js";
+import { playwrightSubstrateBundle } from "../../page/substrate-bundle.js";
+import { playwrightPostWire } from "../../session/playwright-post-wire.js";
+import { buildManagedLaunch, buildIncognitoContextOptions, finalizeManagedSession, finalizeIncognitoSession, } from "../../session/launch-options.js";
+import { assertByobAttach } from "../../session/byob-attach.js";
+async function makeFirefoxAdapter(opts) {
+    const mode = opts.launchMode ?? "managed";
+    if (mode === "byob") {
+        // Firefox attach is a glass-box LAUNCH over BiDi, not CDP-attach — Playwright
+        // has no `connectOverBiDi` for a user's running Firefox. Surface the
+        // structured `firefox-attach-not-supported` error (no silent fail).
+        const url = assertByobAttach(opts);
+        await new PlaywrightFirefoxAdapter().attach(url);
+        throw new Error("unreachable: firefox attach always refuses");
+    }
+    if (mode === "incognito") {
+        const adapter = new PlaywrightFirefoxAdapter({ channel: firefoxChannelFromEnv() });
+        const { browser, context, page } = await adapter.launchEphemeral({
+            launchOptions: { headless: !!opts.headless },
+            contextOptions: buildIncognitoContextOptions(opts),
+        });
+        return finalizeIncognitoSession("firefox", { browser, context, page });
+    }
+    const { profileDir, options } = buildManagedLaunch("firefox", opts);
+    const adapter = new PlaywrightFirefoxAdapter({ channel: firefoxChannelFromEnv() });
+    const { context, page } = await adapter.launchPersistent({ profileDir, options });
+    return finalizeManagedSession("firefox", opts, profileDir, { context, page });
+}
+registerEngine({
+    kind: "firefox",
+    capabilities: capabilitiesFor("firefox"),
+    makeAdapter: makeFirefoxAdapter,
+    makeSubstrates: (deps) => playwrightSubstrateBundle(deps),
+    postWire: (entry, deps) => playwrightPostWire(entry, deps),
+});

package/dist/engine/adapters/playwright-chromium.d.ts

@@ -0,0 +1,43 @@
+import type { Browser, BrowserContext, BrowserContextOptions, CDPSession, LaunchOptions, Page } from "playwright-core";
+import { resolveBrowserType } from "../select.js";
+import type { EngineCapabilities, EngineKind } from "../types.js";
+/** Chromium always mints an eager CDP session, so its launch handles carry a
+ *  required `cdp` — tighter than the port's optional-`cdp` `EngineLaunchHandles`
+ *  so callers don't need a non-null assertion on the Chromium path. */
+export interface ChromiumLaunchHandles {
+    browser?: Browser;
+    context: BrowserContext;
+    page: Page;
+    cdp: CDPSession;
+}
+/** Options for a persistent (managed) launch — the subset the managed factory
+ *  passes to `launchPersistentContext` today. */
+export interface PersistentLaunchSpec {
+    profileDir: string;
+    options: Parameters<ReturnType<typeof resolveBrowserType>["launchPersistentContext"]>[1];
+}
+/** Options for an ephemeral (incognito) launch — a `launch` + `newContext`
+ *  pair, exactly as the incognito factory builds it today. */
+export interface EphemeralLaunchSpec {
+    launchOptions: LaunchOptions;
+    contextOptions: BrowserContextOptions;
+}
+/** The Chromium engine adapter. One instance per launch; it owns the engine
+ *  selection + the eager CDP session, and surfaces the handles the session
+ *  layer wires its bookkeeping onto. */
+export declare class PlaywrightChromiumAdapter {
+    readonly engine: EngineKind;
+    readonly capabilities: EngineCapabilities;
+    constructor();
+    /** Persistent-profile launch — wraps `launchPersistentContext` + the eager
+     *  `newCDPSession`. Mirrors openManagedSession's pre-seam body verbatim. */
+    launchPersistent(spec: PersistentLaunchSpec): Promise<ChromiumLaunchHandles>;
+    /** Ephemeral launch — wraps `launch` + `newContext` + the eager
+     *  `newCDPSession`. Mirrors openIncognitoSession's pre-seam body verbatim. */
+    launchEphemeral(spec: EphemeralLaunchSpec): Promise<ChromiumLaunchHandles>;
+    /** BYOB attach over CDP — wraps `connectOverCDP` + the eager `newCDPSession`.
+     *  The loopback / not-owned policy stays in byob.ts because it is
+     *  protocol-neutral; only this transport hop is engine-specific. Mirrors
+     *  openByobSession's pre-seam connect body verbatim. */
+    attachOverCdp(endpoint: string): Promise<ChromiumLaunchHandles>;
+}

package/dist/engine/adapters/playwright-chromium.js

@@ -0,0 +1,56 @@
+// PlaywrightChromiumAdapter — the first BrowserEngine adapter. This is where
+// today's Chromium/CDP behavior lives now: it WRAPS the exact Playwright calls
+// the three session factories used inline before the seam existed
+// (`chromium.launchPersistentContext`, `chromium.launch` + `newContext`,
+// `chromium.connectOverCDP`), and mints the eager `CDPSession` Chromium needs.
+// It does not reimplement anything — the launch options, flags, and ordering
+// are byte-identical to the pre-seam factories.
+//
+// The browser-type is resolved through `resolveBrowserType("chromium")` so the
+// selection seam is exercised by the only engine currently wired up;
+// firefox/webkit route through the same resolver and hit
+// `EngineNotYetSupportedError`.
+import { resolveBrowserType } from "../select.js";
+import { capabilitiesFor } from "../capabilities.js";
+/** The Chromium engine adapter. One instance per launch; it owns the engine
+ *  selection + the eager CDP session, and surfaces the handles the session
+ *  layer wires its bookkeeping onto. */
+export class PlaywrightChromiumAdapter {
+    engine = "chromium";
+    capabilities;
+    constructor() {
+        // chromium always has a declaration (see capabilities.ts).
+        this.capabilities = capabilitiesFor("chromium");
+    }
+    /** Persistent-profile launch — wraps `launchPersistentContext` + the eager
+     *  `newCDPSession`. Mirrors openManagedSession's pre-seam body verbatim. */
+    async launchPersistent(spec) {
+        const browserType = resolveBrowserType(this.engine);
+        const context = await browserType.launchPersistentContext(spec.profileDir, spec.options);
+        const page = context.pages()[0] ?? (await context.newPage());
+        const cdp = await context.newCDPSession(page);
+        return { context, page, cdp };
+    }
+    /** Ephemeral launch — wraps `launch` + `newContext` + the eager
+     *  `newCDPSession`. Mirrors openIncognitoSession's pre-seam body verbatim. */
+    async launchEphemeral(spec) {
+        const browserType = resolveBrowserType(this.engine);
+        const browser = await browserType.launch(spec.launchOptions);
+        const context = await browser.newContext(spec.contextOptions);
+        const page = await context.newPage();
+        const cdp = await context.newCDPSession(page);
+        return { browser, context, page, cdp };
+    }
+    /** BYOB attach over CDP — wraps `connectOverCDP` + the eager `newCDPSession`.
+     *  The loopback / not-owned policy stays in byob.ts because it is
+     *  protocol-neutral; only this transport hop is engine-specific. Mirrors
+     *  openByobSession's pre-seam connect body verbatim. */
+    async attachOverCdp(endpoint) {
+        const browserType = resolveBrowserType(this.engine);
+        const browser = await browserType.connectOverCDP(endpoint);
+        const context = browser.contexts()[0] ?? (await browser.newContext());
+        const page = context.pages()[0] ?? (await context.newPage());
+        const cdp = await context.newCDPSession(page);
+        return { browser, context, page, cdp };
+    }
+}

package/dist/engine/adapters/playwright-firefox.d.ts

@@ -0,0 +1,52 @@
+import type { BrowserContextOptions, LaunchOptions } from "playwright-core";
+import { resolveBrowserType } from "../select.js";
+import type { EngineCapabilities, EngineKind, EngineLaunchHandles } from "../types.js";
+/** Persistent (managed) launch spec — the subset the managed factory passes to
+ *  `launchPersistentContext`. Same shape as the chromium adapter's so the
+ *  session factories thread one spec regardless of engine. */
+export interface FirefoxPersistentLaunchSpec {
+    profileDir: string;
+    options: Parameters<ReturnType<typeof resolveBrowserType>["launchPersistentContext"]>[1];
+}
+/** Ephemeral (incognito) launch spec — a `launch` + `newContext` pair. */
+export interface FirefoxEphemeralLaunchSpec {
+    launchOptions: LaunchOptions;
+    contextOptions: BrowserContextOptions;
+}
+/** The experimental stock-Firefox BiDi channel name (Playwright `channel`).
+ *  Selected via `BROWX_FIREFOX_CHANNEL=moz-firefox`. */
+export declare const MOZ_FIREFOX_CHANNEL = "moz-firefox";
+/** Resolve the optional `BROWX_FIREFOX_CHANNEL` flag. Returns the channel string
+ *  to pass to Playwright's `launch`/`launchPersistentContext`, or undefined for
+ *  the default Juggler lane. Only `moz-firefox` is recognised; any other value
+ *  is rejected loudly (no silent fallback). */
+export declare function firefoxChannelFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
+/** The Firefox engine adapter. One instance per launch; it owns engine
+ *  selection and surfaces the handles the session layer wires its bookkeeping
+ *  onto. Unlike the chromium adapter it carries no `cdp` on its handles —
+ *  Firefox has no CDP escape hatch. */
+export declare class PlaywrightFirefoxAdapter {
+    readonly engine: EngineKind;
+    readonly capabilities: EngineCapabilities;
+    private readonly channel;
+    constructor(opts?: {
+        channel?: string;
+    });
+    /** Persistent-profile launch — wraps `launchPersistentContext`. No eager CDP
+     *  session (Firefox has none). Mirrors the chromium adapter's shape. */
+    launchPersistent(spec: FirefoxPersistentLaunchSpec): Promise<EngineLaunchHandles>;
+    /** Ephemeral launch — wraps `launch` + `newContext`. No eager CDP session. */
+    launchEphemeral(spec: FirefoxEphemeralLaunchSpec): Promise<EngineLaunchHandles>;
+    /** BYOB attach. The Firefox attach model is a glass-box LAUNCH of
+     *  the user's real profile with `--remote-debugging-port`, NOT a CDP-attach —
+     *  and Playwright has no public `connectOverBiDi` for a user's running
+     *  Firefox. Until a BiDi attach client exists this rejects with a structured,
+     *  explanatory error rather than silently failing (the doctrine's
+     *  no-silent-no-op rule). The `BROWX_ATTACH_BIDI` name is reserved for it.
+     *  Promise-returning (not `async`) so the eslint require-await rule is honest:
+     *  there is no awaited work — it is a structured refusal. */
+    attach(_endpoint: string): Promise<EngineLaunchHandles>;
+    /** Splice the optional `moz-firefox` BiDi channel into a launch options bag.
+     *  No-op for the default Juggler lane. */
+    private withChannel;
+}

package/dist/engine/adapters/playwright-firefox.js

@@ -0,0 +1,97 @@
+// PlaywrightFirefoxAdapter — the second BrowserEngine adapter, the proof the
+// port generalizes to a second engine. It mirrors PlaywrightChromiumAdapter's
+// three launch shapes over `resolveBrowserType("firefox")` (Playwright's bundled
+// Juggler Firefox, the default supported lane) — but it mints NO eager CDP
+// session: `newCDPSession` throws on Firefox (measured), and Firefox declares
+// `deep: false`, so the raw-CDP escape hatch is absent. Sessions on this engine
+// run the cross-browser surface; the ~19 CDP-hard tools structured-refuse via
+// the engine gate (src/engine/tool-gate.ts).
+//
+// Dependency direction (architecture doctrine): port → adapter → Playwright.
+// The adapter delegates directly to Playwright on the per-action path exactly
+// like the chromium one — no added allocation on the hot path.
+//
+// Two-track design: the default lane is Juggler (full Playwright API — routes,
+// video, HAR — so the ~139 class-A tools are real). The experimental stock-
+// Firefox `moz-firefox` BiDi channel rides behind `BROWX_FIREFOX_CHANNEL`
+// (see firefoxChannelFromEnv); it is NOT gated by the keystone. Measured against
+// the installed Playwright: the channel IS recognised (it launches a real BiDi
+// session against stock Firefox) but the session immediately hits a Mozilla-side
+// BiDi gap (`network.addDataCollector: unknown command`) — the M20 streaming /
+// network gaps the research predicted. So the flag is wired and the channel
+// resolves; stock-Firefox-BiDi is just not usable for browxai's surface yet.
+// Flip the default to this lane when Mozilla M20 closes.
+import { resolveBrowserType } from "../select.js";
+import { capabilitiesFor } from "../capabilities.js";
+/** The experimental stock-Firefox BiDi channel name (Playwright `channel`).
+ *  Selected via `BROWX_FIREFOX_CHANNEL=moz-firefox`. */
+export const MOZ_FIREFOX_CHANNEL = "moz-firefox";
+/** Resolve the optional `BROWX_FIREFOX_CHANNEL` flag. Returns the channel string
+ *  to pass to Playwright's `launch`/`launchPersistentContext`, or undefined for
+ *  the default Juggler lane. Only `moz-firefox` is recognised; any other value
+ *  is rejected loudly (no silent fallback). */
+export function firefoxChannelFromEnv(env = process.env) {
+    const raw = env.BROWX_FIREFOX_CHANNEL?.trim();
+    if (!raw)
+        return undefined;
+    if (raw !== MOZ_FIREFOX_CHANNEL) {
+        throw new Error(`BROWX_FIREFOX_CHANNEL: unknown value "${raw}". The only supported value is ` +
+            `"${MOZ_FIREFOX_CHANNEL}" (the experimental stock-Firefox WebDriver-BiDi channel). ` +
+            "Unset it for the default bundled-Juggler lane.");
+    }
+    return MOZ_FIREFOX_CHANNEL;
+}
+/** The Firefox engine adapter. One instance per launch; it owns engine
+ *  selection and surfaces the handles the session layer wires its bookkeeping
+ *  onto. Unlike the chromium adapter it carries no `cdp` on its handles —
+ *  Firefox has no CDP escape hatch. */
+export class PlaywrightFirefoxAdapter {
+    engine = "firefox";
+    capabilities;
+    channel;
+    constructor(opts = {}) {
+        // firefox always has a declaration (see capabilities.ts).
+        this.capabilities = capabilitiesFor("firefox");
+        this.channel = opts.channel;
+    }
+    /** Persistent-profile launch — wraps `launchPersistentContext`. No eager CDP
+     *  session (Firefox has none). Mirrors the chromium adapter's shape. */
+    async launchPersistent(spec) {
+        const browserType = resolveBrowserType(this.engine);
+        const options = this.withChannel(spec.options);
+        const context = await browserType.launchPersistentContext(spec.profileDir, options);
+        const page = context.pages()[0] ?? (await context.newPage());
+        return { context, page };
+    }
+    /** Ephemeral launch — wraps `launch` + `newContext`. No eager CDP session. */
+    async launchEphemeral(spec) {
+        const browserType = resolveBrowserType(this.engine);
+        const browser = await browserType.launch(this.withChannel(spec.launchOptions));
+        const context = await browser.newContext(spec.contextOptions);
+        const page = await context.newPage();
+        return { browser, context, page };
+    }
+    /** BYOB attach. The Firefox attach model is a glass-box LAUNCH of
+     *  the user's real profile with `--remote-debugging-port`, NOT a CDP-attach —
+     *  and Playwright has no public `connectOverBiDi` for a user's running
+     *  Firefox. Until a BiDi attach client exists this rejects with a structured,
+     *  explanatory error rather than silently failing (the doctrine's
+     *  no-silent-no-op rule). The `BROWX_ATTACH_BIDI` name is reserved for it.
+     *  Promise-returning (not `async`) so the eslint require-await rule is honest:
+     *  there is no awaited work — it is a structured refusal. */
+    attach(_endpoint) {
+        return Promise.reject(new Error("firefox-attach-not-supported: browxai cannot attach to a running Firefox over CDP. " +
+            "Firefox removed CDP in v141; the forward path is WebDriver BiDi, and Playwright has no " +
+            "public `connectOverBiDi` for a user's running Firefox yet (the `BROWX_ATTACH_BIDI` name " +
+            "is reserved for it). The Firefox BYOB model is a glass-box LAUNCH of the " +
+            "real profile with `--remote-debugging-port`, subject to the profile lock. Use a managed " +
+            "Firefox session (the default), or a chromium session for CDP-attach BYOB."));
+    }
+    /** Splice the optional `moz-firefox` BiDi channel into a launch options bag.
+     *  No-op for the default Juggler lane. */
+    withChannel(options) {
+        if (!this.channel)
+            return options;
+        return { ...(options ?? {}), channel: this.channel };
+    }
+}

package/dist/engine/adapters/playwright-webkit.d.ts

@@ -0,0 +1,40 @@
+import type { BrowserContextOptions, LaunchOptions } from "playwright-core";
+import { resolveBrowserType } from "../select.js";
+import type { EngineCapabilities, EngineKind, EngineLaunchHandles } from "../types.js";
+/** Persistent (managed) launch spec — the subset the managed factory passes to
+ *  `launchPersistentContext`. Same shape as the chromium/firefox adapters' so the
+ *  session factories thread one spec regardless of engine. */
+export interface WebKitPersistentLaunchSpec {
+    profileDir: string;
+    options: Parameters<ReturnType<typeof resolveBrowserType>["launchPersistentContext"]>[1];
+}
+/** Ephemeral (incognito) launch spec — a `launch` + `newContext` pair. */
+export interface WebKitEphemeralLaunchSpec {
+    launchOptions: LaunchOptions;
+    contextOptions: BrowserContextOptions;
+}
+/** The WebKit engine adapter. One instance per launch; it owns engine selection
+ *  and surfaces the handles the session layer wires its bookkeeping onto. Like
+ *  the firefox adapter it carries no `cdp` on its handles — WebKit has no CDP
+ *  escape hatch (measured: `newCDPSession` throws off Chromium). */
+export declare class PlaywrightWebKitAdapter {
+    readonly engine: EngineKind;
+    readonly capabilities: EngineCapabilities;
+    constructor();
+    /** Persistent-profile launch — wraps `launchPersistentContext`. No eager CDP
+     *  session (WebKit has none). Mirrors the firefox adapter's shape. If a future
+     *  WebKit build lacks persistent-context support, `launchPersistentContext`
+     *  throws and the failure surfaces through the session factory (the
+     *  `webkit-persistent-not-supported` reason is reserved for a structured refusal). */
+    launchPersistent(spec: WebKitPersistentLaunchSpec): Promise<EngineLaunchHandles>;
+    /** Ephemeral launch — wraps `launch` + `newContext`. No eager CDP session. */
+    launchEphemeral(spec: WebKitEphemeralLaunchSpec): Promise<EngineLaunchHandles>;
+    /** BYOB attach. WebKit has no CDP attach client and no BiDi attach client
+     *  either (Safari has not shipped BiDi as of June 2026), and the
+     *  WebKit engine build exposes no remote-debugging attach surface browxai can
+     *  drive. Per the doctrine's no-silent-no-op rule this rejects with a
+     *  structured, RFC-naming error rather than failing quietly. Promise-returning
+     *  (not `async`) so the eslint require-await rule is honest: there is no awaited
+     *  work — it is a structured refusal. */
+    attach(_endpoint: string): Promise<EngineLaunchHandles>;
+}

package/dist/engine/adapters/playwright-webkit.js

@@ -0,0 +1,79 @@
+// PlaywrightWebKitAdapter — the THIRD BrowserEngine adapter.
+// It mirrors PlaywrightFirefoxAdapter's three launch shapes over
+// `resolveBrowserType("webkit")` (Playwright's bundled WebKit build — the
+// WebKit-ENGINE correctness lane, NOT Safari; a real-Safari surface is a
+// separate, tiered companion product, never a browxai engine
+// adapter). Like the Firefox adapter it mints NO eager CDP session — WebKit has
+// no CDP at all (measured: `newCDPSession` throws "CDP session is only available
+// in Chromium"), and `WEBKIT_CAPABILITIES` declares `deep: false`, so the raw-CDP
+// escape hatch is absent and the ~26 CDP-deep tools structured-refuse via the
+// CAPABILITY-based engine gate (src/engine/tool-gate.ts) with NO per-engine edit
+// — the gate keys on `deep:false`, not an engine name, so a new engine that drops
+// `deep` auto-gates. That is the open/closed-correct design the doctrine asks for.
+//
+// Dependency direction (architecture doctrine): port → adapter → Playwright. The
+// adapter delegates directly to Playwright on the per-action path exactly like
+// the chromium + firefox ones — no added allocation on the hot path.
+//
+// Substrates: both already engine-agnostic. WebKit (CDP-absent) selects the
+// page-side `PlaywrightSnapshotSubstrate` walker (`snapshotSubstrateFor` keys on
+// CDP capability, not engine name), so `snapshot`/`find`/`navigate`/`click`/
+// `fill`/`text_search`/`extract`/`set_of_marks`/`plan` work on WebKit with no
+// substrate code change. The network slice rides P2b's Playwright-event tap when
+// it lands (same as Firefox); until then WebKit's network slice is empty.
+//
+// Persistent mode: measured against the installed Playwright, WebKit DOES support
+// `launchPersistentContext` (unlike the "persistent-mode-on-WebKit is a
+// known loss" caveat, which is about real-Safari, not the WebKit engine build) —
+// so the managed path is real. Should a future Playwright/WebKit build drop it,
+// the launch throws and the session factory surfaces it; the reserved structured
+// reason name is `webkit-persistent-not-supported`.
+import { resolveBrowserType } from "../select.js";
+import { capabilitiesFor } from "../capabilities.js";
+/** The WebKit engine adapter. One instance per launch; it owns engine selection
+ *  and surfaces the handles the session layer wires its bookkeeping onto. Like
+ *  the firefox adapter it carries no `cdp` on its handles — WebKit has no CDP
+ *  escape hatch (measured: `newCDPSession` throws off Chromium). */
+export class PlaywrightWebKitAdapter {
+    engine = "webkit";
+    capabilities;
+    constructor() {
+        // webkit always has a declaration (see capabilities.ts).
+        this.capabilities = capabilitiesFor("webkit");
+    }
+    /** Persistent-profile launch — wraps `launchPersistentContext`. No eager CDP
+     *  session (WebKit has none). Mirrors the firefox adapter's shape. If a future
+     *  WebKit build lacks persistent-context support, `launchPersistentContext`
+     *  throws and the failure surfaces through the session factory (the
+     *  `webkit-persistent-not-supported` reason is reserved for a structured refusal). */
+    async launchPersistent(spec) {
+        const browserType = resolveBrowserType(this.engine);
+        const context = await browserType.launchPersistentContext(spec.profileDir, spec.options);
+        const page = context.pages()[0] ?? (await context.newPage());
+        return { context, page };
+    }
+    /** Ephemeral launch — wraps `launch` + `newContext`. No eager CDP session. */
+    async launchEphemeral(spec) {
+        const browserType = resolveBrowserType(this.engine);
+        const browser = await browserType.launch(spec.launchOptions);
+        const context = await browser.newContext(spec.contextOptions);
+        const page = await context.newPage();
+        return { browser, context, page };
+    }
+    /** BYOB attach. WebKit has no CDP attach client and no BiDi attach client
+     *  either (Safari has not shipped BiDi as of June 2026), and the
+     *  WebKit engine build exposes no remote-debugging attach surface browxai can
+     *  drive. Per the doctrine's no-silent-no-op rule this rejects with a
+     *  structured, RFC-naming error rather than failing quietly. Promise-returning
+     *  (not `async`) so the eslint require-await rule is honest: there is no awaited
+     *  work — it is a structured refusal. */
+    attach(_endpoint) {
+        return Promise.reject(new Error("webkit-attach-not-supported: browxai cannot attach to a running WebKit/Safari over CDP " +
+            "or BiDi. WebKit has no CDP escape hatch, and Safari has not shipped WebDriver BiDi as " +
+            "of June 2026 (safaridriver is WebDriver-Classic-only and hard-isolates automation into " +
+            "a clean ephemeral window — attach-to-the-live-session is impossible by design). The " +
+            "WebKit engine lane is correctness-only (managed sessions); real-Safari BYOB " +
+            "is a separate, tiered companion surface (AppleScript / Web-Extension), not a browxai " +
+            "engine adapter. Use a managed WebKit session, or a chromium session for CDP-attach BYOB."));
+    }
+}