@wenrwa/marketplace-cli 0.4.4 → 0.4.6

package/dist/bridge/activityParser.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * pucc-int-03 (ADR-0032) — Claude Code PTY activity parser (the PRODUCER).
+ *
+ * A Claude Code agent is a real PTY session the platform never drives
+ * (ADR-0028). To give it the same file-targeted drones/holograms a credits
+ * agent gets, the bridge OBSERVES its PTY output (read-only) and extracts the
+ * tool-use it renders — Edit/Write/Read/Bash targets + a short "thinking"
+ * summary — so the arena can swarm the files it touches.
+ *
+ * This module is PURE and defensive by contract:
+ *   - Input is raw PTY output: ANSI escapes, \r cursor redraws, and tool lines
+ *     split arbitrarily across chunks. It buffers partial lines across `push`.
+ *   - A parse MISS yields NOTHING (empty array). It NEVER throws — every code
+ *     path that could fail is caught and degraded to "no signal", because a
+ *     parser bug must never break the terminal it is only watching.
+ *   - The recognized markers are a SMALL, VERSIONED set (see TOOL_VERBS): if
+ *     Claude Code's output format drifts, this table is the one thing to bump.
+ *
+ * Recognized shape (best-effort): Claude Code renders a tool call as a bulleted
+ * line — `● Edit(src/foo.ts)`, `⏺ Read(package.json)`, `● Bash(npm test)`,
+ * `⏺ Update(src/x.ts)` — a bullet glyph, the Tool name, and a parenthesized
+ * arg. For file tools the arg's first token is the (repo-relative) path; for
+ * Bash it is a command (no path is extracted — the consumer degrades an empty
+ * `filePaths` to an ambient pulse). Every recognized tool also yields a
+ * human "thinking" phrase ("Editing foo.ts", "Running npm test").
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityParser = void 0;
+/**
+ * The VERSIONED marker table. Tool → gerund used in the "thinking" phrase.
+ * FILE_TOOLS is the subset whose arg is a path we extract into `filePaths`.
+ * Bash is recognized (for a thinking cue) but yields no path.
+ */
+const TOOL_VERBS = {
+    Read: 'Reading',
+    Edit: 'Editing',
+    Write: 'Writing',
+    Update: 'Updating',
+    Create: 'Creating',
+    MultiEdit: 'Editing',
+    NotebookEdit: 'Editing',
+    Bash: 'Running',
+};
+const FILE_TOOLS = new Set(['Read', 'Edit', 'Write', 'Update', 'Create', 'MultiEdit', 'NotebookEdit']);
+/** Bullet glyphs Claude Code (and similar TUIs) prefix a tool line with. */
+const BULLET = '[\\u25cf\\u23fa\\u23f5\\u25b6\\u25b7\\u2022*>]'; // ● ⏺ ⏵ ▶ ▷ • * >
+/**
+ * `<bullet> <Tool>(<arg>` — arg captured up to the first ')' or end-of-line
+ * (Claude Code truncates long args with `…` and NO closing paren, so a missing
+ * ')' must still parse). Operates on a single already-newline-split, ANSI-free
+ * line, so `.` never crosses lines.
+ */
+const TOOL_LINE = new RegExp('^' + BULLET + '\\s+([A-Za-z][A-Za-z0-9_]*)\\(([^)]*)\\)?');
+/**
+ * ANSI/VT control-sequence matchers, built from \\u001b (ESC) / \\u0007 (BEL)
+ * escapes so this source carries NO literal control bytes (which an editor can
+ * silently corrupt). Stateless with /g; String.replace resets lastIndex.
+ */
+const _ESC = "\\u001b";
+const _BEL = "\\u0007";
+// OSC: ESC ] ... (BEL | ESC \\)
+const OSC = new RegExp(_ESC + '\\][\\s\\S]*?(?:' + _BEL + '|' + _ESC + '\\\\)', 'g');
+// CSI + other ESC-introduced sequences (SGR colors, cursor moves, ...): ESC,
+// optional intro chars, optional numeric params, a final byte in @-~.
+const CSI = new RegExp(_ESC + '[[\\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[@-~]', 'g');
+// Any remaining lone ESC + C0 control chars EXCEPT tab(09) newline(0a) cr(0d).
+const STRAY = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+/** Strip ANSI/VT control sequences to leave printable text. */
+function stripAnsi(input) {
+    return input.replace(OSC, "").replace(CSI, "").replace(STRAY, "");
+}
+/**
+ * Reduce a raw line to its final RENDERED content. A TUI redraws in place with
+ * carriage returns: "old\rnew" displays "new". Keep only the text after the
+ * last \r so repeated redraws collapse to one signal.
+ */
+function finalRendered(line) {
+    const cr = line.lastIndexOf('\r');
+    return cr >= 0 ? line.slice(cr + 1) : line;
+}
+/** Extract a plausible repo-relative path from a file-tool arg, or null. */
+function extractPath(arg) {
+    // Take the first comma-separated segment (Claude Code appends `, offset:…`).
+    let s = arg.split(',')[0].trim();
+    // Drop an optional `file_path:` / `path:` label if present.
+    const labelled = s.match(/^(?:file_path|path|notebook_path)\s*:\s*(.+)$/i);
+    if (labelled)
+        s = labelled[1].trim();
+    // Strip a single pair of surrounding quotes.
+    s = s.replace(/^["'`](.*)["'`]$/, '$1').trim();
+    // Strip a trailing truncation ellipsis Claude Code adds to long args.
+    s = s.replace(/(?:…|\.\.\.)+$/, '').trim();
+    // Strip a leading "./".
+    s = s.replace(/^\.\//, '');
+    if (!s || s.length > 512)
+        return null;
+    // Reject obvious non-paths (nothing path-like left after cleanup).
+    if (!/[A-Za-z0-9._/\\-]/.test(s))
+        return null;
+    return s;
+}
+function basename(p) {
+    const parts = p.split(/[\\/]/);
+    return parts[parts.length - 1] || p;
+}
+/** Truncate a thinking phrase to a bounded, single-line length. */
+function boundThinking(s) {
+    const oneLine = s.replace(/\s+/g, ' ').trim();
+    return oneLine.length > 80 ? oneLine.slice(0, 79) + '…' : oneLine;
+}
+/** Best-effort short summary of a Bash arg for the thinking cue. */
+function extractCommandSummary(arg) {
+    const s = arg
+        .replace(/(?:…|\.\.\.)+$/, '')
+        .trim()
+        .replace(/^["'`](.*)["'`]$/, '$1')
+        .trim();
+    return s || null;
+}
+const DEFAULT_MAX_LINE = 16384;
+class ActivityParser {
+    buf = '';
+    maxLineLength;
+    /** Suppress consecutive identical signals (TUI re-renders the same line). */
+    lastKey = '';
+    constructor(opts = {}) {
+        this.maxLineLength = opts.maxLineLength ?? DEFAULT_MAX_LINE;
+    }
+    /**
+     * Feed a chunk of PTY output. Returns every NEW tool-use signal completed by
+     * this chunk (usually 0 or 1). Never throws: any internal failure degrades
+     * to an empty result so the caller's PTY forwarding is never disturbed.
+     */
+    push(chunk) {
+        try {
+            return this.pushUnsafe(chunk);
+        }
+        catch {
+            // A parser bug must never break the terminal it only observes. Reset the
+            // buffer so one bad state can't wedge all future parsing.
+            this.buf = '';
+            return [];
+        }
+    }
+    pushUnsafe(chunk) {
+        if (typeof chunk !== 'string' || chunk.length === 0)
+            return [];
+        this.buf += chunk;
+        // Normalize CRLF line endings to LF so a terminal's trailing `\r\n` is a
+        // line break, not mistaken for a mid-line redraw. A lone trailing `\r`
+        // (chunk boundary) stays buffered — the next chunk's `\n` completes it.
+        this.buf = this.buf.replace(/\r\n/g, '\n');
+        // Bounded buffer: if a single line runs away without a newline (binary
+        // spew), keep only the tail so a future newline can still complete a line.
+        if (this.buf.length > this.maxLineLength && !this.buf.includes('\n')) {
+            this.buf = this.buf.slice(-this.maxLineLength);
+        }
+        const nl = this.buf.lastIndexOf('\n');
+        if (nl < 0)
+            return []; // no complete line yet — keep buffering
+        const complete = this.buf.slice(0, nl);
+        this.buf = this.buf.slice(nl + 1);
+        const out = [];
+        for (const rawLine of complete.split('\n')) {
+            const signal = this.parseLine(rawLine);
+            if (!signal)
+                continue;
+            const key = JSON.stringify(signal);
+            if (key === this.lastKey)
+                continue; // dedup rapid repeats
+            this.lastKey = key;
+            out.push(signal);
+        }
+        return out;
+    }
+    parseLine(rawLine) {
+        const line = stripAnsi(finalRendered(rawLine)).trim();
+        if (!line)
+            return null;
+        const m = TOOL_LINE.exec(line);
+        if (!m)
+            return null;
+        const tool = m[1];
+        const verb = TOOL_VERBS[tool];
+        if (!verb)
+            return null; // unknown tool → no signal (fewer false events)
+        const arg = m[2] ?? '';
+        if (FILE_TOOLS.has(tool)) {
+            const path = extractPath(arg);
+            if (path) {
+                return { filePaths: [path], thinking: boundThinking(verb + ' ' + basename(path)) };
+            }
+            // Recognized file tool but no usable path → thinking-only (ambient pulse).
+            return { filePaths: [], thinking: boundThinking(verb) };
+        }
+        // Bash (and any future non-file tool): a thinking cue, no path.
+        const cmd = extractCommandSummary(arg);
+        return { filePaths: [], thinking: boundThinking(cmd ? verb + ' ' + cmd : verb) };
+    }
+}
+exports.ActivityParser = ActivityParser;

package/dist/bridge/apiClient.d.ts

@@ -0,0 +1,56 @@
+/**
+ * lws-03 — bridge REST client. The daemon talks to the backend AS ITSELF
+ * (Authorization: Bearer <Connect Token>), distinct from utils/client.ts
+ * (the interactive CLI's X-Wallet-Pubkey login flow). Used for device
+ * pairing ("Connect this machine") and local-workspace creation/deletion.
+ * fetchImpl is injectable so callers/tests never hit the network.
+ */
+export type FetchImpl = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<any>;
+}>;
+export interface BridgeApiOpts {
+    apiUrl: string;
+    connectToken: string;
+    fetchImpl?: FetchImpl;
+}
+export declare class BridgeApiError extends Error {
+    code: string;
+    status: number;
+    constructor(message: string, code: string, status: number);
+}
+export interface DeviceRecord {
+    id: string;
+    name: string;
+    createdAt?: string;
+    revokedAt?: string | null;
+}
+export declare function registerDevice(opts: BridgeApiOpts, name: string): Promise<{
+    success: boolean;
+    device: DeviceRecord;
+}>;
+export declare function listDevices(opts: BridgeApiOpts): Promise<{
+    success: boolean;
+    devices: DeviceRecord[];
+}>;
+export declare function revokeDevice(opts: BridgeApiOpts, deviceId: string): Promise<{
+    success: boolean;
+}>;
+export interface WorkspaceRecord {
+    id: string;
+    name: string;
+}
+export declare function createLocalWorkspace(opts: BridgeApiOpts, params: {
+    name: string;
+}): Promise<{
+    success: boolean;
+    workspace: WorkspaceRecord;
+}>;
+export declare function deleteWorkspace(opts: BridgeApiOpts, workspaceId: string): Promise<{
+    success: boolean;
+}>;

package/dist/bridge/apiClient.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BridgeApiError = void 0;
+exports.registerDevice = registerDevice;
+exports.listDevices = listDevices;
+exports.revokeDevice = revokeDevice;
+exports.createLocalWorkspace = createLocalWorkspace;
+exports.deleteWorkspace = deleteWorkspace;
+class BridgeApiError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'BridgeApiError';
+    }
+}
+exports.BridgeApiError = BridgeApiError;
+async function bridgeRequest(opts, method, path, body) {
+    const f = opts.fetchImpl ?? fetch;
+    const res = await f(`${opts.apiUrl}${path}`, {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${opts.connectToken}`,
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const json = await res.json();
+    if (!res.ok || json?.success === false) {
+        throw new BridgeApiError(json?.error?.message || `HTTP ${res.status}`, json?.error?.code || 'UNKNOWN', res.status);
+    }
+    return json;
+}
+function registerDevice(opts, name) {
+    return bridgeRequest(opts, 'POST', '/me/devices', { name });
+}
+function listDevices(opts) {
+    return bridgeRequest(opts, 'GET', '/me/devices');
+}
+function revokeDevice(opts, deviceId) {
+    return bridgeRequest(opts, 'DELETE', `/me/devices/${deviceId}`);
+}
+function createLocalWorkspace(opts, params) {
+    return bridgeRequest(opts, 'POST', '/workspaces', { name: params.name, kind: 'local' });
+}
+function deleteWorkspace(opts, workspaceId) {
+    return bridgeRequest(opts, 'DELETE', `/workspaces/${workspaceId}`);
+}

package/dist/bridge/browserDriver.d.ts

@@ -0,0 +1,98 @@
+/**
+ * cbs-02 — bridge CDP browser driver.
+ *
+ * (docs/prd/cloud-browser-session.md, issues/cbs-02-bridge-cdp-driver.md)
+ * The deep module inside the in-container bridge that owns one headless
+ * Chromium tab: spawn (child_process, NOT node-pty/SessionManager — this
+ * must never touch the PTY session manager or spawn a shell), a minimal
+ * hand-rolled CDP client (cdpClient.ts) driving `Page.startScreencast` for
+ * output and `Input.dispatch*`/`insertText` for input, screencast frames
+ * piped through the cbs-01 keep-newest pacer (framePacer.ts), and
+ * navigation/lifecycle state surfaced as plain callbacks. All CDP mechanics
+ * (target attach, session ids, event wiring) are hidden behind this
+ * interface — relayClient.ts (or any future caller) only sees start/
+ * navigate/input/back/forward/reload/onFrame/onState/ackFrame/stop.
+ */
+import { ChromiumLaunchHandle } from './chromiumLauncher';
+import { CdpTransportLike } from './cdpClient';
+import { BrowserInputEvent, BrowserSessionState } from './browserFrames';
+/** container -> pane screencast frame, minus the wire envelope (`t`,
+ *  `sessionId`) — the driver doesn't know the relay session id; the caller
+ *  (relayClient) stamps those on when forwarding. */
+export interface BrowserDriverFramePayload {
+    seq: number;
+    data: string;
+    w: number;
+    h: number;
+}
+/** container -> pane lifecycle/navigation state, minus the wire envelope. */
+export interface BrowserDriverStatePayload {
+    state: BrowserSessionState;
+    url?: string;
+    title?: string;
+    reason?: string;
+}
+export interface BrowserDriver {
+    /** Launches Chromium (if not already running), attaches to a page
+     *  target, starts the screencast, and navigates to `url`. */
+    start(url: string): Promise<void>;
+    /** Navigates the already-open tab to `url` (also what a `browser-open`
+     *  on an already-open session should call — see relayClient wiring). */
+    navigate(url: string): Promise<void>;
+    /** Dispatches one input event. Never dropped/paced (unlike frames). */
+    input(event: BrowserInputEvent): void;
+    back(): Promise<void>;
+    forward(): Promise<void>;
+    reload(): Promise<void>;
+    /** Registers the (single) frame consumer. Frames are keep-newest paced —
+     *  see ackFrame(). */
+    onFrame(cb: (frame: BrowserDriverFramePayload) => void): void;
+    /** Registers the (single) lifecycle/navigation state consumer. */
+    onState(cb: (state: BrowserDriverStatePayload) => void): void;
+    /** Consumer contract for the cbs-01 pacer (framePacer.ts): call once a
+     *  delivered frame has been handed off downstream. The wire protocol
+     *  (browserFrames.ts, v1) has no pane-side ack frame yet, so relayClient's
+     *  interim policy is to call this right after forwarding — true end-to-end
+     *  backpressure to the pane is a later slice (see PRD module 5). */
+    ackFrame(): void;
+    /** Kills the Chromium process and tears down the CDP transport, emitting a
+     *  terminal 'closed' state. Safe to call more than once and safe to call
+     *  before start() resolves. */
+    stop(): void;
+    /** cbs-06: same physical teardown as stop() (kills Chromium, tears down
+     *  CDP — no orphaned process either way), but emits a terminal 'asleep'
+     *  state instead of 'closed' — intentional and resumable (a later
+     *  browser-open on this sessionId gets a FRESH driver instance per the
+     *  relayClient "replace, not navigate" policy; this driver instance is
+     *  done either way). `reason` rides straight onto the emitted
+     *  browser-state (default 'sleep'; relayClient passes 'idle-timeout' for
+     *  the 15-minute auto-close path — see browserFrames.ts's BrowserStateFrame
+     *  doc comment for the reason-string convention). Safe to call more than
+     *  once, safe to call before start() resolves, and safe to call after
+     *  stop() (or vice versa) — only the FIRST of stop()/sleep() wins; the
+     *  second is a no-op (exactly one terminal browser-state frame per driver
+     *  lifetime). */
+    sleep(reason?: string): void;
+}
+export interface BrowserDriverOpts {
+    chromiumPath?: string;
+    userDataDir?: string;
+    /** Window size AND `Page.startScreencast` maxWidth/maxHeight. Default 1280x800. */
+    width?: number;
+    height?: number;
+    /** JPEG quality for the screencast. Default 60 (PRD: "JPEG quality tuned
+     *  for text legibility"). */
+    quality?: number;
+    /** Injectable for tests: defaults to chromiumLauncher.launchChromium. */
+    launchChromiumFn?: (opts: {
+        chromiumPath?: string;
+        userDataDir?: string;
+        width?: number;
+        height?: number;
+    }) => ChromiumLaunchHandle;
+    /** Injectable for tests: defaults to a `ws`-backed transport connected to
+     *  the Chromium DevTools websocket URL. Tests inject an in-process
+     *  MockCdpEndpoint transport here to avoid a real socket/process. */
+    wsFactory?: (url: string) => CdpTransportLike;
+}
+export declare function createBrowserDriver(opts?: BrowserDriverOpts): BrowserDriver;

package/dist/bridge/browserDriver.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserDriver = createBrowserDriver;
+/**
+ * cbs-02 — bridge CDP browser driver.
+ *
+ * (docs/prd/cloud-browser-session.md, issues/cbs-02-bridge-cdp-driver.md)
+ * The deep module inside the in-container bridge that owns one headless
+ * Chromium tab: spawn (child_process, NOT node-pty/SessionManager — this
+ * must never touch the PTY session manager or spawn a shell), a minimal
+ * hand-rolled CDP client (cdpClient.ts) driving `Page.startScreencast` for
+ * output and `Input.dispatch*`/`insertText` for input, screencast frames
+ * piped through the cbs-01 keep-newest pacer (framePacer.ts), and
+ * navigation/lifecycle state surfaced as plain callbacks. All CDP mechanics
+ * (target attach, session ids, event wiring) are hidden behind this
+ * interface — relayClient.ts (or any future caller) only sees start/
+ * navigate/input/back/forward/reload/onFrame/onState/ackFrame/stop.
+ */
+const chromiumLauncher_1 = require("./chromiumLauncher");
+const cdpClient_1 = require("./cdpClient");
+const framePacer_1 = require("./framePacer");
+/** CDP's Input.dispatch*Event `modifiers` bitmask: Alt=1, Ctrl=2, Meta=4,
+ *  Shift=8 (per the CDP spec) — abstracted away from callers by
+ *  browserFrames.ts's plain BrowserInputModifiers booleans. */
+function modifiersBitmask(m) {
+    let bits = 0;
+    if (m?.alt)
+        bits |= 1;
+    if (m?.ctrl)
+        bits |= 2;
+    if (m?.meta)
+        bits |= 4;
+    if (m?.shift)
+        bits |= 8;
+    return bits;
+}
+/** Default real transport: wraps a `ws` WebSocket connected to the
+ *  Chromium DevTools endpoint. Never exercised by tests (they inject
+ *  wsFactory) — the real-Chromium round is a manual smoke test at
+ *  image-build time per the PRD's Testing Decisions. */
+function createDefaultTransport(url) {
+    // Lazy require: keeps `ws` off the load path for every CLI command that
+    // never touches the browser driver (mirrors realPty.ts's lazy node-pty require).
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { WebSocket } = require('ws');
+    const socket = new WebSocket(url);
+    return {
+        send: (data) => {
+            if (socket.readyState === WebSocket.OPEN)
+                socket.send(data);
+        },
+        close: () => socket.close(),
+        on: (event, cb) => {
+            if (event === 'message') {
+                socket.on('message', (raw) => cb(String(raw)));
+            }
+            else if (event === 'close') {
+                socket.on('close', (code, reason) => cb({ code, reason: reason ? String(reason) : undefined }));
+            }
+            else {
+                socket.on(event, cb);
+            }
+        },
+    };
+}
+function createBrowserDriver(opts = {}) {
+    const chromiumPath = opts.chromiumPath;
+    const userDataDir = opts.userDataDir;
+    const width = opts.width ?? 1280;
+    const height = opts.height ?? 800;
+    const quality = opts.quality ?? 60;
+    const launchChromiumFn = opts.launchChromiumFn ?? chromiumLauncher_1.launchChromium;
+    const wsFactory = opts.wsFactory ?? createDefaultTransport;
+    let cdp = null;
+    let childProc = null;
+    let pageTargetId = null;
+    let targetSessionId = null;
+    let seq = 0;
+    let closed = false;
+    let stopped = false;
+    let frameCb = null;
+    let stateCb = null;
+    const pacer = (0, framePacer_1.createFramePacer)({
+        onDeliver: (f) => frameCb?.(f),
+    });
+    const emitState = (s) => {
+        stateCb?.(s);
+    };
+    // cbs-06: `closed` guards the TERMINAL STATE EMISSION (fires at most once
+    // per driver lifetime, whichever of 'closed'/'asleep' gets there first —
+    // a crash-exit racing an explicit stop()/sleep() must never double-emit).
+    // `stopped` guards the PHYSICAL TEARDOWN (kill the process, close CDP) —
+    // separate from `closed` because a genuine Chromium exit event can arrive
+    // AFTER an explicit stop()/sleep() already tore things down; teardown()
+    // must not try to kill an already-dead process a second time.
+    const emitTerminal = (state, reason) => {
+        if (closed)
+            return;
+        closed = true;
+        pacer.close();
+        emitState({ state, reason });
+    };
+    const handleClosed = (reason) => {
+        emitTerminal('closed', reason);
+    };
+    const teardown = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        try {
+            cdp?.close();
+        }
+        catch {
+            /* best-effort teardown */
+        }
+        try {
+            childProc?.kill();
+        }
+        catch {
+            /* best-effort teardown */
+        }
+    };
+    async function start(url) {
+        emitState({ state: 'opening' });
+        const { proc, wsUrl } = launchChromiumFn({ chromiumPath, userDataDir, width, height });
+        childProc = proc;
+        proc.on('exit', (code, signal) => {
+            handleClosed(`chromium-exit code=${code ?? 'null'} signal=${signal ?? 'null'}`);
+        });
+        proc.on('error', (err) => {
+            handleClosed(`chromium-error ${err instanceof Error ? err.message : String(err)}`);
+        });
+        const browserWsUrl = await wsUrl;
+        const transport = wsFactory(browserWsUrl);
+        const client = (0, cdpClient_1.createCdpClient)(transport);
+        cdp = client;
+        client.onClose((info) => {
+            handleClosed(info?.reason ? `cdp-closed:${info.reason}` : 'cdp-closed');
+        });
+        client.onEvent('Target.targetInfoChanged', (params) => {
+            const info = params.targetInfo;
+            if (!info || !pageTargetId || info.targetId !== pageTargetId)
+                return;
+            emitState({ state: 'open', url: info.url, title: info.title });
+        });
+        client.onEvent('Page.screencastFrame', (params) => {
+            const frameAckId = params.sessionId;
+            // Ack CDP immediately regardless of pacer/consumer state — this is
+            // CDP's own flow-control contract (an un-acked screencast stalls),
+            // independent of the keep-newest policy governing onFrame delivery.
+            if (targetSessionId) {
+                void client.send('Page.screencastFrameAck', { sessionId: frameAckId }, targetSessionId).catch(() => { });
+            }
+            seq += 1;
+            const metadata = params.metadata ?? {};
+            pacer.push({
+                seq,
+                data: params.data,
+                w: metadata.deviceWidth ?? width,
+                h: metadata.deviceHeight ?? height,
+            });
+        });
+        const { targetInfos } = await client.send('Target.getTargets');
+        const existingPage = targetInfos.find((t) => t.type === 'page');
+        if (existingPage) {
+            pageTargetId = existingPage.targetId;
+        }
+        else {
+            const created = await client.send('Target.createTarget', { url: 'about:blank' });
+            pageTargetId = created.targetId;
+        }
+        const attached = await client.send('Target.attachToTarget', {
+            targetId: pageTargetId,
+            flatten: true,
+        });
+        targetSessionId = attached.sessionId;
+        await client.send('Page.enable', {}, targetSessionId);
+        await client.send('Page.startScreencast', { format: 'jpeg', quality, maxWidth: width, maxHeight: height }, targetSessionId);
+        await navigate(url);
+    }
+    async function navigate(url) {
+        if (!cdp || !targetSessionId)
+            return;
+        await cdp.send('Page.navigate', { url }, targetSessionId);
+    }
+    async function goHistory(delta) {
+        if (!cdp || !targetSessionId)
+            return;
+        const hist = await cdp.send('Page.getNavigationHistory', {}, targetSessionId);
+        const entry = hist.entries[hist.currentIndex + delta];
+        if (!entry)
+            return;
+        await cdp.send('Page.navigateToHistoryEntry', { entryId: entry.id }, targetSessionId);
+    }
+    async function reload() {
+        if (!cdp || !targetSessionId)
+            return;
+        await cdp.send('Page.reload', {}, targetSessionId);
+    }
+    function input(event) {
+        if (!cdp || !targetSessionId)
+            return;
+        const client = cdp;
+        const sid = targetSessionId;
+        switch (event.kind) {
+            case 'mouse': {
+                const type = event.type === 'down' ? 'mousePressed' : event.type === 'up' ? 'mouseReleased' : 'mouseMoved';
+                void client
+                    .send('Input.dispatchMouseEvent', {
+                    type,
+                    x: event.x,
+                    y: event.y,
+                    button: event.button ?? 'none',
+                    clickCount: event.type === 'move' ? 0 : 1,
+                    modifiers: modifiersBitmask(event.modifiers),
+                }, sid)
+                    .catch(() => { });
+                break;
+            }
+            case 'wheel':
+                void client
+                    .send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: event.x, y: event.y, deltaX: event.deltaX, deltaY: event.deltaY }, sid)
+                    .catch(() => { });
+                break;
+            case 'key':
+                void client
+                    .send('Input.dispatchKeyEvent', {
+                    type: event.type === 'down' ? 'keyDown' : 'keyUp',
+                    key: event.key,
+                    code: event.code,
+                    modifiers: modifiersBitmask(event.modifiers),
+                }, sid)
+                    .catch(() => { });
+                break;
+            case 'insertText':
+                void client.send('Input.insertText', { text: event.text }, sid).catch(() => { });
+                break;
+        }
+    }
+    function stop() {
+        teardown();
+        emitTerminal('closed', 'stopped');
+    }
+    function sleep(reason = 'sleep') {
+        teardown();
+        emitTerminal('asleep', reason);
+    }
+    return {
+        start,
+        navigate,
+        input,
+        back: () => goHistory(-1),
+        forward: () => goHistory(1),
+        reload,
+        onFrame: (cb) => {
+            frameCb = cb;
+        },
+        onState: (cb) => {
+            stateCb = cb;
+        },
+        ackFrame: () => pacer.ack(),
+        stop,
+        sleep,
+    };
+}