browxai 0.7.0

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

@@ -0,0 +1,96 @@
+export interface CanvasTransform {
+    scale: number;
+    panX: number;
+    panY: number;
+    /** Optional origin offsets — added after the scale/pan. Default 0. */
+    originX?: number;
+    originY?: number;
+}
+export type CanvasAdapterHint = "figma" | "tldraw" | "excalidraw" | "generic";
+export interface CanvasWorldToScreenArgs {
+    worldX: number;
+    worldY: number;
+    ref?: string;
+    selector?: string;
+    transform?: CanvasTransform;
+}
+export interface CanvasScreenToWorldArgs {
+    screenX: number;
+    screenY: number;
+    ref?: string;
+    selector?: string;
+    transform?: CanvasTransform;
+}
+export interface CanvasWorldToScreenResult {
+    ok: boolean;
+    screenX?: number;
+    screenY?: number;
+    transformDiscovered?: CanvasTransform;
+    adapterHint?: CanvasAdapterHint;
+    warnings?: string[];
+    error?: string;
+    code?: string;
+}
+export interface CanvasScreenToWorldResult {
+    ok: boolean;
+    worldX?: number;
+    worldY?: number;
+    transformDiscovered?: CanvasTransform;
+    adapterHint?: CanvasAdapterHint;
+    warnings?: string[];
+    error?: string;
+    code?: string;
+}
+/** Pure math — apply an affine transform to a world point.
+ *  `screen = (world + pan) * scale + origin`. Documented this way (rather
+ *  than the matrix form) because that's the shape the discovery probes
+ *  return for the three named editors. */
+export declare function applyWorldToScreen(world: {
+    x: number;
+    y: number;
+}, t: CanvasTransform): {
+    x: number;
+    y: number;
+};
+/** Inverse: `world = (screen - origin) / scale - pan`. Round-trips with
+ *  `applyWorldToScreen` to within fp precision. */
+export declare function applyScreenToWorld(screen: {
+    x: number;
+    y: number;
+}, t: CanvasTransform): {
+    x: number;
+    y: number;
+};
+/** Page-side discovery probe — REAL function literal. Returns the best
+ *  candidate transform found by walking known app-side global shapes,
+ *  plus an adapter hint naming which shape matched. Order matters:
+ *  Figma/Excalidraw shape is the most common; Tldraw's distinct shape
+ *  is tried next; finally the generic 3x3 matrix path. */
+export declare const PAGE_DISCOVER_TRANSFORM_FN: () => {
+    ok: boolean;
+    transform?: CanvasTransform;
+    adapterHint?: CanvasAdapterHint;
+};
+/** Thin adapter interface — server.ts owns the page-side evaluate call. */
+export interface CanvasDiscoverPage {
+    evaluate<T, Arg>(fn: (arg: Arg) => T | Promise<T>, args?: Arg): Promise<T>;
+    evaluate<T>(fn: () => T | Promise<T>): Promise<T>;
+}
+export declare function canvasWorldToScreen(page: CanvasDiscoverPage, args: CanvasWorldToScreenArgs): Promise<CanvasWorldToScreenResult>;
+export declare function canvasScreenToWorld(page: CanvasDiscoverPage, args: CanvasScreenToWorldArgs): Promise<CanvasScreenToWorldResult>;
+export interface CanvasQueryArgs {
+    adapter: string;
+    op: string;
+    args?: Record<string, unknown>;
+}
+export interface CanvasQueryNoAdapterError {
+    ok: false;
+    error: string;
+    code: "no-adapter";
+    requestedAdapter: string;
+    requestedOp: string;
+}
+/** Build the structured `no-adapter` error returned when `canvas_query`
+ *  cannot find a plugin registered under the requested namespace. The
+ *  shape is kept stable so adopters can match on `code:"no-adapter"`. */
+export declare function noAdapterError(adapter: string, op: string): CanvasQueryNoAdapterError;

package/dist/page/canvas-transform.js

@@ -0,0 +1,150 @@
+// canvas_world_to_screen / canvas_screen_to_world — affine transform helpers
+// (explicit transform OR heuristic discovery of common app-side globals), and
+// canvas_query's structured no-adapter error. (See canvas.ts header.)
+const DISCOVERY_HEURISTIC_WARNING = "discovery probes are HEURISTIC — they match common app-side global shapes (Figma/Excalidraw `app.viewport.{zoom,center}`, Tldraw `app.{scale,offset}`, generic `app.transform.matrix`). Confirm the transform on a known landmark before relying on the result; for production, pass `transform` explicitly or install a canvas-app adapter plugin.";
+/** Pure math — apply an affine transform to a world point.
+ *  `screen = (world + pan) * scale + origin`. Documented this way (rather
+ *  than the matrix form) because that's the shape the discovery probes
+ *  return for the three named editors. */
+export function applyWorldToScreen(world, t) {
+    const ox = t.originX ?? 0;
+    const oy = t.originY ?? 0;
+    return {
+        x: (world.x + t.panX) * t.scale + ox,
+        y: (world.y + t.panY) * t.scale + oy,
+    };
+}
+/** Inverse: `world = (screen - origin) / scale - pan`. Round-trips with
+ *  `applyWorldToScreen` to within fp precision. */
+export function applyScreenToWorld(screen, t) {
+    if (t.scale === 0 || !Number.isFinite(t.scale)) {
+        return { x: NaN, y: NaN };
+    }
+    const ox = t.originX ?? 0;
+    const oy = t.originY ?? 0;
+    return {
+        x: (screen.x - ox) / t.scale - t.panX,
+        y: (screen.y - oy) / t.scale - t.panY,
+    };
+}
+/** Page-side discovery probe — REAL function literal. Returns the best
+ *  candidate transform found by walking known app-side global shapes,
+ *  plus an adapter hint naming which shape matched. Order matters:
+ *  Figma/Excalidraw shape is the most common; Tldraw's distinct shape
+ *  is tried next; finally the generic 3x3 matrix path. */
+export const PAGE_DISCOVER_TRANSFORM_FN = () => {
+    // Helper — pull a finite number out of `obj[path]` (dot-path); returns
+    // undefined if any segment misses or the leaf is non-finite.
+    function get(obj, path) {
+        const parts = path.split(".");
+        let cur = obj;
+        for (const p of parts) {
+            if (cur && typeof cur === "object" && p in cur) {
+                cur = cur[p];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return typeof cur === "number" && Number.isFinite(cur) ? cur : undefined;
+    }
+    const w = window;
+    // 1) Figma / Excalidraw shape — `app.viewport.zoom` + `app.viewport.center.{x,y}`.
+    const zoom = get(w.app, "viewport.zoom");
+    const cx = get(w.app, "viewport.center.x");
+    const cy = get(w.app, "viewport.center.y");
+    if (zoom !== undefined && cx !== undefined && cy !== undefined) {
+        return {
+            ok: true,
+            transform: { scale: zoom, panX: -cx, panY: -cy, originX: 0, originY: 0 },
+            adapterHint: "figma",
+        };
+    }
+    // 2) Tldraw-like shape — `app.scale` + `app.offset.{x,y}`.
+    const tlScale = get(w.app, "scale");
+    const tlOffsetX = get(w.app, "offset.x");
+    const tlOffsetY = get(w.app, "offset.y");
+    if (tlScale !== undefined && tlOffsetX !== undefined && tlOffsetY !== undefined) {
+        return {
+            ok: true,
+            transform: { scale: tlScale, panX: tlOffsetX, panY: tlOffsetY, originX: 0, originY: 0 },
+            adapterHint: "tldraw",
+        };
+    }
+    // 3) Generic matrix shape — `app.transform.matrix` as a 6-element
+    //    affine (a,b,c,d,e,f → [[a,c,e],[b,d,f],[0,0,1]]) or as a uniform
+    //    scale matrix.
+    const m = w.app?.transform;
+    const mat = m?.matrix;
+    if (Array.isArray(mat) &&
+        mat.length >= 6 &&
+        mat.every((v) => typeof v === "number" && Number.isFinite(v))) {
+        const a = mat[0];
+        const e = mat[4];
+        const f = mat[5];
+        return {
+            ok: true,
+            transform: { scale: a, panX: 0, panY: 0, originX: e, originY: f },
+            adapterHint: "generic",
+        };
+    }
+    return { ok: false };
+};
+export async function canvasWorldToScreen(page, args) {
+    if (args.transform) {
+        const p = applyWorldToScreen({ x: args.worldX, y: args.worldY }, args.transform);
+        return { ok: true, screenX: p.x, screenY: p.y };
+    }
+    const discovered = await page.evaluate(PAGE_DISCOVER_TRANSFORM_FN);
+    if (!discovered.ok || !discovered.transform) {
+        return {
+            ok: false,
+            error: "no transform discoverable — pass `transform` explicitly OR use a canvas-app adapter plugin",
+            code: "no-transform",
+        };
+    }
+    const p = applyWorldToScreen({ x: args.worldX, y: args.worldY }, discovered.transform);
+    return {
+        ok: true,
+        screenX: p.x,
+        screenY: p.y,
+        transformDiscovered: discovered.transform,
+        ...(discovered.adapterHint ? { adapterHint: discovered.adapterHint } : {}),
+        warnings: [DISCOVERY_HEURISTIC_WARNING],
+    };
+}
+export async function canvasScreenToWorld(page, args) {
+    if (args.transform) {
+        const p = applyScreenToWorld({ x: args.screenX, y: args.screenY }, args.transform);
+        return { ok: true, worldX: p.x, worldY: p.y };
+    }
+    const discovered = await page.evaluate(PAGE_DISCOVER_TRANSFORM_FN);
+    if (!discovered.ok || !discovered.transform) {
+        return {
+            ok: false,
+            error: "no transform discoverable — pass `transform` explicitly OR use a canvas-app adapter plugin",
+            code: "no-transform",
+        };
+    }
+    const p = applyScreenToWorld({ x: args.screenX, y: args.screenY }, discovered.transform);
+    return {
+        ok: true,
+        worldX: p.x,
+        worldY: p.y,
+        transformDiscovered: discovered.transform,
+        ...(discovered.adapterHint ? { adapterHint: discovered.adapterHint } : {}),
+        warnings: [DISCOVERY_HEURISTIC_WARNING],
+    };
+}
+/** Build the structured `no-adapter` error returned when `canvas_query`
+ *  cannot find a plugin registered under the requested namespace. The
+ *  shape is kept stable so adopters can match on `code:"no-adapter"`. */
+export function noAdapterError(adapter, op) {
+    return {
+        ok: false,
+        error: `no canvas adapter registered for ${adapter}; install @browxai/plugin-${adapter} or pass a registered adapter namespace`,
+        code: "no-adapter",
+        requestedAdapter: adapter,
+        requestedOp: op,
+    };
+}

package/dist/page/canvas.d.ts

@@ -0,0 +1,8 @@
+export type { CanvasFormat, CanvasCaptureArgs, CanvasCapturePngResult, CanvasCaptureRgbaResult, CanvasCaptureResult, PageCaptureRaw, CanvasCapturePage, } from "./canvas-capture.js";
+export { CANVAS_MAX_DIMENSION, PAGE_CAPTURE_FN, canvasCapture } from "./canvas-capture.js";
+export type { CanvasDiffRegion, CanvasDiffArgs, CanvasDiffResult } from "./canvas-diff.js";
+export { diffRgba, canvasDiff } from "./canvas-diff.js";
+export type { GestureChainStepKind, GestureChainStep, GestureChainArgs, GestureChainResult, ValidateGestureChainResult, GestureChainPage, } from "./canvas-gesture.js";
+export { GESTURE_CHAIN_MAX_STEPS, GESTURE_CHAIN_MIN_MOVE_MS, GESTURE_CHAIN_MAX_WAIT_MS, validateGestureChain, runGestureChain, } from "./canvas-gesture.js";
+export type { CanvasTransform, CanvasAdapterHint, CanvasWorldToScreenArgs, CanvasScreenToWorldArgs, CanvasWorldToScreenResult, CanvasScreenToWorldResult, CanvasDiscoverPage, CanvasQueryArgs, CanvasQueryNoAdapterError, } from "./canvas-transform.js";
+export { applyWorldToScreen, applyScreenToWorld, PAGE_DISCOVER_TRANSFORM_FN, canvasWorldToScreen, canvasScreenToWorld, noAdapterError, } from "./canvas-transform.js";

package/dist/page/canvas.js

@@ -0,0 +1,50 @@
+/// <reference lib="dom" />
+// Canvas-app automation primitives — capability `canvas`.
+//
+// The substrate. Five MCP tools + a pure-math diff, split across cohesive
+// sibling modules and re-exported here so `../page/canvas.js` stays the single
+// public barrel (callers and tests import unchanged):
+//
+//   - `canvas_capture`           — framebuffer / 2D ImageData / PNG bytes
+//                                  of a `<canvas>` element. App-agnostic.
+//                                  → ./canvas-capture.js
+//   - `canvas_diff`              — pixel/region delta between two RGBA
+//                                  captures. Pure function over bytes;
+//                                  no page contact. → ./canvas-diff.js
+//   - `gesture_chain`            — multi-step pointer program (down /
+//                                  move / wheel / wait / up). Custom
+//                                  paint strokes, lasso paths, gestures
+//                                  the canned `drag` / `gesture_swipe`
+//                                  family doesn't cover. → ./canvas-gesture.js
+//   - `canvas_world_to_screen` + `canvas_screen_to_world` —
+//                                  affine transform helpers, two modes:
+//                                  explicit (caller passes transform)
+//                                  or discovery (probe common app-side
+//                                  globals — Figma / Tldraw / Excalidraw
+//                                  shapes; documented as heuristic).
+//                                  → ./canvas-transform.js
+//   - `canvas_query`             — dispatcher to a canvas-app adapter
+//                                  plugin. The router lives in
+//                                  server.ts (it has the plugin handler
+//                                  map); only the structured no-adapter
+//                                  error shape lives here. → ./canvas-transform.js
+//
+// Design principle (project-wide, see CLAUDE.md
+// `feedback_design_for_problem_class`): the primitives are app-agnostic.
+// Discovery probes common globals — those are HEURISTIC; the structured
+// failure path tells the caller to pass `transform` explicitly OR install
+// a canvas-app adapter plugin.
+//
+// BYO-vision pattern (docs only this cycle, see docs/tool-reference.md
+// "Canvas-app automation — BYO vision pattern"): browxai does NOT bundle
+// OCR or a hosted vision API. `canvas_capture` is the pixel source;
+// composition with the host agent's own multimodal vision is the loop.
+//
+// Bounded:
+//   - canvas_capture refuses canvases larger than 16384×16384 pixels.
+//   - gesture_chain caps at 200 steps, floors `move` step delays at 5 ms,
+//     bounds `wait` steps at 5000 ms.
+export { CANVAS_MAX_DIMENSION, PAGE_CAPTURE_FN, canvasCapture } from "./canvas-capture.js";
+export { diffRgba, canvasDiff } from "./canvas-diff.js";
+export { GESTURE_CHAIN_MAX_STEPS, GESTURE_CHAIN_MIN_MOVE_MS, GESTURE_CHAIN_MAX_WAIT_MS, validateGestureChain, runGestureChain, } from "./canvas-gesture.js";
+export { applyWorldToScreen, applyScreenToWorld, PAGE_DISCOVER_TRANSFORM_FN, canvasWorldToScreen, canvasScreenToWorld, noAdapterError, } from "./canvas-transform.js";

package/dist/page/capture-substrate.d.ts

@@ -0,0 +1,111 @@
+import type { Locator, Page } from "playwright-core";
+import type { RefRegistry } from "./refs.js";
+import type { SafariSessionHandle } from "../engine/index.js";
+import type { ScreenshotSaveResult } from "./screenshot-save.js";
+/** Normalised screenshot request — the handler's already-validated args, engine-
+ *  blind. `resolveTarget`, when present, marks an element-scoped capture and is the
+ *  DEFERRED `asTarget` resolution: an adapter calls it only after its own refusals
+ *  pass, so a malformed target (multi-target / unbound `named`) surfaces as the
+ *  engine/`fullPage` refusal it sat behind pre-seam, not as a preempting throw. Its
+ *  absence means a viewport (or `fullPage`) capture. `path`, when set, swaps the
+ *  inline image for a workspace-rooted disk write (the handler has already enforced
+ *  the `file-io` capability). */
+export interface ScreenshotRequest {
+    format: "png" | "jpeg";
+    quality?: number;
+    scale?: "css" | "device";
+    fullPage: boolean;
+    describe: boolean;
+    resolveTarget?: () => {
+        ref: string;
+    } | {
+        selector: string;
+        contextRef?: string;
+    };
+    path?: string;
+}
+/** Inline-image outcome: the encoded bytes + mime, an optional `describe`
+ *  caption, and an optional page-text source the handler's secrets sweep reads
+ *  (only the Playwright path can offer it — Safari has no Page to evaluate, the
+ *  same as before the seam, where the Safari branch returned before the sweep). */
+export interface CaptureImage {
+    kind: "image";
+    data: string;
+    mimeType: string;
+    caption?: string;
+    pageText?: () => Promise<string>;
+}
+/** Disk-write outcome (`path` mode): the `screenshot-save` envelope plus the
+ *  optional caption the handler folds into the JSON body. */
+export interface CaptureSaved {
+    kind: "saved";
+    result: ScreenshotSaveResult;
+    caption?: string;
+}
+/** Disk-write FAILURE (`path` mode): the workspace path escaped the root, or the
+ *  write itself failed. Carries the bare message the handler renders as the same
+ *  `{ ok:false, error, tokensEstimate }` envelope the deleted try/catch produced —
+ *  a throw here was a returned JSON envelope, never a crashed handler. */
+export interface CaptureSaveError {
+    kind: "save-error";
+    error: string;
+}
+/** Structured refusal — an engine that cannot honour the request (Safari for
+ *  element-scoped / `path` / jpeg), or a request the capability itself rejects
+ *  (`fullPage` + a target). The handler renders `error`/`hint` as the same JSON
+ *  envelope the deleted branches produced. */
+export interface CaptureRefusal {
+    kind: "refusal";
+    error: string;
+    hint?: string;
+}
+export type CaptureResult = CaptureImage | CaptureSaved | CaptureSaveError | CaptureRefusal;
+/** The capture capability port. One instance wraps one session's engine handle;
+ *  the methods carry no engine type, so the handler above this seam is
+ *  engine-blind. Mirrors the ActionSubstrate / SnapshotSubstrate shape. */
+export interface CaptureSubstrate {
+    readonly engine: string;
+    screenshot(req: ScreenshotRequest): Promise<CaptureResult>;
+}
+/** Playwright engines — the existing screenshot logic, verbatim. The `page` and
+ *  `describe`/`save` collaborators are injected so this adapter stays free of the
+ *  server's handler closures (the caption + disk-write helpers live in server.ts
+ *  and are passed through unchanged). No behaviour change. */
+export declare class PlaywrightCaptureSubstrate implements CaptureSubstrate {
+    private readonly page;
+    private readonly refs;
+    private readonly deps;
+    readonly engine: string;
+    constructor(page: () => Page, refs: RefRegistry, deps: {
+        describeTarget: (loc: Locator, refs: RefRegistry, target: {
+            ref: string;
+        } | {
+            selector: string;
+        } | {
+            coords: {
+                x: number;
+                y: number;
+            };
+        }) => Promise<string>;
+        save: (buf: Buffer, args: {
+            path: string;
+            format: "png" | "jpeg";
+            fullPage: boolean;
+        }) => ScreenshotSaveResult;
+    }, engine?: string);
+    /** Capture the screenshot bytes + caption for either the element-scoped target
+     *  (deferred `asTarget` resolution) or the whole page. */
+    private captureBytes;
+    screenshot(req: ScreenshotRequest): Promise<CaptureResult>;
+}
+/** Safari — the WebDriver-Classic capture path. safaridriver captures the whole
+ *  document as PNG; the element-scoped / `path` variants need a Playwright Page
+ *  Safari lacks, so they refuse cleanly here (the gating is in the adapter, not
+ *  the handler). The `format`/`scale`/`fullPage`/`describe` args are inert as they
+ *  were before the seam — the WebDriver client always returns a full-document PNG. */
+export declare class SafariCaptureSubstrate implements CaptureSubstrate {
+    private readonly handle;
+    readonly engine = "safari";
+    constructor(handle: SafariSessionHandle);
+    screenshot(req: ScreenshotRequest): Promise<CaptureResult>;
+}

package/dist/page/capture-substrate.js

@@ -0,0 +1,139 @@
+// The CaptureSubstrate interface — the engine-agnostic seam beneath the capture
+// tools (screenshot today; pdf / video later). It is the capture side of the
+// engine-decoupling seam: the `screenshot` handler asks a substrate to capture and gets back a
+// universal `CaptureResult`; an engine-specific implementation does the work. The
+// handler never names Playwright, safaridriver, or an engine — it calls
+// `captureFor(e).screenshot(args)`, the same shape as `actionsFor(e).click(args)`
+// / `snapshotSubstrateFor(e.session).compose(...)`.
+//
+// Dependency direction (architecture doctrine §1): tool handler → CaptureSubstrate
+// (this interface) → implementation → Playwright | safaridriver. Two impls today:
+//   - PlaywrightCaptureSubstrate (chromium / firefox / webkit / android): wraps the
+//     existing screenshot logic verbatim (viewport / fullPage / element-scoped via
+//     locator, jpeg + quality + scale, the `path` disk-write envelope, the
+//     `describe` caption) — byte-identical to the pre-seam handler, so the four
+//     engines' keystones stay green unchanged.
+//   - SafariCaptureSubstrate (safari): wraps `webDriver.screenshot` (full-document
+//     PNG; safaridriver has no Playwright Page). The element-scoped / `path` / jpeg
+//     variants refuse cleanly IN THE ADAPTER as they did in the handler's deleted
+//     `if (safariShotHandle)` branch — so the gating lives here, not as an engine
+//     check in the handler.
+/** Build the Locator for an element-scoped capture. Lazily imported so the
+ *  page-layer locator core is pulled only when a target is actually present —
+ *  the handler did the same `await import("./locator.js")` inline. */
+async function locatorForTarget(page, refs, target) {
+    const { locatorFor } = await import("./locator.js");
+    return locatorFor(page, refs, target);
+}
+/** Playwright engines — the existing screenshot logic, verbatim. The `page` and
+ *  `describe`/`save` collaborators are injected so this adapter stays free of the
+ *  server's handler closures (the caption + disk-write helpers live in server.ts
+ *  and are passed through unchanged). No behaviour change. */
+export class PlaywrightCaptureSubstrate {
+    page;
+    refs;
+    deps;
+    engine;
+    constructor(page, refs, deps, engine = "chromium") {
+        this.page = page;
+        this.refs = refs;
+        this.deps = deps;
+        this.engine = engine;
+    }
+    /** Capture the screenshot bytes + caption for either the element-scoped target
+     *  (deferred `asTarget` resolution) or the whole page. */
+    async captureBytes(page, req, fmt) {
+        if (req.resolveTarget) {
+            // Deferred: only now does the `asTarget` chokepoint run. A malformed target
+            // throws here — past the `fullPage` refusal, matching the pre-seam handler.
+            const target = req.resolveTarget();
+            const loc = await locatorForTarget(page, this.refs, target);
+            // Locator.screenshot doesn't accept `scale`; pass type/quality only there.
+            const locOpts = { type: fmt };
+            if (fmt === "jpeg")
+                locOpts.quality = req.quality ?? 80;
+            const buf = await loc.screenshot(locOpts);
+            const caption = req.describe ? await this.deps.describeTarget(loc, this.refs, target) : "";
+            return { buf, caption };
+        }
+        const opts = {
+            type: fmt,
+        };
+        if (fmt === "jpeg")
+            opts.quality = req.quality ?? 80;
+        if (req.scale)
+            opts.scale = req.scale;
+        const buf = await page.screenshot({ fullPage: req.fullPage, ...opts });
+        const caption = req.describe ? `${req.fullPage ? "fullPage" : "viewport"} (${page.url()})` : "";
+        return { buf, caption };
+    }
+    async screenshot(req) {
+        const page = this.page();
+        const fmt = req.format;
+        const mimeType = fmt === "jpeg" ? "image/jpeg" : "image/png";
+        const fullPage = req.fullPage;
+        if (fullPage && req.resolveTarget) {
+            return {
+                kind: "refusal",
+                error: "screenshot: `fullPage:true` is mutually exclusive with `ref`/`selector`/`named` — element-scoped captures are already bounded by the element's box",
+                hint: "Drop `fullPage` for an element capture, or drop the target for a whole-document capture.",
+            };
+        }
+        const { buf, caption } = await this.captureBytes(page, req, fmt);
+        // `path` mode: write bytes to a workspace-rooted file and return the save
+        // envelope instead of inline base64. The `file-io` capability check already
+        // ran (handler gate); a path escaping the workspace or a failed write throws
+        // out of `screenshotSave` and becomes a structured `save-error` here — never
+        // a crashed handler, matching the deleted try/catch.
+        if (req.path !== undefined) {
+            try {
+                const result = this.deps.save(buf, { path: req.path, format: fmt, fullPage });
+                return { kind: "saved", result, caption: caption || undefined };
+            }
+            catch (err) {
+                return { kind: "save-error", error: err instanceof Error ? err.message : String(err) };
+            }
+        }
+        return {
+            kind: "image",
+            data: buf.toString("base64"),
+            mimeType,
+            caption: caption || undefined,
+            // The secrets sweep reads the document's visible text (innerText falls
+            // back to "" on failure — the page may be navigating). Bounded so a giant
+            // page doesn't make the scan O(n^2-pathological).
+            pageText: () => page
+                .evaluate(() => {
+                const w = globalThis;
+                return (w.document?.body?.innerText ?? "").slice(0, 200_000);
+            })
+                .catch(() => ""),
+        };
+    }
+}
+/** Safari — the WebDriver-Classic capture path. safaridriver captures the whole
+ *  document as PNG; the element-scoped / `path` variants need a Playwright Page
+ *  Safari lacks, so they refuse cleanly here (the gating is in the adapter, not
+ *  the handler). The `format`/`scale`/`fullPage`/`describe` args are inert as they
+ *  were before the seam — the WebDriver client always returns a full-document PNG. */
+export class SafariCaptureSubstrate {
+    handle;
+    engine = "safari";
+    constructor(handle) {
+        this.handle = handle;
+    }
+    async screenshot(req) {
+        // Refuse on the raw element-scoped / `path` signals WITHOUT invoking the
+        // deferred `asTarget` resolver — a malformed target must surface as this
+        // engine refusal, exactly as the pre-seam Safari branch (which never reached
+        // `asTarget`) returned it.
+        if (req.resolveTarget || req.path !== undefined) {
+            return {
+                kind: "refusal",
+                error: "the Safari engine supports only the default inline PNG screenshot — element-scoped (`ref`/`selector`/`named`) and `path` captures need a chromium/firefox/webkit session.",
+            };
+        }
+        const data = await this.handle.webDriver.screenshot(this.handle.sessionId);
+        return { kind: "image", data, mimeType: "image/png" };
+    }
+}

package/dist/page/clipboard.d.ts

@@ -0,0 +1,25 @@
+export type ClipOp = "copy" | "cut";
+export interface ClipEntry {
+    text: string;
+    op: ClipOp;
+    ts: number;
+}
+/** One per SessionEntry. In-memory; nothing persisted. */
+export declare class ClipboardBuffer {
+    private entry;
+    set(text: string, op: ClipOp): void;
+    get(): ClipEntry | null;
+}
+/**
+ * Best-effort, zero-dependency, **write-only** OS clipboard set. Fixed argv
+ * (no shell, content via stdin — no injection surface). Called ONLY as part
+ * of an explicit copy/cut/paste command. Degrades gracefully when the
+ * platform tool is absent (e.g. CI without `xclip`): the per-session buffer
+ * still works for same-session paste reasoning; the result just notes
+ * `osSync:false`.
+ */
+export declare function osClipboardWrite(text: string): Promise<{
+    ok: boolean;
+    tool: string;
+    error?: string;
+}>;

package/dist/page/clipboard.js

@@ -0,0 +1,50 @@
+// Per-session clipboard model (capability `clipboard`, off by default).
+//
+// The OS clipboard is a single shared resource; concurrent browxai sessions
+// must not clobber each other through it. So each session owns its OWN
+// clipboard buffer (the source of truth for what *this* session copied/cut),
+// and the real OS clipboard is touched **only transactionally, at the exact
+// moment of an explicit copy / cut / paste shortcut command** — never polled,
+// never synced in the background, and left exactly as the user left it
+// between commands. We never *read* the OS clipboard into a session (that
+// would import another session's or the human's content — clipboard bleed).
+import { spawn } from "node:child_process";
+/** One per SessionEntry. In-memory; nothing persisted. */
+export class ClipboardBuffer {
+    entry = null;
+    set(text, op) {
+        this.entry = { text, op, ts: Date.now() };
+    }
+    get() {
+        return this.entry;
+    }
+}
+/**
+ * Best-effort, zero-dependency, **write-only** OS clipboard set. Fixed argv
+ * (no shell, content via stdin — no injection surface). Called ONLY as part
+ * of an explicit copy/cut/paste command. Degrades gracefully when the
+ * platform tool is absent (e.g. CI without `xclip`): the per-session buffer
+ * still works for same-session paste reasoning; the result just notes
+ * `osSync:false`.
+ */
+export async function osClipboardWrite(text) {
+    const plat = process.platform;
+    const argv = plat === "darwin"
+        ? ["pbcopy"]
+        : plat === "win32"
+            ? ["clip"]
+            : ["xclip", "-selection", "clipboard"];
+    return new Promise((resolve) => {
+        try {
+            const cp = spawn(argv[0], argv.slice(1), { stdio: ["pipe", "ignore", "ignore"] });
+            cp.on("error", (e) => resolve({ ok: false, tool: argv[0], error: e.message }));
+            cp.on("close", (code) => resolve(code === 0
+                ? { ok: true, tool: argv[0] }
+                : { ok: false, tool: argv[0], error: `exit ${code}` }));
+            cp.stdin.end(text);
+        }
+        catch (e) {
+            resolve({ ok: false, tool: argv[0], error: e instanceof Error ? e.message : String(e) });
+        }
+    });
+}

package/dist/page/clock.d.ts

@@ -0,0 +1,36 @@
+import type { CDPSession, Page } from "playwright-core";
+export type ClockMode = "freeze" | "advance" | "release";
+export interface ClockInput {
+    mode: ClockMode;
+    /** Absolute ISO-8601 instant. `freeze` → pin time there. `advance` → jump to it. */
+    atIso?: string;
+    /** `advance` only — relative jump in ms (mutually exclusive with `atIso`). */
+    byMs?: number;
+}
+/** Cached state used by the re-apply hook. `release` is represented by `undefined`. */
+export interface ClockState {
+    /** Effective virtual-time anchor, epoch ms. Mirrors what the page now sees. */
+    nowMs: number;
+    /** Whether the policy is currently a pause (true) or actively advancing (false). */
+    paused: boolean;
+}
+/** Per-session clock controller. One per SessionEntry. */
+export declare class ClockRegistry {
+    private state;
+    /** Re-apply hook installed once per page on first use. */
+    private reattachInstalled;
+    /** Apply the requested mode and remember it. Returns the normalized state. */
+    apply(cdp: CDPSession, page: Page, input: ClockInput): Promise<{
+        state: ClockState | undefined;
+        mode: ClockMode;
+        appliedAtIso: string | null;
+    }>;
+    /** Reset on close/teardown if a non-default policy is active. */
+    resetAll(cdp: CDPSession): Promise<void>;
+    /** Test introspection. */
+    current(): ClockState | undefined;
+    private installReattach;
+    private sendPauseAt;
+    private sendAdvance;
+    private sendRelease;
+}