runline 0.23.0 → 0.25.0

package/dist/plugins/steel/src/page/cdp.js

@@ -0,0 +1,232 @@
+/**
+ * A minimal Chrome DevTools Protocol client over the Steel session's
+ * websocket, and the page-bridge channel built on top of it.
+ *
+ * This exists because the Steel plugin cannot assume Playwright: the host
+ * app may not have it installed, and quietly substituting a lookalike is
+ * what made `browser.run` report wrong results instead of failing. Here
+ * the dependency is the protocol itself, which Steel always speaks.
+ *
+ * Scope is deliberate. This is not a browser automation library — it is
+ * the transport for two things: evaluating the page bridge, and
+ * dispatching trusted input. Anything richer belongs in the page bridge,
+ * where it is ordinary DOM code.
+ */
+import { PAGE_BRIDGE_GLOBAL, PAGE_BRIDGE_SOURCE, PAGE_BRIDGE_VERSION, } from "./bundle.generated.js";
+const CONNECT_TIMEOUT_MS = 30_000;
+const COMMAND_TIMEOUT_MS = 30_000;
+export class CdpError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = true) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "CdpError";
+    }
+}
+/** Connect to a CDP endpoint and resolve once the socket is open. */
+export async function connectCdp(url) {
+    const ws = new WebSocket(url);
+    const pending = new Map();
+    const handlers = new Set();
+    let nextId = 0;
+    let closed = null;
+    const failAll = (error) => {
+        closed = error;
+        for (const [id, wait] of pending) {
+            clearTimeout(wait.timer);
+            pending.delete(id);
+            wait.reject(error);
+        }
+    };
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new CdpError("cdp_unavailable", `Timed out connecting to the browser after ${CONNECT_TIMEOUT_MS}ms`)), CONNECT_TIMEOUT_MS);
+        ws.addEventListener("open", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+        ws.addEventListener("error", () => {
+            clearTimeout(timer);
+            reject(new CdpError("cdp_unavailable", "Could not connect to the browser"));
+        }, { once: true });
+    });
+    ws.addEventListener("close", () => failAll(new CdpError("cdp_closed", "The browser connection closed")));
+    ws.addEventListener("message", (event) => {
+        let message;
+        try {
+            message = JSON.parse(String(event.data));
+        }
+        catch {
+            return;
+        }
+        if (typeof message.id === "number") {
+            const wait = pending.get(message.id);
+            if (!wait)
+                return;
+            clearTimeout(wait.timer);
+            pending.delete(message.id);
+            if (message.error) {
+                const error = message.error;
+                wait.reject(new CdpError("cdp_command_failed", error.message ?? "CDP error"));
+            }
+            else {
+                wait.resolve(message.result ?? {});
+            }
+            return;
+        }
+        if (typeof message.method === "string") {
+            // The originating target is on the envelope, not in params. Dropping
+            // it here would make every per-page subscription see every page's
+            // events.
+            const from = typeof message.sessionId === "string" ? message.sessionId : undefined;
+            for (const handler of handlers) {
+                handler(message.method, (message.params ?? {}), from);
+            }
+        }
+    });
+    return {
+        get alive() {
+            return closed === null;
+        },
+        send(method, params = {}, sessionId) {
+            if (closed)
+                return Promise.reject(closed);
+            return new Promise((resolve, reject) => {
+                const id = ++nextId;
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    reject(new CdpError("cdp_timeout", `${method} timed out`));
+                }, COMMAND_TIMEOUT_MS);
+                pending.set(id, {
+                    resolve: resolve,
+                    reject,
+                    timer,
+                });
+                ws.send(JSON.stringify({
+                    id,
+                    method,
+                    params,
+                    ...(sessionId ? { sessionId } : {}),
+                }));
+            });
+        },
+        on(handler) {
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+        close() {
+            failAll(new CdpError("cdp_closed", "The browser connection was closed"));
+            try {
+                ws.close();
+            }
+            catch {
+                // Already closing; nothing to recover.
+            }
+        },
+    };
+}
+/**
+ * One attached page target, with the page bridge kept installed on it.
+ */
+export class CdpPage {
+    cdp;
+    targetId;
+    sessionId;
+    constructor(cdp, targetId, sessionId) {
+        this.cdp = cdp;
+        this.targetId = targetId;
+        this.sessionId = sessionId;
+    }
+    send(method, params = {}) {
+        return this.cdp.send(method, params, this.sessionId);
+    }
+    /** Subscribe to this page's protocol events; returns an unsubscribe. */
+    onEvent(handler) {
+        return this.cdp.on((method, params, from) => {
+            if (from !== undefined && from !== this.sessionId)
+                return;
+            handler(method, params);
+        });
+    }
+    /** Evaluate an expression in the page and return its value. */
+    async evaluate(expression) {
+        const result = (await this.send("Runtime.evaluate", {
+            expression,
+            returnByValue: true,
+            awaitPromise: true,
+        }));
+        if (result.exceptionDetails) {
+            const detail = result.exceptionDetails;
+            throw new CdpError("page_error", detail.exception?.description ?? detail.text ?? "Page evaluation failed");
+        }
+        return result.result?.value;
+    }
+    /**
+     * Call the page bridge, installing it first when the world does not
+     * have it. Navigation destroys the world, so this self-heals rather
+     * than requiring callers to track page lifetime.
+     */
+    async bridge(request) {
+        let response = await this.callBridge(request);
+        if (response === undefined) {
+            await this.installBridge();
+            response = await this.callBridge(request);
+        }
+        if (response === undefined) {
+            throw new CdpError("page_unavailable", "The page bridge did not install; the page may have navigated mid-action");
+        }
+        const outcome = response;
+        if (!outcome.ok) {
+            throw new CdpError(outcome.error.code, outcome.error.message, outcome.error.retryable);
+        }
+        return outcome.value;
+    }
+    async callBridge(request) {
+        return await this.evaluate(`(() => {
+        const bridge = window[${JSON.stringify(PAGE_BRIDGE_GLOBAL)}];
+        if (!bridge || bridge.version !== ${PAGE_BRIDGE_VERSION}) return undefined;
+        return bridge.handle(${JSON.stringify(request)});
+      })()`);
+    }
+    async installBridge() {
+        await this.evaluate(PAGE_BRIDGE_SOURCE);
+    }
+    /**
+     * Install the bridge on every future document too. Without this the
+     * first call after any navigation pays a reinstall round trip, and a
+     * page that navigates itself mid-action could be observed bridgeless.
+     */
+    async installOnNewDocuments() {
+        await this.send("Page.addScriptToEvaluateOnNewDocument", {
+            source: PAGE_BRIDGE_SOURCE,
+        });
+    }
+}
+/** Attach to the session's first page target. */
+export async function attachToPage(cdp) {
+    const { targetInfos } = (await cdp.send("Target.getTargets"));
+    const pages = (targetInfos ?? []).filter((info) => info.type === "page");
+    const target = pages[0];
+    if (!target) {
+        throw new CdpError("page_unavailable", "The browser session has no page to control", false);
+    }
+    return await attachToTarget(cdp, target.targetId);
+}
+export async function attachToTarget(cdp, targetId) {
+    const { sessionId } = (await cdp.send("Target.attachToTarget", {
+        targetId,
+        flatten: true,
+    }));
+    const page = new CdpPage(cdp, targetId, sessionId);
+    await page.send("Page.enable");
+    await page.send("Runtime.enable");
+    await page.send("DOM.enable");
+    // Needed before cookies can be written on the target.
+    await page.send("Network.enable");
+    await page.installOnNewDocuments();
+    // The bridge is installed lazily by the first `bridge()` call, which
+    // already probes for it and self-heals. Installing here as well would
+    // re-evaluate the whole bundle on every attach for no benefit.
+    return page;
+}

package/dist/plugins/steel/src/page/driver.js

@@ -0,0 +1,286 @@
+/**
+ * Trusted browser input over raw CDP.
+ *
+ * CDP domains are addressed directly rather than through a browser
+ * automation library, because the plugin must work in hosts that have
+ * none installed. The events are the real ones — `Input.dispatchMouseEvent`
+ * and friends produce `isTrusted` events, so pages that reject synthetic
+ * input behave as they do for a person.
+ *
+ * Targets arrive as a `locatorToken` the page bridge stamped onto the
+ * element. Resolving that token to coordinates happens here, immediately
+ * before dispatch, so a layout shift between preparation and action is
+ * caught rather than clicked through.
+ */
+import { CdpError } from "./cdp.js";
+import { TARGET_ATTRIBUTE } from "./page-snapshot.js";
+const MODIFIER_BITS = {
+    Alt: 1,
+    Control: 2,
+    Meta: 4,
+    Shift: 8,
+};
+/**
+ * CDP wants a bitmask; the tools speak in names. Unknown names are
+ * refused rather than folded in as `undefined`, which would turn the
+ * whole mask into NaN and silently strip every modifier.
+ */
+function modifierMask(modifiers = []) {
+    let mask = 0;
+    for (const name of modifiers) {
+        const bit = MODIFIER_BITS[name];
+        if (bit === undefined) {
+            throw new CdpError("invalid_arguments", `Unknown modifier ${name}; expected Alt, Control, Meta, or Shift`, false);
+        }
+        mask |= bit;
+    }
+    return mask;
+}
+/** A page expression selecting the element the bridge stamped for us. */
+function elementExpression(locatorToken) {
+    return `document.querySelector(${JSON.stringify(`[${TARGET_ATTRIBUTE}=${JSON.stringify(locatorToken)}]`)})`;
+}
+export class CdpDriver {
+    page;
+    openDialog = null;
+    detachDialogs;
+    constructor(page) {
+        this.page = page;
+        // Dialogs block the renderer: every subsequent evaluate would hang
+        // until one is handled, so the tools need to see it as a result
+        // rather than as a timeout.
+        this.detachDialogs = page.onEvent((method, params) => {
+            if (method === "Page.javascriptDialogOpening") {
+                this.openDialog = {
+                    type: String(params.type ?? "dialog"),
+                    message: String(params.message ?? ""),
+                    defaultValue: String(params.defaultPrompt ?? ""),
+                };
+            }
+            if (method === "Page.javascriptDialogClosed")
+                this.openDialog = null;
+        });
+    }
+    dialog() {
+        return this.openDialog;
+    }
+    dispose() {
+        this.detachDialogs();
+    }
+    async handleDialog(options) {
+        if (!this.openDialog) {
+            throw new CdpError("no_dialog", "No dialog is currently open", false);
+        }
+        await this.page.send("Page.handleJavaScriptDialog", {
+            accept: options.accept,
+            ...(options.promptText === undefined
+                ? {}
+                : { promptText: options.promptText }),
+        });
+        this.openDialog = null;
+    }
+    /**
+     * Resolve a prepared token to viewport coordinates. Runs in the page so
+     * the element's own scroll container is honoured, and fails loudly when
+     * the element has gone or moved out of view.
+     */
+    async point(target) {
+        const box = await this.page.evaluate(`(() => {
+      const el = ${elementExpression(target.locatorToken)};
+      if (!el) return { error: 'detached' };
+      el.scrollIntoView({ block: 'center', inline: 'center' });
+      const r = el.getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0) return { error: 'not_visible' };
+      return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+    })()`);
+        if ("error" in box) {
+            throw box.error === "detached"
+                ? new CdpError("stale_ref", "The target element left the page between preparing and acting on it. Capture a fresh snapshot and retry.")
+                : new CdpError("element_not_visible", "The target element is not visible at action time");
+        }
+        return box;
+    }
+    async mouse(type, point, options = {}) {
+        await this.page.send("Input.dispatchMouseEvent", {
+            type,
+            x: point.x,
+            y: point.y,
+            button: options.button ?? "left",
+            clickCount: options.clickCount ?? 0,
+            modifiers: options.modifiers ?? 0,
+        });
+    }
+    async click(target, options) {
+        const point = await this.point(target);
+        const modifiers = modifierMask(options.modifiers);
+        const button = options.button ?? "left";
+        await this.mouse("mouseMoved", point, { modifiers });
+        const clicks = options.doubleClick ? 2 : 1;
+        for (let index = 1; index <= clicks; index += 1) {
+            await this.mouse("mousePressed", point, {
+                button,
+                clickCount: index,
+                modifiers,
+            });
+            await this.mouse("mouseReleased", point, {
+                button,
+                clickCount: index,
+                modifiers,
+            });
+        }
+    }
+    async hover(target) {
+        await this.mouse("mouseMoved", await this.point(target));
+    }
+    async drag(start, end) {
+        const from = await this.point(start);
+        const to = await this.point(end);
+        await this.mouse("mouseMoved", from);
+        await this.mouse("mousePressed", from, { clickCount: 1 });
+        // Intermediate moves: drag handlers commonly ignore a single jump.
+        for (let step = 1; step <= 4; step += 1) {
+            await this.mouse("mouseMoved", {
+                x: from.x + ((to.x - from.x) * step) / 4,
+                y: from.y + ((to.y - from.y) * step) / 4,
+            });
+        }
+        await this.mouse("mouseReleased", to, { clickCount: 1 });
+    }
+    async scroll(deltaY, target) {
+        const point = target
+            ? await this.point(target)
+            : await this.viewportCentre();
+        await this.page.send("Input.dispatchMouseEvent", {
+            type: "mouseWheel",
+            x: point.x,
+            y: point.y,
+            deltaX: 0,
+            deltaY,
+        });
+    }
+    async viewportCentre() {
+        return await this.page.evaluate("({ x: window.innerWidth / 2, y: window.innerHeight / 2 })");
+    }
+    async type(target, text, options) {
+        // The bridge already focused the element and set the selection for
+        // replace/append, so typing here just replays keys into it.
+        if (options.slowly) {
+            for (const char of text)
+                await this.insertKey(char);
+            return;
+        }
+        if (text.length === 0) {
+            // Replace-mode with empty text means "clear": the selection is
+            // set, so a delete is what removes it.
+            await this.press("Delete");
+            return;
+        }
+        await this.page.send("Input.insertText", { text });
+    }
+    async insertKey(char) {
+        await this.page.send("Input.dispatchKeyEvent", {
+            type: "keyDown",
+            text: char,
+            unmodifiedText: char,
+        });
+        await this.page.send("Input.dispatchKeyEvent", {
+            type: "keyUp",
+            text: char,
+        });
+    }
+    async press(key) {
+        const parts = key.split("+");
+        const main = parts[parts.length - 1] ?? key;
+        const modifiers = modifierMask(parts.slice(0, -1));
+        const descriptor = keyDescriptor(main);
+        await this.page.send("Input.dispatchKeyEvent", {
+            type: descriptor.text ? "keyDown" : "rawKeyDown",
+            modifiers,
+            ...descriptor,
+        });
+        await this.page.send("Input.dispatchKeyEvent", {
+            type: "keyUp",
+            modifiers,
+            ...descriptor,
+        });
+    }
+    async select(target, values) {
+        const ok = await this.page.evaluate(`(() => {
+      const el = ${elementExpression(target.locatorToken)};
+      if (!el) return false;
+      const wanted = new Set(${JSON.stringify(values)});
+      for (const option of el.options) option.selected = wanted.has(option.value);
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+      return true;
+    })()`);
+        if (!ok) {
+            throw new CdpError("stale_ref", "The select element left the page between preparing and acting on it. Capture a fresh snapshot and retry.");
+        }
+    }
+    async screenshot(options) {
+        const params = {
+            format: "jpeg",
+            quality: 80,
+        };
+        if (options.fullPage)
+            params.captureBeyondViewport = true;
+        const result = (await this.page.send("Page.captureScreenshot", params));
+        return { data: result.data, mimeType: "image/jpeg" };
+    }
+    /** Let the page react to the action before it is snapshotted. */
+    async settle() {
+        await new Promise((resolve) => setTimeout(resolve, 120));
+        if (this.openDialog)
+            return;
+        await this.page
+            .evaluate(`new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)))`)
+            .catch(() => {
+            // A navigation or dialog can tear down the world mid-settle;
+            // the caller's snapshot reports the real state either way.
+        });
+    }
+}
+const NAMED_KEYS = {
+    Enter: { code: "Enter", keyCode: 13 },
+    Tab: { code: "Tab", keyCode: 9 },
+    Escape: { code: "Escape", keyCode: 27 },
+    Backspace: { code: "Backspace", keyCode: 8 },
+    Delete: { code: "Delete", keyCode: 46 },
+    ArrowUp: { code: "ArrowUp", keyCode: 38 },
+    ArrowDown: { code: "ArrowDown", keyCode: 40 },
+    ArrowLeft: { code: "ArrowLeft", keyCode: 37 },
+    ArrowRight: { code: "ArrowRight", keyCode: 39 },
+    Home: { code: "Home", keyCode: 36 },
+    End: { code: "End", keyCode: 35 },
+    PageUp: { code: "PageUp", keyCode: 33 },
+    PageDown: { code: "PageDown", keyCode: 34 },
+    Space: { code: "Space", keyCode: 32 },
+};
+/**
+ * CDP needs `key`/`code`/`windowsVirtualKeyCode` for non-printable keys;
+ * printable ones also need `text` or they arrive as bare keydowns.
+ */
+function keyDescriptor(key) {
+    const match = NAMED_KEYS[key];
+    if (match) {
+        return {
+            key: key === "Space" ? " " : key,
+            code: match.code,
+            windowsVirtualKeyCode: match.keyCode,
+            ...(key === "Enter" ? { text: "\r" } : {}),
+            ...(key === "Space" ? { text: " " } : {}),
+        };
+    }
+    if (key.length === 1) {
+        const upper = key.toUpperCase();
+        return {
+            key,
+            code: /[a-z]/i.test(key) ? `Key${upper}` : `Digit${key}`,
+            windowsVirtualKeyCode: upper.charCodeAt(0),
+            text: key,
+            unmodifiedText: key,
+        };
+    }
+    return { key };
+}

package/dist/plugins/steel/src/page/entry.js

@@ -0,0 +1,91 @@
+/**
+ * The in-page half of the Steel page tools.
+ *
+ * This module is bundled (see `scripts/build-steel-page-bundle.ts`) into
+ * one self-contained IIFE and evaluated inside the Steel session's page.
+ * Everything here is pure DOM code — it never sees the Steel API key, the
+ * CDP socket, or any plugin state.
+ *
+ * Why a resident global rather than a fresh evaluate per call: element
+ * refs (`e12`) are only stable while the aria-snapshot module's counter
+ * and each element's cached `_ariaRef` survive between calls. A new
+ * bundle per call would renumber every element and silently invalidate
+ * refs the agent is holding. So the bundle installs itself once per
+ * execution context and the driver re-injects only when the world is
+ * gone — which is exactly navigation, where fresh refs are correct.
+ */
+import { PageSnapshotService, BrowserToolError, } from "./page-snapshot.js";
+import { waitForPage } from "./wait-for.js";
+/** Bumped when the in-page contract changes, so a stale world is replaced. */
+export const PAGE_BRIDGE_VERSION = 1;
+export const PAGE_BRIDGE_GLOBAL = "__steelPageBridge";
+export function createPageBridge(document) {
+    let service = new PageSnapshotService(document);
+    let maxChars;
+    return {
+        version: PAGE_BRIDGE_VERSION,
+        async handle(request) {
+            try {
+                return { ok: true, value: await dispatch(request) };
+            }
+            catch (error) {
+                if (error instanceof BrowserToolError) {
+                    return {
+                        ok: false,
+                        error: {
+                            code: error.code,
+                            message: error.message,
+                            retryable: error.retryable,
+                        },
+                    };
+                }
+                return {
+                    ok: false,
+                    error: {
+                        code: "page_error",
+                        message: error instanceof Error ? error.message : String(error),
+                        retryable: true,
+                    },
+                };
+            }
+        },
+    };
+    async function dispatch(request) {
+        switch (request.action) {
+            case "snapshot": {
+                // maxChars is a construction option upstream; honour a per-call
+                // override by rebuilding rather than reaching into the service.
+                if (request.maxChars !== undefined && request.maxChars !== maxChars) {
+                    maxChars = request.maxChars;
+                    service = new PageSnapshotService(document, { maxChars });
+                }
+                return service.capture({
+                    ...(request.depth !== undefined ? { depth: request.depth } : {}),
+                    ...(request.boxes !== undefined ? { boxes: request.boxes } : {}),
+                });
+            }
+            case "prepare_target":
+                return await service.prepareTarget(request.target);
+            case "prepare_editable":
+                return await service.prepareEditableTarget(request.target, request.mode);
+            case "editable_value":
+                return service.readEditableValue(request.target);
+            case "resolve_options":
+                return { selected: service.resolveOptions(request.target, request.values) };
+            case "wait_for":
+                return await waitForPage(document, request);
+        }
+    }
+}
+/**
+ * Install idempotently. Re-evaluating the bundle in a world that already
+ * has a current bridge must not reset the ref counter.
+ */
+export function installPageBridge() {
+    const existing = globalThis[PAGE_BRIDGE_GLOBAL];
+    if (existing?.version === PAGE_BRIDGE_VERSION)
+        return existing;
+    const bridge = createPageBridge(document);
+    globalThis[PAGE_BRIDGE_GLOBAL] = bridge;
+    return bridge;
+}

package/dist/plugins/steel/src/page/install.js

@@ -0,0 +1,3 @@
+/** Bundle entrypoint: install the bridge into the page's global world. */
+import { installPageBridge } from "./entry.js";
+installPageBridge();