@crewhaus/computer-use-driver 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@crewhaus/computer-use-driver",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cross-platform mouse/keyboard/screenshot driver — chromium backend (Section 25 BROW)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "peerDependencies": {
+    "playwright": "*"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/computer-use-driver"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/computer-use-driver#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/backends/backends.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Section 30 — host + remote driver contract tests.
+ */
+import { describe, expect, test } from "bun:test";
+import { ComputerUseDriverError, type Viewport } from "../index";
+import { type HostExecutor, createHostDriver } from "./host";
+import { type PuppeteerCoreLike, createRemoteDriver } from "./remote";
+
+describe("host driver — Section 30", () => {
+  test("disabled flag → throws on construction", () => {
+    expect(() => createHostDriver({ enabled: false, executor: {} as never })).toThrow(
+      ComputerUseDriverError,
+    );
+  });
+
+  test("connect + click + screenshot delegates to executor", async () => {
+    const calls: string[] = [];
+    const viewport: Viewport = { width: 1920, height: 1080, devicePixelRatio: 1 };
+    const executor: HostExecutor = {
+      async click(x, y, button) {
+        calls.push(`click ${x},${y} ${button}`);
+      },
+      async type(text) {
+        calls.push(`type ${text}`);
+      },
+      async key(combo) {
+        calls.push(`key ${combo}`);
+      },
+      async scroll(x, y, dx, dy) {
+        calls.push(`scroll ${x},${y} ${dx},${dy}`);
+      },
+      async screenshot() {
+        calls.push("screenshot");
+        // "iVBORw0KGgo=" decodes to the PNG magic bytes (0x89 0x50 0x4E 0x47 ...).
+        return { pngBase64: "iVBORw0KGgo=", viewport };
+      },
+    };
+    const driver = createHostDriver({ enabled: true, executor });
+    await driver.connect();
+    await driver.click(100, 200, "left");
+    const shot = await driver.screenshot();
+    expect(shot).toBeInstanceOf(Uint8Array);
+    expect(shot[0]).toBe(0x89);
+    expect(shot[1]).toBe(0x50);
+    expect(calls).toEqual(["click 100,200 left", "screenshot"]);
+  });
+
+  test("scroll delegates to executor with zero anchor", async () => {
+    const calls: string[] = [];
+    const executor: HostExecutor = {
+      async click() {},
+      async type() {},
+      async key() {},
+      async scroll(x, y, dx, dy) {
+        calls.push(`scroll ${x},${y} ${dx},${dy}`);
+      },
+      async screenshot() {
+        return {
+          pngBase64: "",
+          viewport: { width: 0, height: 0, devicePixelRatio: 1 },
+        };
+      },
+    };
+    const driver = createHostDriver({ enabled: true, executor });
+    await driver.connect();
+    await driver.scroll(10, 20);
+    expect(calls).toEqual(["scroll 0,0 10,20"]);
+  });
+
+  test("operations before connect throw", async () => {
+    const executor = {
+      async click() {},
+      async type() {},
+      async key() {},
+      async scroll() {},
+      async screenshot() {
+        return {
+          pngBase64: "",
+          viewport: { width: 0, height: 0, devicePixelRatio: 1 },
+        };
+      },
+    } as HostExecutor;
+    const driver = createHostDriver({ enabled: true, executor });
+    await expect(driver.click(0, 0)).rejects.toBeInstanceOf(ComputerUseDriverError);
+  });
+
+  test("goto throws — host backend cannot navigate URLs", async () => {
+    const driver = createHostDriver({
+      enabled: true,
+      executor: {
+        async screenshot() {
+          return {
+            pngBase64: "",
+            viewport: { width: 0, height: 0, devicePixelRatio: 1 },
+          };
+        },
+      } as HostExecutor,
+    });
+    await driver.connect();
+    await expect(driver.goto("https://x.com")).rejects.toBeInstanceOf(ComputerUseDriverError);
+  });
+});
+
+describe("remote driver — Section 30", () => {
+  test("missing url throws on construction", () => {
+    expect(() => createRemoteDriver({ url: "" })).toThrow(ComputerUseDriverError);
+  });
+
+  test("connect without _puppeteer throws with install hint", async () => {
+    const driver = createRemoteDriver({ url: "ws://test" });
+    await expect(driver.connect()).rejects.toThrow(/puppeteer-core/);
+  });
+
+  test("connect + screenshot + click delegate to puppeteer-core stub", async () => {
+    const ops: string[] = [];
+    const stubPage = {
+      async goto(url: string) {
+        ops.push(`goto ${url}`);
+      },
+      async screenshot() {
+        ops.push("screenshot");
+        return Buffer.from("png-data");
+      },
+      mouse: {
+        async click(x: number, y: number, opts?: { button?: string }) {
+          ops.push(`click ${x},${y} ${opts?.button}`);
+        },
+      },
+      keyboard: {
+        async type(text: string) {
+          ops.push(`type ${text}`);
+        },
+        async press(key: string) {
+          ops.push(`press ${key}`);
+        },
+      },
+      async evaluate<T>(_fn: () => T) {
+        return undefined as unknown as T;
+      },
+      async close() {
+        ops.push("close-page");
+      },
+    };
+    const stubBrowser = {
+      async newPage() {
+        return stubPage;
+      },
+      async close() {
+        ops.push("close-browser");
+      },
+    };
+    const stubPuppeteer: PuppeteerCoreLike = {
+      async connect(_opts) {
+        ops.push("connect");
+        return stubBrowser as never;
+      },
+    };
+    const driver = createRemoteDriver({ url: "ws://test", _puppeteer: stubPuppeteer });
+    await driver.connect();
+    await driver.goto("https://x.com");
+    await driver.click(50, 60, "right");
+    await driver.disconnect();
+    expect(ops).toContain("connect");
+    expect(ops).toContain("goto https://x.com");
+    expect(ops).toContain("click 50,60 right");
+    expect(ops).toContain("close-browser");
+  });
+});

package/src/backends/host.ts

@@ -0,0 +1,96 @@
+/**
+ * Section 30 — host backend for `computer-use-driver`. Drives the
+ * dev's actual desktop via the OS-level computer-use surface (macOS
+ * Quartz / Linux X11+xdotool / Windows SendInput). Production
+ * deployments use this for cross-app workflows that no browser can
+ * reach (Maps, Notes, Photos, Finder, native System Settings).
+ *
+ * **Safety gate:** the constructor refuses to return a working driver
+ * unless `CREWHAUS_BROW_HOST_ENABLED=1` is set in the environment. The
+ * goal is fail-loud ergonomics: deployment errors that try to use the
+ * host backend without explicit opt-in should immediately surface
+ * rather than silently driving the dev's machine.
+ *
+ * The OS-level command dispatch is delegated to a caller-supplied
+ * `HostExecutor` so tests + the smoke harness can stub the surface.
+ * In production, codegen wires a thin wrapper that shells out to
+ * `xdotool` (Linux), `cliclick` (macOS), or PowerShell (Windows).
+ */
+import { ComputerUseDriverError, type Driver, type Viewport } from "../index";
+
+export type HostExecutor = {
+  /** Click at absolute screen coordinates. Button: "left" | "right" | "middle". */
+  click(x: number, y: number, button: string): Promise<void>;
+  /** Type a string at the current focus. */
+  type(text: string): Promise<void>;
+  /** Press a single key (or modifier+key, e.g. "cmd+space"). */
+  key(combo: string): Promise<void>;
+  /** Scroll at absolute screen coordinates. */
+  scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
+  /** Capture a PNG screenshot of the entire screen, returning base64. */
+  screenshot(): Promise<{ pngBase64: string; viewport: Viewport }>;
+  /** Disconnect / clean up any handles. */
+  close?(): Promise<void>;
+};
+
+export type HostBackendOptions = {
+  /** Required to pass; otherwise the constructor throws. */
+  readonly enabled: boolean;
+  /** Test injection (or production OS shim). */
+  readonly executor: HostExecutor;
+};
+
+export function createHostDriver(opts: HostBackendOptions): Driver {
+  if (!opts.enabled) {
+    throw new ComputerUseDriverError(
+      "host backend disabled. Set CREWHAUS_BROW_HOST_ENABLED=1 to opt in (this drives the actual desktop — never enable in smoke tests).",
+    );
+  }
+  let connected = false;
+  return {
+    backend: "host",
+    async connect(): Promise<void> {
+      connected = true;
+    },
+    async goto(_url: string): Promise<void> {
+      // The host backend doesn't navigate URLs — callers should open
+      // a browser app first via the OS shell. We surface this as a
+      // soft-fail since some workflows want goto to be a no-op.
+      throw new ComputerUseDriverError(
+        "host backend cannot navigate URLs directly — open a browser via OS shell first",
+      );
+    },
+    async screenshot(): Promise<Uint8Array> {
+      if (!connected) throw new ComputerUseDriverError("host driver not connected");
+      const { pngBase64 } = await opts.executor.screenshot();
+      return Buffer.from(pngBase64, "base64");
+    },
+    async click(x: number, y: number, button = "left"): Promise<void> {
+      if (!connected) throw new ComputerUseDriverError("host driver not connected");
+      await opts.executor.click(x, y, button);
+    },
+    async type(text: string): Promise<void> {
+      if (!connected) throw new ComputerUseDriverError("host driver not connected");
+      await opts.executor.type(text);
+    },
+    async key(combo: string): Promise<void> {
+      if (!connected) throw new ComputerUseDriverError("host driver not connected");
+      await opts.executor.key(combo);
+    },
+    async scroll(dx: number, dy: number): Promise<void> {
+      if (!connected) throw new ComputerUseDriverError("host driver not connected");
+      // Driver.scroll has no cursor coords; pass (0, 0) for the executor's
+      // anchor and let the host shim scroll at the focused window's origin.
+      await opts.executor.scroll(0, 0, dx, dy);
+    },
+    async getViewport(): Promise<Viewport> {
+      if (!connected) throw new ComputerUseDriverError("host driver not connected");
+      const shot = await opts.executor.screenshot();
+      return shot.viewport;
+    },
+    async disconnect(): Promise<void> {
+      connected = false;
+      await opts.executor.close?.();
+    },
+  };
+}

package/src/backends/remote.ts

@@ -0,0 +1,127 @@
+/**
+ * Section 30 — remote backend for `computer-use-driver`. Connects to a
+ * remote chromium instance over Chrome DevTools Protocol (browserless.io,
+ * BrowserBase, self-hosted DevTools). Same `Driver` surface as the
+ * Playwright-backed `chromium` backend; the difference is the connection
+ * layer.
+ *
+ * Production deployments install `puppeteer-core` and pass it as
+ * `_puppeteer`. Without it, the constructor returns a driver whose
+ * `connect()` throws a clear diagnostic — matching the SQS / Vapi
+ * pattern of "abstraction always builds; deployment-time SDK presence
+ * gates the operation".
+ */
+import { ComputerUseDriverError, type Driver, type Viewport } from "../index";
+
+export type RemoteBackendOptions = {
+  /** Browserless / BrowserBase WebSocket endpoint. */
+  readonly url: string;
+  /** Optional viewport override; defaults to 1280×800. */
+  readonly viewport?: Viewport;
+  /**
+   * Test / production injection: `puppeteer-core` `import` namespace.
+   * When undefined, the driver throws at `connect()` with a hint to
+   * install puppeteer-core.
+   */
+  readonly _puppeteer?: PuppeteerCoreLike;
+};
+
+export type PuppeteerCoreLike = {
+  connect(opts: { browserWSEndpoint: string }): Promise<{
+    newPage(): Promise<{
+      goto(url: string): Promise<void>;
+      screenshot(opts?: { encoding?: "base64" }): Promise<string | Buffer>;
+      mouse: {
+        click(x: number, y: number, opts?: { button?: string }): Promise<void>;
+      };
+      keyboard: {
+        type(text: string): Promise<void>;
+        press(key: string): Promise<void>;
+      };
+      evaluate<T>(fn: () => T): Promise<T>;
+      close(): Promise<void>;
+    }>;
+    close(): Promise<void>;
+  }>;
+};
+
+export function createRemoteDriver(opts: RemoteBackendOptions): Driver {
+  if (!opts.url) throw new ComputerUseDriverError("remote backend requires url");
+  let browser: Awaited<ReturnType<NonNullable<typeof opts._puppeteer>["connect"]>> | undefined;
+  let page: Awaited<ReturnType<NonNullable<typeof browser>["newPage"]>> | undefined;
+  let connected = false;
+
+  function ensure(): NonNullable<typeof page> {
+    if (!page) throw new ComputerUseDriverError("remote driver not connected");
+    return page;
+  }
+
+  return {
+    backend: "remote",
+    async connect(): Promise<void> {
+      const pup = opts._puppeteer;
+      if (!pup) {
+        throw new ComputerUseDriverError(
+          "remote backend requires `puppeteer-core` to be installed and passed as `_puppeteer`. e.g. `import * as pc from 'puppeteer-core'; createDriver({ backend: 'remote', url, _puppeteer: pc })`.",
+        );
+      }
+      browser = await pup.connect({ browserWSEndpoint: opts.url });
+      page = await browser.newPage();
+      connected = true;
+    },
+    async goto(url: string): Promise<void> {
+      await ensure().goto(url);
+    },
+    async screenshot(): Promise<Uint8Array> {
+      const buffer = await ensure().screenshot({ encoding: "base64" });
+      const pngBase64 = typeof buffer === "string" ? buffer : buffer.toString("base64");
+      return Buffer.from(pngBase64, "base64");
+    },
+    async click(x: number, y: number, button = "left"): Promise<void> {
+      await ensure().mouse.click(x, y, { button });
+    },
+    async type(text: string): Promise<void> {
+      await ensure().keyboard.type(text);
+    },
+    async key(combo: string): Promise<void> {
+      await ensure().keyboard.press(combo);
+    },
+    async scroll(dx: number, dy: number): Promise<void> {
+      // Puppeteer doesn't expose mouse.wheel directly; dispatch from the
+      // page context where `window` is defined. The eval-with-args shape
+      // isn't on the local PuppeteerCoreLike type; cast to puppeteer's
+      // actual surface to call it.
+      const pageWithArgs = ensure() as unknown as {
+        evaluate(
+          fn: (d: { dx: number; dy: number }) => void,
+          arg: { dx: number; dy: number },
+        ): Promise<void>;
+      };
+      await pageWithArgs.evaluate(
+        (d: { dx: number; dy: number }) => {
+          (globalThis as unknown as { scrollBy: (dx: number, dy: number) => void }).scrollBy(
+            d.dx,
+            d.dy,
+          );
+        },
+        { dx, dy },
+      );
+    },
+    async getViewport(): Promise<Viewport> {
+      const v = opts.viewport;
+      if (v !== undefined) return v;
+      return { width: 1280, height: 800, devicePixelRatio: 1 };
+    },
+    async disconnect(): Promise<void> {
+      try {
+        if (page) await page.close();
+        if (browser) await browser.close();
+      } catch {
+        /* best-effort */
+      }
+      connected = false;
+      page = undefined;
+      browser = undefined;
+    },
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { ComputerUseDriverError, type Driver, createDriver } from "./index.js";
+
+describe("createDriver", () => {
+  test("dispatches on backend tag", () => {
+    const chromium = createDriver({ backend: "chromium" });
+    expect(chromium.backend).toBe("chromium");
+    const host = createDriver({ backend: "host" });
+    expect(host.backend).toBe("host");
+    const remote = createDriver({ backend: "remote" });
+    expect(remote.backend).toBe("remote");
+  });
+
+  test("unknown backend throws", () => {
+    expect(() => createDriver({ backend: "bogus" as unknown as "host" })).toThrow(
+      /unknown backend/,
+    );
+  });
+
+  test("host backend rejects connect (T8 — kickoff explicitly forbids)", async () => {
+    const d = createDriver({ backend: "host" });
+    await expect(d.connect()).rejects.toThrow(ComputerUseDriverError);
+  });
+
+  test("remote backend rejects connect (v0 stub)", async () => {
+    const d = createDriver({ backend: "remote" });
+    await expect(d.connect()).rejects.toThrow(/not implemented in v0/);
+  });
+
+  test("_injected returns the injected driver verbatim (test seam)", async () => {
+    const recorded: string[] = [];
+    const stub: Driver = {
+      backend: "chromium",
+      async connect() {
+        recorded.push("connect");
+      },
+      async goto() {
+        recorded.push("goto");
+      },
+      async screenshot() {
+        recorded.push("screenshot");
+        return new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG header
+      },
+      async click() {
+        recorded.push("click");
+      },
+      async type() {
+        recorded.push("type");
+      },
+      async key() {
+        recorded.push("key");
+      },
+      async scroll() {
+        recorded.push("scroll");
+      },
+      async getViewport() {
+        return { width: 800, height: 600, devicePixelRatio: 1 };
+      },
+      async disconnect() {
+        recorded.push("disconnect");
+      },
+    };
+    const d = createDriver({ backend: "chromium", _injected: stub });
+    await d.connect();
+    await d.goto("about:blank");
+    await d.screenshot();
+    await d.click(100, 200);
+    await d.type("hi");
+    await d.key("Enter");
+    await d.scroll(0, 200);
+    await d.disconnect();
+    expect(recorded).toEqual([
+      "connect",
+      "goto",
+      "screenshot",
+      "click",
+      "type",
+      "key",
+      "scroll",
+      "disconnect",
+    ]);
+  });
+
+  test("chromium driver throws clean diagnostic when used before connect()", async () => {
+    const d = createDriver({ backend: "chromium" });
+    await expect(d.screenshot()).rejects.toThrow(/not connected/);
+    await expect(d.click(0, 0)).rejects.toThrow(/not connected/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,289 @@
+/**
+ * Catalog R18 `computer-use-driver` — Section 25 BROW.
+ *
+ * Cross-platform driver for mouse/keyboard/screenshot operations. The
+ * `Driver` interface exposes:
+ *   - `screenshot()` → PNG `Uint8Array`
+ *   - `click(x, y, button?)`
+ *   - `type(text)`
+ *   - `key(combo)`            // "Enter", "Tab", "Control+a"
+ *   - `scroll(dx, dy)`
+ *   - `getViewport()` → { width, height, devicePixelRatio }
+ *   - `goto(url)`              // browser-only; `host` backend rejects
+ *
+ * v0 ships ONE concrete backend — `chromium` — driven by Playwright's
+ * bundled headless chromium. The kickoff names this `docker-chromium`
+ * because it's intended to run inside a Section-18 sandbox; in v0 we
+ * lean on Playwright's own chromium-sandboxing (the chromium binary
+ * runs as a sandboxed renderer process) and defer the explicit Docker
+ * wrapping to a follow-up.
+ *
+ * The `host` backend (drives the developer's actual desktop) and
+ * `remote` backend (CDP-style remote control) are interface stubs that
+ * throw at `connect()` — see the kickoff explicitly forbidding the host
+ * backend in the smoke ("never use `host` backend for the smoke since
+ * it would drive the dev's actual desktop").
+ */
+import { CrewhausError } from "@crewhaus/errors";
+
+export class ComputerUseDriverError extends CrewhausError {
+  override readonly name = "ComputerUseDriverError";
+  constructor(message: string, cause?: unknown) {
+    super("tool", message, cause);
+  }
+}
+
+export type DriverBackend = "host" | "chromium" | "remote";
+export type MouseButton = "left" | "right" | "middle";
+
+export type Viewport = {
+  readonly width: number;
+  readonly height: number;
+  readonly devicePixelRatio: number;
+};
+
+export interface Driver {
+  readonly backend: DriverBackend;
+  /** Open / connect / launch chromium. Idempotent. */
+  connect(): Promise<void>;
+  /** Navigate the chromium tab. Throws on `host` backend. */
+  goto(url: string): Promise<void>;
+  /** Capture a PNG screenshot. */
+  screenshot(): Promise<Uint8Array>;
+  click(x: number, y: number, button?: MouseButton): Promise<void>;
+  type(text: string): Promise<void>;
+  key(combo: string): Promise<void>;
+  scroll(dx: number, dy: number): Promise<void>;
+  getViewport(): Promise<Viewport>;
+  /** Best-effort DOM snapshot. Used by tests + the post-action assertions. */
+  domText?(): Promise<string>;
+  disconnect(): Promise<void>;
+}
+
+export type CreateDriverOptions = {
+  readonly backend: DriverBackend;
+  /** Playwright launch overrides (e.g. headless: false). chromium-only. */
+  readonly playwrightOptions?: Record<string, unknown>;
+  /** Initial viewport — chromium-only. Default 1280x720@1. */
+  readonly viewport?: { width: number; height: number };
+  /** Test injection: a pre-built Driver instance the factory returns verbatim. */
+  readonly _injected?: Driver;
+};
+
+export function createDriver(opts: CreateDriverOptions): Driver {
+  if (opts._injected !== undefined) return opts._injected;
+  if (opts.backend === "chromium") return createChromiumDriver(opts);
+  if (opts.backend === "host") {
+    // Section 30 — host backend stays gated. Callers that have wired
+    // a real executor use `createHostDriver` directly.
+    return createHostDriverStub();
+  }
+  if (opts.backend === "remote") {
+    // Same pattern: callers with a puppeteer-core import use
+    // `createRemoteDriver` directly.
+    return createRemoteDriverStub();
+  }
+  throw new ComputerUseDriverError(`unknown backend: ${opts.backend}`);
+}
+
+// Section 30 — direct exports for callers that wire backends with an
+// executor or puppeteer-core import.
+export { createHostDriver, type HostBackendOptions, type HostExecutor } from "./backends/host";
+export {
+  createRemoteDriver,
+  type PuppeteerCoreLike,
+  type RemoteBackendOptions,
+} from "./backends/remote";
+
+// ---------------------------------------------------------------------------
+// Playwright-backed chromium driver.
+// ---------------------------------------------------------------------------
+
+function createChromiumDriver(opts: CreateDriverOptions): Driver {
+  let browser: unknown;
+  let context: unknown;
+  let page: unknown;
+  let connected = false;
+
+  async function loadPlaywright(): Promise<{
+    chromium: { launch: (...args: unknown[]) => unknown };
+  }> {
+    try {
+      // Lazy import so non-browser users don't need Playwright in their tree.
+      // The import is dynamic via a string indirection so `tsc` doesn't fail
+      // when playwright (an optional peer dep) isn't installed in CI.
+      const playwrightModule = "playwright";
+      const mod = await import(playwrightModule);
+      return mod as unknown as { chromium: { launch: (...args: unknown[]) => unknown } };
+    } catch (err) {
+      throw new ComputerUseDriverError(
+        "Playwright not installed. Run `bun add -D playwright` and `bunx playwright install chromium` to use the chromium backend.",
+        err,
+      );
+    }
+  }
+
+  return {
+    backend: "chromium",
+    async connect() {
+      if (connected) return;
+      const { chromium } = await loadPlaywright();
+      // Playwright defaults: chromium runs in its own sandbox (its own
+      // sandboxed renderer process). Headless by default.
+      const launchOpts: Record<string, unknown> = {
+        headless: true,
+        ...(opts.playwrightOptions ?? {}),
+      };
+      browser = await (chromium.launch as (o: unknown) => Promise<unknown>)(launchOpts);
+      const ctxOpts: Record<string, unknown> = {
+        viewport: opts.viewport ?? { width: 1280, height: 720 },
+      };
+      context = await (browser as { newContext: (o: unknown) => Promise<unknown> }).newContext(
+        ctxOpts,
+      );
+      page = await (context as { newPage: () => Promise<unknown> }).newPage();
+      connected = true;
+    },
+
+    async goto(url) {
+      if (!connected)
+        throw new ComputerUseDriverError("driver not connected — call connect() first");
+      await (page as { goto: (u: string, o?: unknown) => Promise<unknown> }).goto(url, {
+        waitUntil: "domcontentloaded",
+      });
+    },
+
+    async screenshot() {
+      if (!connected) throw new ComputerUseDriverError("driver not connected");
+      const buf = (await (page as { screenshot: (o?: unknown) => Promise<unknown> }).screenshot({
+        type: "png",
+      })) as Uint8Array;
+      return buf;
+    },
+
+    async click(x, y, button = "left") {
+      if (!connected) throw new ComputerUseDriverError("driver not connected");
+      await (
+        page as { mouse: { click: (x: number, y: number, o?: unknown) => Promise<void> } }
+      ).mouse.click(x, y, { button });
+    },
+
+    async type(text) {
+      if (!connected) throw new ComputerUseDriverError("driver not connected");
+      await (page as { keyboard: { type: (t: string) => Promise<void> } }).keyboard.type(text);
+    },
+
+    async key(combo) {
+      if (!connected) throw new ComputerUseDriverError("driver not connected");
+      await (page as { keyboard: { press: (k: string) => Promise<void> } }).keyboard.press(combo);
+    },
+
+    async scroll(dx, dy) {
+      if (!connected) throw new ComputerUseDriverError("driver not connected");
+      await (page as { mouse: { wheel: (dx: number, dy: number) => Promise<void> } }).mouse.wheel(
+        dx,
+        dy,
+      );
+    },
+
+    async getViewport() {
+      if (!connected) throw new ComputerUseDriverError("driver not connected");
+      const vp = (
+        page as { viewportSize: () => { width: number; height: number } | null }
+      ).viewportSize();
+      const w = vp?.width ?? opts.viewport?.width ?? 1280;
+      const h = vp?.height ?? opts.viewport?.height ?? 720;
+      return { width: w, height: h, devicePixelRatio: 1 };
+    },
+
+    async domText() {
+      if (!connected) throw new ComputerUseDriverError("driver not connected");
+      return (page as { textContent: (sel: string) => Promise<string | null> })
+        .textContent("body")
+        .then((t) => t ?? "");
+    },
+
+    async disconnect() {
+      if (!connected) return;
+      try {
+        await (browser as { close: () => Promise<void> }).close();
+      } catch {
+        // best-effort
+      }
+      connected = false;
+      browser = undefined;
+      context = undefined;
+      page = undefined;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Stubs for host + remote backends.
+// ---------------------------------------------------------------------------
+
+function createHostDriverStub(): Driver {
+  return {
+    backend: "host",
+    async connect() {
+      throw new ComputerUseDriverError(
+        "host backend is not implemented in v0. The kickoff explicitly forbids it for smokes (would drive the dev's actual desktop). Native macOS / Linux / Windows backends land in a follow-up gated on `CREWHAUS_BROW_HOST_SMOKE=1`.",
+      );
+    },
+    async goto() {
+      throw new ComputerUseDriverError("host backend not implemented");
+    },
+    async screenshot() {
+      throw new ComputerUseDriverError("host backend not implemented");
+    },
+    async click() {
+      throw new ComputerUseDriverError("host backend not implemented");
+    },
+    async type() {
+      throw new ComputerUseDriverError("host backend not implemented");
+    },
+    async key() {
+      throw new ComputerUseDriverError("host backend not implemented");
+    },
+    async scroll() {
+      throw new ComputerUseDriverError("host backend not implemented");
+    },
+    async getViewport() {
+      throw new ComputerUseDriverError("host backend not implemented");
+    },
+    async disconnect() {},
+  };
+}
+
+function createRemoteDriverStub(): Driver {
+  return {
+    backend: "remote",
+    async connect() {
+      throw new ComputerUseDriverError(
+        "remote backend (CDP / Browserless) is not implemented in v0",
+      );
+    },
+    async goto() {
+      throw new ComputerUseDriverError("remote backend not implemented");
+    },
+    async screenshot() {
+      throw new ComputerUseDriverError("remote backend not implemented");
+    },
+    async click() {
+      throw new ComputerUseDriverError("remote backend not implemented");
+    },
+    async type() {
+      throw new ComputerUseDriverError("remote backend not implemented");
+    },
+    async key() {
+      throw new ComputerUseDriverError("remote backend not implemented");
+    },
+    async scroll() {
+      throw new ComputerUseDriverError("remote backend not implemented");
+    },
+    async getViewport() {
+      throw new ComputerUseDriverError("remote backend not implemented");
+    },
+    async disconnect() {},
+  };
+}