browxai 0.7.0

package/dist/page/canvas-capture.js

@@ -0,0 +1,257 @@
+/// <reference lib="dom" />
+// canvas_capture — framebuffer / 2D ImageData / PNG bytes of a `<canvas>`.
+// App-agnostic pixel source for the BYO-vision loop (see canvas.ts header).
+//
+// Bounded: refuses canvases larger than 16384×16384 (CANVAS_MAX_DIMENSION) —
+// a multi-megapixel buffer round-tripped through base64 is genuinely a problem.
+/** Max canvas dimensions accepted by `canvas_capture`. Larger canvases
+ *  refuse with a structured error rather than allocating a giant byte
+ *  payload. 16384 matches Chromium's `max_texture_size` for most
+ *  hardware — a `<canvas>` larger than this would not paint correctly
+ *  anyway. */
+export const CANVAS_MAX_DIMENSION = 16384;
+// The page-side capture is decomposed into per-format helpers so the
+// top-level `PAGE_CAPTURE_FN` stays a small dispatcher. EVERY helper is a
+// nested declaration of PAGE_CAPTURE_FN — the whole thing must serialize as
+// one self-contained function literal across `page.evaluate`, so the helpers
+// cannot live at module scope (they would be lost on serialization). The split
+// is therefore internal to the one function literal.
+/** Page-side capture function — REAL function literal (NOT stringified).
+ *  Playwright's `page.evaluate(fn, arg)` serializes the source + invokes
+ *  in-page with the arg. Mirror of the pattern used in `dom_export` /
+ *  `element_export` / `overflow_detect` — a stringified arrow function
+ *  evaluates to the function value uncalled, which CDP can't serialize.
+ *
+ *  Returns a structured discriminated union (mirror of CanvasCaptureResult)
+ *  so the host side can pass it straight back. */
+export const PAGE_CAPTURE_FN = (args) => {
+    // --- locate ---
+    function locateCanvas() {
+        let canvas = null;
+        if (args.selector) {
+            try {
+                const found = document.querySelector(args.selector);
+                if (found && found.tagName.toLowerCase() === "canvas") {
+                    canvas = found;
+                }
+            }
+            catch (_) {
+                /* ignore — fall through */
+            }
+        }
+        if (!canvas && args.ref) {
+            try {
+                const found = document.querySelector(`[data-browx-ref="${args.ref}"]`);
+                if (found && found.tagName.toLowerCase() === "canvas") {
+                    canvas = found;
+                }
+            }
+            catch (_) {
+                /* ignore */
+            }
+        }
+        if (!canvas) {
+            const all = document.getElementsByTagName("canvas");
+            if (all.length > 0)
+                canvas = all[0];
+        }
+        return canvas;
+    }
+    // --- shared encode helper ---
+    // base64-encode a Uint8Array using only DOM-available builtins. btoa wants
+    // binary string input; build it in chunks so we don't blow the call stack
+    // on huge buffers.
+    function bytesToB64(bytes) {
+        let binary = "";
+        const chunk = 0x8000;
+        for (let i = 0; i < bytes.length; i += chunk) {
+            const slice = bytes.subarray(i, Math.min(i + chunk, bytes.length));
+            binary += String.fromCharCode.apply(null, Array.prototype.slice.call(slice));
+        }
+        return btoa(binary);
+    }
+    // --- per-format captures ---
+    function capturePng(canvas, w, h) {
+        try {
+            const dataUrl = canvas.toDataURL("image/png");
+            const idx = dataUrl.indexOf("base64,");
+            if (idx < 0) {
+                return {
+                    ok: false,
+                    error: "toDataURL did not return a base64 payload",
+                    code: "encode-failed",
+                };
+            }
+            const b64 = dataUrl.slice(idx + 7);
+            // Byte length of decoded PNG ≈ b64.length * 3/4 (minus padding).
+            let pad = 0;
+            if (b64.endsWith("=="))
+                pad = 2;
+            else if (b64.endsWith("="))
+                pad = 1;
+            const byteLength = Math.floor((b64.length * 3) / 4) - pad;
+            return { ok: true, format: "png", contentBase64: b64, byteLength, width: w, height: h };
+        }
+        catch (e) {
+            // toDataURL throws SecurityError on tainted canvases (cross-origin
+            // images without CORS). Surface a clean shape.
+            return {
+                ok: false,
+                error: "canvas.toDataURL failed: " + (e?.message || String(e)),
+                code: "taint-or-encode",
+            };
+        }
+    }
+    function captureImageData(canvas, w, h) {
+        const ctx = canvas.getContext("2d");
+        if (!ctx) {
+            return {
+                ok: false,
+                error: 'canvas has no 2d context (likely a WebGL/WebGPU canvas — try format:"webgl-framebuffer")',
+                code: "no-2d-context",
+            };
+        }
+        try {
+            const data = ctx.getImageData(0, 0, w, h);
+            const bytes = new Uint8Array(data.data.buffer, data.data.byteOffset, data.data.byteLength);
+            return {
+                ok: true,
+                format: "2d-imagedata",
+                contentBase64: bytesToB64(bytes),
+                width: w,
+                height: h,
+                channelCount: 4,
+            };
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: "getImageData failed: " + (e?.message || String(e)),
+                code: "taint-or-read",
+            };
+        }
+    }
+    function captureWebgl(canvas, w, h) {
+        // Try webgl2 first then webgl. Some apps configure
+        // preserveDrawingBuffer:false — readPixels then returns blank because the
+        // compositor cleared the buffer; the caller sees zero-bytes on diff in
+        // that case and we can't undo it without recreating the context.
+        let gl = null;
+        try {
+            gl = canvas.getContext("webgl2", { preserveDrawingBuffer: true });
+        }
+        catch (_) {
+            gl = null;
+        }
+        if (!gl) {
+            try {
+                gl = canvas.getContext("webgl", { preserveDrawingBuffer: true });
+            }
+            catch (_) {
+                gl = null;
+            }
+        }
+        if (!gl) {
+            return {
+                ok: false,
+                error: 'canvas has no webgl/webgl2 context (try format:"2d-imagedata" for a 2D canvas)',
+                code: "no-webgl-context",
+            };
+        }
+        try {
+            const pixels = new Uint8Array(w * h * 4);
+            gl.readPixels(0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+            // WebGL's coordinate origin is bottom-left; flip into top-left order so
+            // downstream `canvas_diff` math is consistent with the imagedata format
+            // (and with PNG / typical screenshot conventions).
+            const flipped = new Uint8Array(w * h * 4);
+            const stride = w * 4;
+            for (let y = 0; y < h; y++) {
+                const src = (h - 1 - y) * stride;
+                const dst = y * stride;
+                flipped.set(pixels.subarray(src, src + stride), dst);
+            }
+            return {
+                ok: true,
+                format: "webgl-framebuffer",
+                contentBase64: bytesToB64(flipped),
+                width: w,
+                height: h,
+                channelCount: 4,
+                isWebGL: true,
+            };
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: "webgl readPixels failed: " + (e?.message || String(e)),
+                code: "webgl-read-failed",
+            };
+        }
+    }
+    // --- dispatch ---
+    const canvas = locateCanvas();
+    if (!canvas) {
+        return {
+            ok: false,
+            error: "no <canvas> element found on the page (ref/selector did not match and no fallback canvas exists)",
+            code: "no-canvas",
+        };
+    }
+    const w = canvas.width;
+    const h = canvas.height;
+    if (w <= 0 || h <= 0) {
+        return {
+            ok: false,
+            error: `canvas dimensions are non-positive (${w}x${h})`,
+            code: "bad-dimensions",
+        };
+    }
+    if (w > args.maxDimension || h > args.maxDimension) {
+        return {
+            ok: false,
+            error: `canvas dimensions ${w}x${h} exceed the maximum ${args.maxDimension}x${args.maxDimension} cap`,
+            code: "too-large",
+        };
+    }
+    if (args.format === "png")
+        return capturePng(canvas, w, h);
+    if (args.format === "2d-imagedata")
+        return captureImageData(canvas, w, h);
+    return captureWebgl(canvas, w, h);
+};
+export async function canvasCapture(page, args) {
+    const r = await page.evaluate(PAGE_CAPTURE_FN, {
+        ref: args.ref,
+        selector: args.selector,
+        format: args.format,
+        maxDimension: CANVAS_MAX_DIMENSION,
+    });
+    if (!r.ok)
+        return {
+            ok: false,
+            error: r.error ?? "canvas_capture failed",
+            ...(r.code ? { code: r.code } : {}),
+        };
+    if (r.format === "png") {
+        return {
+            ok: true,
+            format: "png",
+            contentBase64: r.contentBase64,
+            byteLength: r.byteLength,
+            width: r.width,
+            height: r.height,
+        };
+    }
+    const out = {
+        ok: true,
+        format: r.format,
+        contentBase64: r.contentBase64,
+        width: r.width,
+        height: r.height,
+        channelCount: 4,
+    };
+    if (r.isWebGL)
+        out.isWebGL = true;
+    return out;
+}

package/dist/page/canvas-diff.d.ts

@@ -0,0 +1,51 @@
+export interface CanvasDiffRegion {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface CanvasDiffArgs {
+    /** Base64 RGBA bytes (or PNG — see note below) from a prior capture. */
+    beforeBase64: string;
+    /** Base64 RGBA bytes (or PNG) from a later capture. */
+    afterBase64: string;
+    /** Optional sub-rectangle (in pixels, top-left origin). When omitted,
+     *  the diff covers the whole image. */
+    region?: CanvasDiffRegion;
+    /** Pixel dimensions of the two captures. Required when both inputs are
+     *  RGBA bytes — the byte buffer alone does not carry width/height. */
+    width?: number;
+    height?: number;
+    /** Tag the inputs explicitly when known. Defaults to `rgba`; pass
+     *  `png` to surface the PNG-decode caveat in the warnings. */
+    inputFormat?: "rgba" | "png";
+}
+export interface CanvasDiffResult {
+    ok: boolean;
+    /** Number of pixels with any RGBA channel differing between before/
+     *  after within the region. For PNG inputs (no decode this cycle),
+     *  reports 0 when the base64 strings match byte-for-byte, otherwise
+     *  the total pixel count of the region and surfaces a warning. */
+    changedPixelCount: number;
+    /** Sum of absolute per-channel differences across all changed pixels
+     *  (cap-summed at 4 channels per pixel). Useful for "how much
+     *  changed", not just "did anything". */
+    changedBytes: number;
+    /** Ratio of changed pixels to total pixels in the region (0..1). */
+    percentageChanged: number;
+    /** Tight bounding box of the changed area, in image coordinates. Null
+     *  when no pixels changed. */
+    bboxOfChanges: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    warnings: string[];
+    error?: string;
+    code?: string;
+}
+/** Pure function — pixel diff math on two RGBA byte buffers. Exposed for
+ *  unit tests; the MCP handler in server.ts unwraps the base64. */
+export declare function diffRgba(before: Uint8Array, after: Uint8Array, width: number, height: number, region?: CanvasDiffRegion): Omit<CanvasDiffResult, "warnings" | "error" | "code">;
+export declare function canvasDiff(args: CanvasDiffArgs): CanvasDiffResult;

package/dist/page/canvas-diff.js

@@ -0,0 +1,131 @@
+// canvas_diff — pixel/region delta between two RGBA captures. Pure function
+// over bytes; no page contact. (See canvas.ts header for the tool overview.)
+/** Pure function — pixel diff math on two RGBA byte buffers. Exposed for
+ *  unit tests; the MCP handler in server.ts unwraps the base64. */
+export function diffRgba(before, after, width, height, region) {
+    const expected = width * height * 4;
+    if (before.length !== expected || after.length !== expected) {
+        return {
+            ok: false,
+            changedPixelCount: 0,
+            changedBytes: 0,
+            percentageChanged: 0,
+            bboxOfChanges: null,
+        };
+    }
+    const r = region ?? { x: 0, y: 0, w: width, h: height };
+    // Clamp the region to image bounds (an over-flow region collapses
+    // into the available pixel rectangle rather than throwing).
+    const x0 = Math.max(0, Math.min(width, Math.floor(r.x)));
+    const y0 = Math.max(0, Math.min(height, Math.floor(r.y)));
+    const x1 = Math.max(0, Math.min(width, Math.floor(r.x + r.w)));
+    const y1 = Math.max(0, Math.min(height, Math.floor(r.y + r.h)));
+    if (x1 <= x0 || y1 <= y0) {
+        return {
+            ok: true,
+            changedPixelCount: 0,
+            changedBytes: 0,
+            percentageChanged: 0,
+            bboxOfChanges: null,
+        };
+    }
+    let changed = 0;
+    let bytes = 0;
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    const totalPixels = (x1 - x0) * (y1 - y0);
+    for (let y = y0; y < y1; y++) {
+        for (let x = x0; x < x1; x++) {
+            const idx = (y * width + x) * 4;
+            const r0 = before[idx], g0 = before[idx + 1], b0 = before[idx + 2], a0 = before[idx + 3];
+            const r1 = after[idx], g1 = after[idx + 1], b1 = after[idx + 2], a1 = after[idx + 3];
+            const d = Math.abs(r1 - r0) + Math.abs(g1 - g0) + Math.abs(b1 - b0) + Math.abs(a1 - a0);
+            if (d !== 0) {
+                changed++;
+                bytes += d;
+                if (x < minX)
+                    minX = x;
+                if (y < minY)
+                    minY = y;
+                if (x > maxX)
+                    maxX = x;
+                if (y > maxY)
+                    maxY = y;
+            }
+        }
+    }
+    return {
+        ok: true,
+        changedPixelCount: changed,
+        changedBytes: bytes,
+        percentageChanged: totalPixels === 0 ? 0 : changed / totalPixels,
+        bboxOfChanges: changed === 0 ? null : { x: minX, y: minY, w: maxX - minX + 1, h: maxY - minY + 1 },
+    };
+}
+export function canvasDiff(args) {
+    const warnings = [];
+    const inputFormat = args.inputFormat ?? "rgba";
+    // PNG path (deferred — just compare base64 byte equality this cycle).
+    // The roadmap note in the spec: "for PNG format inputs: document that
+    // PNG-decoded-pixel diff is a follow-up (just compare base64 byte
+    // equality for now and surface a warning when inputs are PNG instead
+    // of RGBA)."
+    if (inputFormat === "png") {
+        warnings.push("PNG-decoded pixel diff is a follow-up — this cycle compares base64 byte equality only. " +
+            "For per-pixel + bbox math, recapture with format:'2d-imagedata' or format:'webgl-framebuffer'.");
+        const same = args.beforeBase64 === args.afterBase64;
+        return {
+            ok: true,
+            changedPixelCount: same ? 0 : 1,
+            changedBytes: same ? 0 : 1,
+            percentageChanged: same ? 0 : 1,
+            bboxOfChanges: null,
+            warnings,
+        };
+    }
+    if (args.width === undefined || args.height === undefined) {
+        return {
+            ok: false,
+            changedPixelCount: 0,
+            changedBytes: 0,
+            percentageChanged: 0,
+            bboxOfChanges: null,
+            warnings,
+            error: "canvas_diff with format:'rgba' inputs requires width + height — the byte buffer does not carry dimensions",
+            code: "missing-dimensions",
+        };
+    }
+    let before;
+    let after;
+    try {
+        before = Buffer.from(args.beforeBase64, "base64");
+        after = Buffer.from(args.afterBase64, "base64");
+    }
+    catch (e) {
+        return {
+            ok: false,
+            changedPixelCount: 0,
+            changedBytes: 0,
+            percentageChanged: 0,
+            bboxOfChanges: null,
+            warnings,
+            error: "canvas_diff: failed to base64-decode an input — " +
+                (e instanceof Error ? e.message : String(e)),
+            code: "decode-failed",
+        };
+    }
+    const expected = args.width * args.height * 4;
+    if (before.length !== expected || after.length !== expected) {
+        return {
+            ok: false,
+            changedPixelCount: 0,
+            changedBytes: 0,
+            percentageChanged: 0,
+            bboxOfChanges: null,
+            warnings,
+            error: `canvas_diff: RGBA byte length mismatch — got before=${before.length}, after=${after.length}, expected ${expected} (width*height*4)`,
+            code: "shape-mismatch",
+        };
+    }
+    const r = diffRgba(before, after, args.width, args.height, args.region);
+    return { ...r, warnings };
+}

package/dist/page/canvas-gesture.d.ts

@@ -0,0 +1,53 @@
+export type GestureChainStepKind = "down" | "move" | "up" | "wait" | "wheel";
+export interface GestureChainStep {
+    kind: GestureChainStepKind;
+    x?: number;
+    y?: number;
+    deltaX?: number;
+    deltaY?: number;
+    ms?: number;
+    pointerId?: number;
+}
+export interface GestureChainArgs {
+    steps: GestureChainStep[];
+}
+export interface GestureChainResult {
+    ok: boolean;
+    stepsExecuted: number;
+    totalDurationMs: number;
+    warnings: string[];
+    error?: string;
+    code?: string;
+}
+export declare const GESTURE_CHAIN_MAX_STEPS = 200;
+export declare const GESTURE_CHAIN_MIN_MOVE_MS = 5;
+export declare const GESTURE_CHAIN_MAX_WAIT_MS = 5000;
+export interface ValidateGestureChainResult {
+    ok: boolean;
+    steps: GestureChainStep[];
+    warnings: string[];
+    error?: string;
+    code?: string;
+}
+/** Validate + clamp a gesture-chain step list. Pure function — returns
+ *  the normalised step list + any warnings the runtime should surface.
+ *  Hard caps (max steps) refuse loudly; soft caps (min move ms, max wait
+ *  ms) clamp + warn. */
+export declare function validateGestureChain(steps: GestureChainStep[]): ValidateGestureChainResult;
+/** Thin adapter so unit tests can stub Playwright's `page.mouse`. */
+export interface GestureChainPage {
+    mouse: {
+        down(options?: {
+            button?: "left" | "right" | "middle";
+        }): Promise<void>;
+        move(x: number, y: number, options?: {
+            steps?: number;
+        }): Promise<void>;
+        up(options?: {
+            button?: "left" | "right" | "middle";
+        }): Promise<void>;
+        wheel(deltaX: number, deltaY: number): Promise<void>;
+    };
+}
+/** Execute a validated step list against a Playwright page mouse. */
+export declare function runGestureChain(page: GestureChainPage, args: GestureChainArgs): Promise<GestureChainResult>;

package/dist/page/canvas-gesture.js

@@ -0,0 +1,167 @@
+// gesture_chain — multi-step pointer program (down / move / wheel / wait /
+// up). Custom paint strokes, lasso paths, and gestures the canned `drag` /
+// `gesture_swipe` family doesn't cover. (See canvas.ts header.)
+//
+// Bounded: caps at 200 steps, floors `move` step delays at 5 ms, bounds
+// `wait` steps at 5000 ms.
+export const GESTURE_CHAIN_MAX_STEPS = 200;
+export const GESTURE_CHAIN_MIN_MOVE_MS = 5;
+export const GESTURE_CHAIN_MAX_WAIT_MS = 5000;
+function badStep(error) {
+    return { ok: false, error, code: "bad-step" };
+}
+/** Validate + clamp a single pointer step (`down`/`up`/`move`). `move`
+ *  floors its delay at GESTURE_CHAIN_MIN_MOVE_MS, warning when it clamps. */
+function validatePointerStep(s, i, warnings) {
+    if (typeof s.x !== "number" || typeof s.y !== "number") {
+        return badStep(`gesture_chain: step[${i}] kind="${s.kind}" requires numeric x + y`);
+    }
+    const clamped = { kind: s.kind, x: s.x, y: s.y };
+    if (s.pointerId !== undefined)
+        clamped.pointerId = s.pointerId;
+    if (s.kind === "move") {
+        const ms = typeof s.ms === "number" ? s.ms : GESTURE_CHAIN_MIN_MOVE_MS;
+        if (ms < GESTURE_CHAIN_MIN_MOVE_MS) {
+            warnings.push(`gesture_chain: step[${i}] move ms=${ms} floored to ${GESTURE_CHAIN_MIN_MOVE_MS}ms — tighter pacing rarely changes app behaviour and starves the renderer`);
+            clamped.ms = GESTURE_CHAIN_MIN_MOVE_MS;
+        }
+        else {
+            clamped.ms = ms;
+        }
+    }
+    return { ok: true, step: clamped };
+}
+/** Validate + clamp a `wait` step. Refuses negatives; clamps over-long
+ *  waits at GESTURE_CHAIN_MAX_WAIT_MS with a warning. */
+function validateWaitStep(s, i, warnings) {
+    const ms = typeof s.ms === "number" ? s.ms : 0;
+    if (ms < 0) {
+        return badStep(`gesture_chain: step[${i}] wait ms must be non-negative`);
+    }
+    const clamped = { kind: "wait" };
+    if (ms > GESTURE_CHAIN_MAX_WAIT_MS) {
+        warnings.push(`gesture_chain: step[${i}] wait ms=${ms} clamped to max ${GESTURE_CHAIN_MAX_WAIT_MS}ms — a single chained wait should not exceed 5s; split across calls`);
+        clamped.ms = GESTURE_CHAIN_MAX_WAIT_MS;
+    }
+    else {
+        clamped.ms = ms;
+    }
+    return { ok: true, step: clamped };
+}
+/** Validate a `wheel` step — requires a non-zero delta; carries optional
+ *  cursor position. */
+function validateWheelStep(s, i) {
+    const dx = typeof s.deltaX === "number" ? s.deltaX : 0;
+    const dy = typeof s.deltaY === "number" ? s.deltaY : 0;
+    if (dx === 0 && dy === 0) {
+        return badStep(`gesture_chain: step[${i}] wheel requires non-zero deltaX or deltaY`);
+    }
+    const clamped = { kind: "wheel", deltaX: dx, deltaY: dy };
+    if (typeof s.x === "number")
+        clamped.x = s.x;
+    if (typeof s.y === "number")
+        clamped.y = s.y;
+    return { ok: true, step: clamped };
+}
+function validateStep(s, i, warnings) {
+    if (!s || typeof s.kind !== "string") {
+        return badStep(`gesture_chain: step[${i}] missing kind`);
+    }
+    if (s.kind === "down" || s.kind === "up" || s.kind === "move") {
+        return validatePointerStep(s, i, warnings);
+    }
+    if (s.kind === "wait")
+        return validateWaitStep(s, i, warnings);
+    if (s.kind === "wheel")
+        return validateWheelStep(s, i);
+    return badStep(`gesture_chain: step[${i}] unknown kind "${String(s.kind)}"`);
+}
+/** Validate + clamp a gesture-chain step list. Pure function — returns
+ *  the normalised step list + any warnings the runtime should surface.
+ *  Hard caps (max steps) refuse loudly; soft caps (min move ms, max wait
+ *  ms) clamp + warn. */
+export function validateGestureChain(steps) {
+    const warnings = [];
+    if (!Array.isArray(steps) || steps.length === 0) {
+        return {
+            ok: false,
+            steps: [],
+            warnings,
+            error: "gesture_chain: `steps` must be a non-empty array",
+            code: "no-steps",
+        };
+    }
+    if (steps.length > GESTURE_CHAIN_MAX_STEPS) {
+        return {
+            ok: false,
+            steps: [],
+            warnings,
+            error: `gesture_chain: ${steps.length} steps exceeds the maximum ${GESTURE_CHAIN_MAX_STEPS}; split the program across multiple calls`,
+            code: "too-many-steps",
+        };
+    }
+    const out = [];
+    for (let i = 0; i < steps.length; i++) {
+        const outcome = validateStep(steps[i], i, warnings);
+        if (!outcome.ok) {
+            return { ok: false, steps: [], warnings, error: outcome.error, code: outcome.code };
+        }
+        out.push(outcome.step);
+    }
+    return { ok: true, steps: out, warnings };
+}
+/** Execute one validated step against the page mouse. */
+async function runGestureStep(page, s) {
+    if (s.kind === "down") {
+        // Position the pointer at the down point so the press lands where the
+        // caller asked. Playwright's mouse.down() acts at the current pointer
+        // position only.
+        await page.mouse.move(s.x, s.y);
+        await page.mouse.down();
+    }
+    else if (s.kind === "up") {
+        await page.mouse.move(s.x, s.y);
+        await page.mouse.up();
+    }
+    else if (s.kind === "move") {
+        await page.mouse.move(s.x, s.y);
+        if (s.ms && s.ms > 0)
+            await new Promise((r) => setTimeout(r, s.ms));
+    }
+    else if (s.kind === "wait") {
+        if (s.ms && s.ms > 0)
+            await new Promise((r) => setTimeout(r, s.ms));
+    }
+    else if (s.kind === "wheel") {
+        if (typeof s.x === "number" && typeof s.y === "number") {
+            await page.mouse.move(s.x, s.y);
+        }
+        await page.mouse.wheel(s.deltaX ?? 0, s.deltaY ?? 0);
+    }
+}
+/** Execute a validated step list against a Playwright page mouse. */
+export async function runGestureChain(page, args) {
+    const v = validateGestureChain(args.steps);
+    if (!v.ok) {
+        return {
+            ok: false,
+            stepsExecuted: 0,
+            totalDurationMs: 0,
+            warnings: v.warnings,
+            ...(v.error ? { error: v.error } : {}),
+            ...(v.code ? { code: v.code } : {}),
+        };
+    }
+    const started = Date.now();
+    let executed = 0;
+    for (const s of v.steps) {
+        await runGestureStep(page, s);
+        executed++;
+    }
+    return {
+        ok: true,
+        stepsExecuted: executed,
+        totalDurationMs: Date.now() - started,
+        warnings: v.warnings,
+    };
+}