@handstage/core 0.0.7 → 1.0.0

package/README.md

@@ -1,3 +1,50 @@
 # @handstage/core
 
-Core browser automation engine for Handstage. Manages browser connections, Chrome DevTools Protocol (CDP) communication, page context, frame locators, and script injection for reliable browser automation.
+Core browser automation engine for Handstage. Manages CDP connections,
+target routing, page/frame lifecycle, and script injection for reliable
+browser automation.
+
+## Connection ownership
+
+Connection subpath factories own the CDP connection they construct:
+
+- `connectLocal(chrome)` from `@handstage/core/connect/local` — attaches to
+  a launched Chrome pipe and owns the connection.
+- `connectWS(ws)` from `@handstage/core/connect/ws` — wraps a browser
+  WebSocket and owns the connection. `close()` closes the WebSocket.
+- `connectTransport(transport)` from `@handstage/core/connect/transport` —
+  wraps and owns a raw `CDPTransport`.
+- `connectSession(session)` from `@handstage/core/connect/session` — wraps
+  and owns an `ExternalCDPSession`.
+- `connectConnection(existingConnection)` from
+  `@handstage/core/connect/connection` — explicit sharing entrypoint. Handstage does
+  NOT close the connection on `close()`; the caller does.
+
+Wrapping the same `transport` or `session` again throws
+`HandstageTransportAlreadyOwnedError`.
+
+`Context.close()` only ever calls `Target.disposeBrowserContext` (for
+dedicated contexts). It never tears down the underlying CDP connection —
+that responsibility lives with `Handstage` or, for shared connections, the caller.
+
+## Default-context attach
+
+Handstage creates instances containing the `defaultBrowserContext()` by default (which aligns with Puppeteer's `puppeteer.connect` and `puppeteer.launch`).
+Two Handstage clients on the same CDP websocket therefore share the default browser context natively without breaking. If you want isolation, call `handstage.createBrowserContext()`, which returns an isolated browser context. Targets owned by other browser contexts are resumed/detached at the target router rather than left paused.
+
+To intentionally attach to the shared default context (and accept that
+other actors may race with you on a shared tab), simply use the default browser context (i.e. `handstage.newPage()`).
+
+## Active page is gone
+
+Contexts no longer auto-create an initial page and there is no
+`context.activePage()` / `setActivePage()` / `awaitActivePage()`. Track
+`Page` references yourself (from `newPage()` / `pages()`) and call
+`page.bringToFront()` if you want to foreground a tab.
+
+## Per-instance logging
+
+Pass `logger:` to any connection factory and that logger receives every log
+from that Handstage's contexts / pages / network managers / target-router delegate.
+Two Handstage instances on a shared connection each receive router-level debug lines
+via broadcast.

package/dist/launch/bun.js

@@ -0,0 +1,44 @@
+/// <reference types="bun" />
+import Bun from "bun";
+import { performBrowserProcessCleanup, prepareChromeLaunchOptions, } from "./utils";
+export async function launchChromeBun(opts) {
+    const lbo = opts ?? {};
+    const { chromePath, finalFlags, userDataDir, createdTemp } = prepareChromeLaunchOptions(lbo);
+    const p = Bun.spawn([chromePath, ...finalFlags], {
+        stdio: ["ignore", "ignore", "ignore", "pipe", "pipe"],
+    });
+    const fd3 = p.stdio[3]; // Chrome's read pipe
+    const fd4 = p.stdio[4]; // Chrome's write pipe
+    if (typeof fd3 !== "number" || typeof fd4 !== "number") {
+        throw new Error("Failed to map Chrome pipes to Bun stdio streams");
+    }
+    const fd3Writer = Bun.file(fd3).writer();
+    const fd4Reader = Bun.file(fd4).stream();
+    const stdin = new WritableStream({
+        write(chunk) {
+            fd3Writer.write(chunk);
+            fd3Writer.flush();
+        },
+        close() {
+            fd3Writer.end();
+        },
+        abort() {
+            fd3Writer.end();
+        },
+    });
+    const close = async () => {
+        try {
+            fd3Writer.end();
+            await performBrowserProcessCleanup((signal) => p.kill(signal), p.exited, userDataDir, createdTemp, lbo);
+        }
+        catch { }
+    };
+    return {
+        stdout: fd4Reader,
+        stdin,
+        close,
+        pid: p.pid,
+        userDataDir,
+        createdTempProfile: createdTemp,
+    };
+}

package/dist/launch/node.js

@@ -0,0 +1,77 @@
+/// <reference types="node" />
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { performBrowserProcessCleanup, prepareChromeLaunchOptions, } from "./utils";
+export async function launchChromeNode(opts) {
+    const lbo = opts ?? {};
+    const { chromePath, finalFlags, userDataDir, createdTemp } = prepareChromeLaunchOptions(lbo);
+    const p = spawn(chromePath, finalFlags, {
+        stdio: ["ignore", "ignore", "ignore", "pipe", "pipe"],
+    });
+    const fd3 = p.stdio[3]; // Chrome's read pipe (our WritableStream)
+    const fd4 = p.stdio[4]; // Chrome's write pipe (our ReadableStream)
+    if (!(fd3 instanceof Writable) || !(fd4 instanceof Readable)) {
+        throw new Error("Failed to map Chrome pipes to stdio");
+    }
+    const stdout = new ReadableStream({
+        start(controller) {
+            fd4.on("data", (chunk) => {
+                controller.enqueue(new Uint8Array(chunk));
+            });
+            fd4.on("end", () => {
+                controller.close();
+            });
+            fd4.on("error", (err) => {
+                controller.error(err);
+            });
+        },
+        cancel() {
+            fd4.destroy();
+        },
+    });
+    const stdin = new WritableStream({
+        write(chunk, controller) {
+            return new Promise((resolve, reject) => {
+                fd3.write(chunk, (err) => {
+                    if (err) {
+                        controller.error(err);
+                        reject(err);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve) => {
+                fd3.end(resolve);
+            });
+        },
+        abort(err) {
+            fd3.destroy(err instanceof Error ? err : new Error(String(err)));
+        },
+    });
+    const close = async () => {
+        try {
+            fd3.destroy();
+            fd4.destroy();
+            const exited = new Promise((resolve) => {
+                if (p.exitCode !== null || p.signalCode !== null)
+                    resolve();
+                else
+                    p.once("exit", resolve);
+            });
+            await performBrowserProcessCleanup((signal) => p.kill(signal), exited, userDataDir, createdTemp, lbo);
+        }
+        catch { }
+    };
+    return {
+        stdout,
+        stdin,
+        close,
+        pid: p.pid,
+        userDataDir,
+        createdTempProfile: createdTemp,
+    };
+}

package/dist/launch/utils.js

@@ -0,0 +1,88 @@
+/// <reference types="node" />
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getChromePath } from "chrome-launcher";
+// `DEFAULT_FLAGS` is intentionally not re-exported from chrome-launcher's
+// package entry, so import it from the flags module directly.
+import { DEFAULT_FLAGS } from "chrome-launcher/dist/flags.js";
+export const CHROME_EXIT_TIMEOUT_MS = 5000;
+export async function waitForProcessExit(exited, timeoutMs) {
+    return Promise.race([
+        exited.then(() => true, () => true),
+        new Promise((resolve) => setTimeout(() => resolve(false), timeoutMs)),
+    ]);
+}
+export async function performBrowserProcessCleanup(kill, exited, userDataDir, createdTemp, opts) {
+    kill();
+    if (!(await waitForProcessExit(exited, CHROME_EXIT_TIMEOUT_MS))) {
+        kill("SIGKILL");
+        await waitForProcessExit(exited, CHROME_EXIT_TIMEOUT_MS);
+    }
+    cleanupUserDataDir(userDataDir, createdTemp, opts);
+}
+export function prepareChromeLaunchOptions(opts) {
+    const lbo = opts ?? {};
+    const chromePath = lbo.executablePath || getChromePath();
+    let userDataDir = lbo.userDataDir;
+    let createdTemp = false;
+    if (!userDataDir) {
+        const base = path.join(os.tmpdir(), "handstage-v3");
+        fs.mkdirSync(base, { recursive: true });
+        userDataDir = fs.mkdtempSync(path.join(base, "profile-"));
+        createdTemp = true;
+    }
+    let baseChromeFlags = [];
+    const ignore = lbo.ignoreDefaultArgs;
+    if (ignore === true) {
+        baseChromeFlags = [];
+    }
+    else if (Array.isArray(ignore)) {
+        baseChromeFlags = DEFAULT_FLAGS.filter((f) => !ignore.some((ex) => f.includes(ex)));
+    }
+    else {
+        baseChromeFlags = [...DEFAULT_FLAGS];
+    }
+    const chromeFlags = [
+        ...(lbo.headless !== false ? ["--headless=new"] : []),
+        ...baseChromeFlags,
+        "--remote-debugging-pipe",
+    ];
+    if (lbo.devtools)
+        chromeFlags.push("--auto-open-devtools-for-tabs");
+    if (lbo.locale)
+        chromeFlags.push(`--lang=${lbo.locale}`);
+    if (lbo.viewport?.width && lbo.viewport?.height) {
+        chromeFlags.push(`--window-size=${lbo.viewport.width},${lbo.viewport.height + 87}`);
+    }
+    if (typeof lbo.deviceScaleFactor === "number") {
+        chromeFlags.push(`--force-device-scale-factor=${Math.max(0.1, lbo.deviceScaleFactor)}`);
+    }
+    if (lbo.hasTouch)
+        chromeFlags.push("--touch-events=enabled");
+    if (lbo.ignoreHTTPSErrors)
+        chromeFlags.push("--ignore-certificate-errors");
+    if (lbo.proxy?.server)
+        chromeFlags.push(`--proxy-server=${lbo.proxy.server}`);
+    if (lbo.proxy?.bypass)
+        chromeFlags.push(`--proxy-bypass-list=${lbo.proxy.bypass}`);
+    if (userDataDir)
+        chromeFlags.push(`--user-data-dir=${userDataDir}`);
+    if (Array.isArray(lbo.args))
+        chromeFlags.push(...lbo.args);
+    const finalFlags = chromeFlags.filter((f) => typeof f === "string");
+    return {
+        chromePath,
+        finalFlags,
+        userDataDir,
+        createdTemp,
+    };
+}
+export function cleanupUserDataDir(userDataDir, createdTemp, opts) {
+    if (createdTemp && !opts?.preserveUserDataDir && userDataDir) {
+        try {
+            fs.rmSync(userDataDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+}

package/dist/v3/connect/connection.js

@@ -0,0 +1,20 @@
+import { LogLevel } from "../types/public/logs";
+import { connectOptionsToLocalBrowserLaunchOptions, createSharedHandstage, setupConnectContext, } from "./shared";
+/**
+ * Attach a Handstage instance to a pre-existing `CDPConnectionLike` that the caller
+ * manages. Handstage will not close the shared connection on `close()`.
+ */
+export async function connectConnection(conn, opts) {
+    const { sharedOpts, logSink, logger } = setupConnectContext(opts);
+    logger({
+        category: "init",
+        message: "Attaching to shared CDP connection",
+        level: LogLevel.Info,
+    });
+    return await createSharedHandstage({
+        conn,
+        lbo: connectOptionsToLocalBrowserLaunchOptions(opts),
+        sharedOpts,
+        logSink,
+    });
+}

package/dist/v3/connect/index.js

@@ -0,0 +1,5 @@
+export { connectConnection } from "./connection";
+export { connectLocal } from "./local";
+export { connectSession } from "./session";
+export { connectTransport } from "./transport";
+export { connectWS } from "./ws";

package/dist/v3/connect/local.js

@@ -0,0 +1,106 @@
+import { LogLevel } from "../types/public/logs";
+import { CDPConnection } from "../understudy/cdp";
+import { createOwnedHandstage, setupConnectContext } from "./shared";
+const textEncoder = new TextEncoder();
+function createUtf8DecoderStream() {
+    const decoder = new TextDecoder();
+    return new TransformStream({
+        transform(chunk, controller) {
+            controller.enqueue(decoder.decode(chunk, { stream: true }));
+        },
+        flush(controller) {
+            const trailing = decoder.decode();
+            if (trailing)
+                controller.enqueue(trailing);
+        },
+    });
+}
+async function* readNullDelimitedMessages(stream) {
+    const decodedStream = stream.pipeThrough(createUtf8DecoderStream());
+    const reader = decodedStream.getReader();
+    let pending = "";
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            pending += value;
+            let frameStart = 0;
+            while (true) {
+                const frameEnd = pending.indexOf("\0", frameStart);
+                if (frameEnd === -1)
+                    break;
+                yield pending.slice(frameStart, frameEnd);
+                frameStart = frameEnd + 1;
+            }
+            if (frameStart > 0) {
+                pending = pending.slice(frameStart);
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function encodeNullDelimitedMessage(message) {
+    const encoded = textEncoder.encode(message);
+    const framed = new Uint8Array(encoded.byteLength + 1);
+    framed.set(encoded);
+    return framed;
+}
+export async function connectLocal(chrome, opts) {
+    const { sharedOpts, logSink, logger } = setupConnectContext(opts);
+    logger({
+        category: "init",
+        message: "Connecting via LaunchedChrome (pipe)",
+        level: LogLevel.Info,
+    });
+    const writer = chrome.stdin.getWriter();
+    let isClosed = false;
+    const transport = {
+        send: (message) => {
+            if (isClosed)
+                return;
+            writer.write(encodeNullDelimitedMessage(message)).catch(() => { });
+        },
+        close: async () => {
+            if (isClosed)
+                return;
+            isClosed = true;
+            await writer.close().catch(() => { });
+            await chrome.close().catch(() => { });
+        },
+    };
+    void (async () => {
+        try {
+            for await (const message of readNullDelimitedMessages(chrome.stdout)) {
+                if (isClosed)
+                    break;
+                if (transport.onmessage)
+                    transport.onmessage(message);
+            }
+        }
+        catch (err) {
+            if (transport.onerror) {
+                transport.onerror(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        finally {
+            if (transport.onclose && !isClosed) {
+                transport.onclose("Pipe closed");
+            }
+            isClosed = true;
+        }
+    })();
+    const conn = new CDPConnection(transport);
+    const lbo = opts?.localBrowserLaunchOptions ?? {};
+    return await createOwnedHandstage({
+        conn,
+        lbo,
+        sharedOpts,
+        logSink,
+        onContextError: async () => {
+            await chrome.close().catch(() => { });
+        },
+    });
+}

package/dist/v3/connect/session.js

@@ -0,0 +1,18 @@
+import { LogLevel } from "../types/public/logs";
+import { ExternalConnectionAdapter, } from "../understudy/cdp";
+import { connectOptionsToLocalBrowserLaunchOptions, createOwnedHandstage, setupConnectContext, } from "./shared";
+export async function connectSession(session, opts) {
+    const { sharedOpts, logSink, logger } = setupConnectContext(opts);
+    logger({
+        category: "init",
+        message: "Connecting via custom connection",
+        level: LogLevel.Info,
+    });
+    const adapter = new ExternalConnectionAdapter(session);
+    return await createOwnedHandstage({
+        conn: adapter,
+        lbo: connectOptionsToLocalBrowserLaunchOptions(opts),
+        sharedOpts,
+        logSink,
+    });
+}

package/dist/v3/connect/shared.js

@@ -0,0 +1,77 @@
+import { createHandstageForConnection } from "../handstage";
+import { createFilteredLogger } from "../logger";
+import { Context } from "../understudy/context";
+export function setupConnectContext(opts) {
+    const sharedOpts = opts ?? {};
+    const logSink = createFilteredLogger(sharedOpts.logger, sharedOpts.verbose);
+    const logger = (line) => logSink(line);
+    return { sharedOpts, logSink, logger };
+}
+export function connectOptionsToLocalBrowserLaunchOptions(opts) {
+    return opts
+        ? {
+            viewport: opts.viewport,
+            deviceScaleFactor: opts.deviceScaleFactor,
+            downloadsPath: opts.downloadsPath,
+            acceptDownloads: opts.acceptDownloads,
+        }
+        : {};
+}
+export function onceAsync(fn) {
+    let called = false;
+    return async () => {
+        if (called)
+            return;
+        called = true;
+        await fn();
+    };
+}
+export async function createOwnedHandstage(params) {
+    let ctx;
+    try {
+        ctx = await Context.createFromConnection(params.conn, {
+            localBrowserLaunchOptions: params.lbo,
+            logger: params.logSink,
+        });
+    }
+    catch (err) {
+        await params.conn.close().catch(() => { });
+        await params.onContextError?.();
+        throw err;
+    }
+    const cleanup = onceAsync(async () => {
+        await params.conn.close().catch(() => { });
+    });
+    const handstage = createHandstageForConnection({
+        connection: params.conn,
+        cleanup,
+        defaultContext: ctx,
+        opts: params.sharedOpts,
+        logSink: params.logSink,
+    });
+    await applyPostConnectLocalOptions(handstage, params.lbo);
+    return handstage;
+}
+export async function createSharedHandstage(params) {
+    const ctx = await Context.createFromConnection(params.conn, {
+        localBrowserLaunchOptions: params.lbo,
+        logger: params.logSink,
+    });
+    const handstage = createHandstageForConnection({
+        connection: params.conn,
+        defaultContext: ctx,
+        opts: params.sharedOpts,
+        logSink: params.logSink,
+    });
+    await applyPostConnectLocalOptions(handstage, params.lbo);
+    return handstage;
+}
+async function applyPostConnectLocalOptions(handstage, lbo) {
+    await handstage
+        .defaultBrowserContext()
+        .setDownloadBehavior({
+        downloadPath: lbo.downloadsPath,
+        acceptDownloads: lbo.acceptDownloads,
+    })
+        .catch(() => { });
+}

package/dist/v3/connect/transport.js

@@ -0,0 +1,18 @@
+import { LogLevel } from "../types/public/logs";
+import { CDPConnection } from "../understudy/cdp";
+import { connectOptionsToLocalBrowserLaunchOptions, createOwnedHandstage, setupConnectContext, } from "./shared";
+export async function connectTransport(transport, opts) {
+    const { sharedOpts, logSink, logger } = setupConnectContext(opts);
+    logger({
+        category: "init",
+        message: "Connecting via custom transport",
+        level: LogLevel.Info,
+    });
+    const conn = new CDPConnection(transport);
+    return await createOwnedHandstage({
+        conn,
+        lbo: connectOptionsToLocalBrowserLaunchOptions(opts),
+        sharedOpts,
+        logSink,
+    });
+}

package/dist/v3/connect/ws.js

@@ -0,0 +1,34 @@
+import { LogLevel } from "../types/public/logs";
+import { CDPConnection } from "../understudy/cdp";
+import { connectOptionsToLocalBrowserLaunchOptions, createOwnedHandstage, setupConnectContext, } from "./shared";
+export async function connectWS(ws, opts) {
+    const { sharedOpts, logSink, logger } = setupConnectContext(opts);
+    logger({
+        category: "init",
+        message: "Connecting via WebSocket",
+        level: LogLevel.Info,
+    });
+    const transport = {
+        send: (message) => ws.send(message),
+        close: () => ws.close(),
+    };
+    ws.addEventListener("message", (event) => {
+        if (transport.onmessage)
+            transport.onmessage(event.data.toString());
+    });
+    ws.addEventListener("close", (event) => {
+        if (transport.onclose)
+            transport.onclose(`code=${event.code} reason=${event.reason}`);
+    });
+    ws.addEventListener("error", () => {
+        if (transport.onerror)
+            transport.onerror(new Error("WebSocket error"));
+    });
+    const conn = new CDPConnection(transport);
+    return await createOwnedHandstage({
+        conn,
+        lbo: connectOptionsToLocalBrowserLaunchOptions(opts),
+        sharedOpts,
+        logSink,
+    });
+}