runline 0.23.0 → 0.24.0

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();