browxai 0.7.0

package/dist/page/safari-actions.js

@@ -0,0 +1,144 @@
+// Safari action helpers. Safari has no Playwright Page, so the Playwright action
+// core (actions.ts → runInActionWindow → ctx.page) cannot run — `ctxFor(e)` throws
+// at context construction. The curated subset that works on Safari is routed here
+// instead, driving the Safari-native WebDriver Classic client (element find →
+// click / clear / sendKeys, navigation) and returning the same `ActionResult`
+// shape so the tool surface stays engine-blind.
+//
+// A ref or a css `selector` resolves to a WebDriver element by CSS: a ref is
+// turned into the most stable selector its snapshot locator carries (a
+// `[data-testid=…]`-style attribute when present, else the structural css path).
+// `coords` and role/name-only refs are not addressable this way and are refused.
+// The action envelope's structure / console / network deltas are NOT captured on
+// Safari (it has no protocol-level taps) — surfaced as an honest warning, never
+// fabricated.
+const EMPTY_NETWORK = { summary: { total: 0, byType: {}, failed: 0 } };
+const ENVELOPE_NOTE = "Safari is driven over WebDriver: the action envelope's structure / console / network deltas are " +
+    "not captured on the Safari engine. Read page state with `snapshot` after an action.";
+/** W3C WebDriver key codes for the named keys `press` accepts. A bare single
+ *  character is sent as-is; anything else falls back to the literal string. */
+const WEBDRIVER_KEYS = {
+    Enter: "\uE007",
+    Tab: "\uE004",
+    Escape: "\uE00C",
+    Backspace: "\uE003",
+    Delete: "\uE017",
+    Space: "\uE00D",
+    ArrowUp: "\uE013",
+    ArrowDown: "\uE015",
+    ArrowLeft: "\uE012",
+    ArrowRight: "\uE014",
+};
+function descriptorFor(type, target) {
+    if (target.ref)
+        return { type, ref: target.ref };
+    if (target.selector)
+        return { type, selector: target.selector };
+    return { type };
+}
+function result(action, ok, extra = {}) {
+    return {
+        ok,
+        action,
+        navigation: { changed: false, from: "", to: "", kind: null },
+        structure: { appeared: [], removed: [], newTabs: [] },
+        console: { errors: [], warnings: 0 },
+        pageErrors: [],
+        network: EMPTY_NETWORK,
+        tokensEstimate: 0,
+        warnings: extra.warnings ?? [ENVELOPE_NOTE],
+        ...(extra.element ? { element: extra.element } : {}),
+        ...(extra.error ? { error: extra.error } : {}),
+    };
+}
+/** Resolve an action target to a CSS selector the WebDriver `findElement` can use,
+ *  or null when the target is not addressable on Safari (coords, or a ref whose
+ *  snapshot locator carries neither a test attribute nor a css path). */
+function selectorForTarget(refs, target) {
+    if (target.selector)
+        return target.selector;
+    if (!target.ref)
+        return null;
+    const loc = refs.locatorOf(target.ref);
+    if (!loc)
+        return null;
+    if (loc.testId && loc.testIdAttr)
+        return `[${loc.testIdAttr}="${loc.testId.replace(/(["\\])/g, "\\$1")}"]`;
+    return loc.cssPath ?? null;
+}
+function unaddressable(action) {
+    return result(action, false, {
+        error: "this target is not addressable on the Safari engine — pass a `ref` (from snapshot/find) whose " +
+            "element carries a test attribute or css path, or a css `selector`. `coords` are not supported.",
+    });
+}
+/** A clean refusal for an action family outside Safari's curated subset (hover,
+ *  select, scroll, …). Keeps the gating in the adapter rather than the handler,
+ *  so the tool surface stays engine-blind. */
+export function safariUnsupportedAction(type) {
+    return result({ type }, false, {
+        error: `\`${type}\` is not supported on the Safari engine — the curated subset is navigate / click / ` +
+            `fill / press / snapshot / find / screenshot / cookies. Use a chromium, firefox, or webkit ` +
+            `session for the rest.`,
+    });
+}
+async function resolveElement(handle, selector) {
+    return handle.webDriver.findElement(handle.sessionId, "css selector", selector);
+}
+export async function safariNavigate(handle, url) {
+    const wd = handle.webDriver;
+    const from = await wd.currentUrl(handle.sessionId).catch(() => "");
+    await wd.navigate(handle.sessionId, url);
+    const to = await wd.currentUrl(handle.sessionId).catch(() => url);
+    const changed = from !== to;
+    return {
+        ok: true,
+        action: { type: "navigate", url },
+        navigation: { changed, from, to, kind: changed ? "full_load" : null },
+        structure: { appeared: [], removed: [], newTabs: [] },
+        console: { errors: [], warnings: 0 },
+        pageErrors: [],
+        network: EMPTY_NETWORK,
+        tokensEstimate: 0,
+        warnings: [ENVELOPE_NOTE],
+    };
+}
+export async function safariClick(handle, refs, target) {
+    const descriptor = descriptorFor("click", target);
+    const selector = selectorForTarget(refs, target);
+    if (!selector)
+        return unaddressable(descriptor);
+    const el = await resolveElement(handle, selector);
+    if (!el)
+        return result(descriptor, false, { error: `no element matches "${selector}"` });
+    await handle.webDriver.elementClick(handle.sessionId, el);
+    return result(descriptor, true, { element: { ref: target.ref, stillAttached: true } });
+}
+export async function safariFill(handle, refs, target, value) {
+    const descriptor = { ...descriptorFor("fill", target), value };
+    const selector = selectorForTarget(refs, target);
+    if (!selector)
+        return unaddressable(descriptor);
+    const el = await resolveElement(handle, selector);
+    if (!el)
+        return result(descriptor, false, { error: `no element matches "${selector}"` });
+    await handle.webDriver.elementClear(handle.sessionId, el);
+    await handle.webDriver.elementValue(handle.sessionId, el, value);
+    const landed = await handle.webDriver
+        .elementProperty(handle.sessionId, el, "value")
+        .catch(() => null);
+    return result(descriptor, true, {
+        element: { ref: target.ref, stillAttached: true, value: landed ?? value },
+    });
+}
+export async function safariPress(handle, refs, target, key) {
+    const descriptor = { ...descriptorFor("press", target), value: key };
+    const selector = selectorForTarget(refs, target);
+    if (!selector)
+        return unaddressable(descriptor);
+    const el = await resolveElement(handle, selector);
+    if (!el)
+        return result(descriptor, false, { error: `no element matches "${selector}"` });
+    await handle.webDriver.elementValue(handle.sessionId, el, WEBDRIVER_KEYS[key] ?? key);
+    return result(descriptor, true, { element: { ref: target.ref, stillAttached: true } });
+}

package/dist/page/sample.d.ts

@@ -0,0 +1,64 @@
+import type { Page } from "playwright-core";
+import { type ActionTarget } from "./locator.js";
+import type { RefRegistry } from "./refs.js";
+export declare const ELEMENT_METRICS: readonly ["scrollTop", "scrollLeft", "scrollHeight", "scrollWidth", "clientWidth", "clientHeight", "bboxX", "bboxY", "bboxWidth", "bboxHeight"];
+export type Metric = (typeof ELEMENT_METRICS)[number];
+/** Above this collected-point count, an unset `summary` auto-omits the full
+ *  series (a raf window of a few seconds is hundreds of points; the agent
+ *  almost always wants only the reduced signal, and the raw series balloons
+ *  the tool-result token cost). Explicit `summary:false` opts back in. */
+export declare const AUTO_SUMMARY_THRESHOLD = 300;
+/** Tri-state series-omission policy (pure, unit-tested):
+ *   - `summary === true`  → always omit the series (caller asked for reduced).
+ *   - `summary === false` → always include it (caller opted into the raw set).
+ *   - `summary` unset     → auto-omit only when the series is large. */
+export declare function shouldOmitSeries(summary: boolean | undefined, count: number): boolean;
+export interface SampleArgs {
+    target?: ActionTarget;
+    metric: Metric;
+    durationMs: number;
+    everyFrame?: boolean;
+    intervalMs?: number;
+    /** Series-omission control (the `summary` is *always* returned regardless).
+     *  `true` → omit the full `series`; `false` → always include it; unset →
+     *  auto-omit only for large windows (> AUTO_SUMMARY_THRESHOLD points), with
+     *  `autoSummarised: true` on the result. Pure server-side reduction of the
+     *  already-collected fixed-metric series — no agent JS, no eval surface. */
+    summary?: boolean;
+}
+export interface SampleSummary {
+    count: number;
+    min: number;
+    max: number;
+    first: number;
+    last: number;
+    /** Distinct sampled values (catches "did it move at all?"). */
+    distinctCount: number;
+    /** tMs of the first sample whose value differed from `first`; null if flat. */
+    firstChangeTMs: number | null;
+}
+export interface SampleResult {
+    metric: Metric;
+    scope: "element" | "window";
+    durationMs: number;
+    mode: "raf" | "interval";
+    intervalMs?: number;
+    count: number;
+    /** Present unless `summary` was requested. */
+    series?: Array<{
+        tMs: number;
+        value: number;
+    }>;
+    /** Always present (cheap) — the reduced signal. */
+    summary?: SampleSummary;
+    /** true when the series was dropped by the auto-large-window policy (caller
+     *  didn't set `summary`). Re-request with `summary:false` for the raw set. */
+    autoSummarised?: boolean;
+    truncated?: boolean;
+}
+/** Pure reduction of a collected series. Exported for unit tests. */
+export declare function summariseSeries(series: Array<{
+    tMs: number;
+    value: number;
+}>): SampleSummary;
+export declare function sampleMetric(page: Page, refs: RefRegistry, args: SampleArgs): Promise<SampleResult>;

package/dist/page/sample.js

@@ -0,0 +1,216 @@
+// bounded frame-aligned metric sampler.
+//
+// Jank / CLS / scroll-drift QA needs "sample this DOM metric every animation
+// frame for N ms and return the series". The metric is a **fixed enum** — the
+// agent supplies NO JavaScript (that would re-open the loophole closes;
+// arbitrary JS stays `eval_js`, gated behind the `eval` capability). browxai
+// supplies the fixed in-page rAF / interval loop.
+import { locatorFor } from "./locator.js";
+export const ELEMENT_METRICS = [
+    "scrollTop",
+    "scrollLeft",
+    "scrollHeight",
+    "scrollWidth",
+    "clientWidth",
+    "clientHeight",
+    "bboxX",
+    "bboxY",
+    "bboxWidth",
+    "bboxHeight",
+];
+const BBOX_METRICS = new Set(["bboxX", "bboxY", "bboxWidth", "bboxHeight"]);
+const MAX_DURATION_MS = 30_000;
+const MAX_SERIES = 2000;
+/** Above this collected-point count, an unset `summary` auto-omits the full
+ *  series (a raf window of a few seconds is hundreds of points; the agent
+ *  almost always wants only the reduced signal, and the raw series balloons
+ *  the tool-result token cost). Explicit `summary:false` opts back in. */
+export const AUTO_SUMMARY_THRESHOLD = 300;
+/** Tri-state series-omission policy (pure, unit-tested):
+ *   - `summary === true`  → always omit the series (caller asked for reduced).
+ *   - `summary === false` → always include it (caller opted into the raw set).
+ *   - `summary` unset     → auto-omit only when the series is large. */
+export function shouldOmitSeries(summary, count) {
+    if (summary === true)
+        return true;
+    if (summary === false)
+        return false;
+    return count > AUTO_SUMMARY_THRESHOLD;
+}
+/** Pure reduction of a collected series. Exported for unit tests. */
+export function summariseSeries(series) {
+    if (series.length === 0) {
+        return {
+            count: 0,
+            min: NaN,
+            max: NaN,
+            first: NaN,
+            last: NaN,
+            distinctCount: 0,
+            firstChangeTMs: null,
+        };
+    }
+    const first = series[0].value;
+    let min = first;
+    let max = first;
+    let firstChangeTMs = null;
+    const distinct = new Set();
+    for (const p of series) {
+        if (p.value < min)
+            min = p.value;
+        if (p.value > max)
+            max = p.value;
+        distinct.add(p.value);
+        if (firstChangeTMs === null && p.value !== first)
+            firstChangeTMs = p.tMs;
+    }
+    return {
+        count: series.length,
+        min,
+        max,
+        first,
+        last: series[series.length - 1].value,
+        distinctCount: distinct.size,
+        firstChangeTMs,
+    };
+}
+// Both samplers are self-contained (no closure / outer refs) so Playwright can
+// stringify and run them in-page. They differ only in arg shape:
+//   loc.evaluate(fn, arg)  → fn(element, arg)
+//   page.evaluate(fn, arg) → fn(arg)
+// The metric/loop logic is intentionally duplicated rather than shared via a
+// closure (which wouldn't survive serialization).
+/** Element sampler — runs as `loc.evaluate(elementSampler, params)`. */
+function elementSampler(el, p) {
+    const read = () => {
+        switch (p.metric) {
+            case "scrollTop":
+                return el.scrollTop;
+            case "scrollLeft":
+                return el.scrollLeft;
+            case "scrollHeight":
+                return el.scrollHeight;
+            case "scrollWidth":
+                return el.scrollWidth;
+            case "clientWidth":
+                return el.clientWidth;
+            case "clientHeight":
+                return el.clientHeight;
+            default: {
+                const r = el.getBoundingClientRect();
+                return p.metric === "bboxX"
+                    ? r.x
+                    : p.metric === "bboxY"
+                        ? r.y
+                        : p.metric === "bboxWidth"
+                            ? r.width
+                            : r.height;
+            }
+        }
+    };
+    return new Promise((resolve) => {
+        const series = [];
+        const clock = () => globalThis.performance && globalThis.performance.now
+            ? globalThis.performance.now()
+            : Date.now();
+        const t0 = clock();
+        const tick = () => {
+            if (series.length < p.maxSeries)
+                series.push({ tMs: Math.round(clock() - t0), value: read() });
+            if (clock() - t0 >= p.durationMs || series.length >= p.maxSeries) {
+                resolve(series);
+                return;
+            }
+            if (p.everyFrame && globalThis.requestAnimationFrame)
+                globalThis.requestAnimationFrame(tick);
+            else
+                globalThis.setTimeout(tick, p.intervalMs);
+        };
+        tick();
+    });
+}
+/** Window/document sampler — runs as `page.evaluate(windowSampler, params)`. */
+function windowSampler(p) {
+    const read = () => {
+        const s = globalThis.document.scrollingElement || globalThis.document.documentElement;
+        switch (p.metric) {
+            case "scrollTop":
+                return globalThis.scrollY ?? s.scrollTop ?? 0;
+            case "scrollLeft":
+                return globalThis.scrollX ?? s.scrollLeft ?? 0;
+            case "scrollHeight":
+                return s.scrollHeight;
+            case "scrollWidth":
+                return s.scrollWidth;
+            case "clientWidth":
+                return s.clientWidth;
+            case "clientHeight":
+                return s.clientHeight;
+            default:
+                return NaN; // bbox* rejected before we get here
+        }
+    };
+    return new Promise((resolve) => {
+        const series = [];
+        const clock = () => globalThis.performance && globalThis.performance.now
+            ? globalThis.performance.now()
+            : Date.now();
+        const t0 = clock();
+        const tick = () => {
+            if (series.length < p.maxSeries)
+                series.push({ tMs: Math.round(clock() - t0), value: read() });
+            if (clock() - t0 >= p.durationMs || series.length >= p.maxSeries) {
+                resolve(series);
+                return;
+            }
+            if (p.everyFrame && globalThis.requestAnimationFrame)
+                globalThis.requestAnimationFrame(tick);
+            else
+                globalThis.setTimeout(tick, p.intervalMs);
+        };
+        tick();
+    });
+}
+export async function sampleMetric(page, refs, args) {
+    const durationMs = Math.min(Math.max(args.durationMs, 1), MAX_DURATION_MS);
+    const everyFrame = args.everyFrame ?? false;
+    const intervalMs = Math.max(args.intervalMs ?? 100, 16);
+    const scope = args.target ? "element" : "window";
+    if (!args.target && BBOX_METRICS.has(args.metric)) {
+        throw new Error(`sample: metric "${args.metric}" needs a target element (bbox* is meaningless for the window)`);
+    }
+    const params = { metric: args.metric, durationMs, everyFrame, intervalMs, maxSeries: MAX_SERIES };
+    let series;
+    if (args.target) {
+        let loc;
+        try {
+            loc = locatorFor(page, refs, args.target);
+        }
+        catch (e) {
+            throw new Error(`sample: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        series = await loc.evaluate(elementSampler, params);
+    }
+    else {
+        series = await page.evaluate(windowSampler, params);
+    }
+    // `summary` is always cheap to compute and included. The full `series` is
+    // omitted when the caller asked for `summary:true` OR (caller unset) the
+    // window is large — long high-rate windows serialise huge and the agent
+    // usually just needs the signal: did it move, bounds, when it first changed.
+    const summary = summariseSeries(series);
+    const omitSeries = shouldOmitSeries(args.summary, series.length);
+    const autoSummarised = omitSeries && args.summary === undefined;
+    return {
+        metric: args.metric,
+        scope,
+        durationMs,
+        mode: everyFrame ? "raf" : "interval",
+        ...(everyFrame ? {} : { intervalMs }),
+        count: series.length,
+        ...(omitSeries ? {} : { series }),
+        summary,
+        ...(autoSummarised ? { autoSummarised: true } : {}),
+        ...(series.length >= MAX_SERIES ? { truncated: true } : {}),
+    };
+}

package/dist/page/screenshot-on.d.ts

@@ -0,0 +1,51 @@
+export declare const TRIGGERS: readonly ["navigation", "console-error", "network-mutation", "dialog"];
+export type Trigger = (typeof TRIGGERS)[number];
+/** Max captures per `screenshot_on` window. The window is already bounded by
+ *  `durationMs`; this cap prevents an event-storm trigger (e.g. console-error
+ *  fired every animation frame) from filling disk with thousands of frames in
+ *  a multi-second window. Surfaced as a `warnings[]` entry when reached. */
+export declare const MAX_TRIGGERS_PER_WINDOW = 50;
+export declare const MIN_DURATION_MS = 1;
+export declare const MAX_DURATION_MS = 600000;
+export interface ScreenshotOnArgs {
+    trigger: Trigger;
+    /** Observation window length (ms). Required — the trigger is armed for
+     *  exactly this long. */
+    durationMs: number;
+    /** Workspace-rooted output directory. The server handler defaults this. */
+    intoDir: string;
+    /** `"png"` (default) or `"jpeg"`. */
+    format?: "png" | "jpeg";
+}
+export interface ScreenshotOnResult {
+    intoDir: string;
+    trigger: Trigger;
+    /** Per-capture offset (ms from window start). */
+    capturedAt: number[];
+    /** Absolute paths to written files (same length as `capturedAt`). */
+    paths: string[];
+    warnings: string[];
+}
+export declare function validateOnArgs(args: ScreenshotOnArgs): void;
+export type SnapFn = () => Promise<Buffer>;
+/** Subscribe-once handle returned by a trigger source. The controller passes
+ *  in a callback fired on every trigger event; the source returns a disposer
+ *  it MUST call exactly once when the window closes (no listener leaks). */
+export type TriggerDisposer = () => void;
+export interface TriggerSource {
+    /** Subscribe to `trigger` events. Returns a disposer the controller calls
+     *  on window close (success or wedge). */
+    subscribe(trigger: Trigger, onFire: () => void): TriggerDisposer;
+}
+/** Injectable timing seam. */
+export interface OnClock {
+    now(): number;
+    /** Returns a promise that resolves after `ms`. Cancellable via the returned
+     *  disposer (used to short-circuit when the per-window cap is hit). */
+    setTimeout(fn: () => void, ms: number): () => void;
+}
+export declare function runScreenshotOn(snap: SnapFn, source: TriggerSource, args: ScreenshotOnArgs, workspaceRoot: string, clock?: OnClock): Promise<ScreenshotOnResult>;
+/** Default `intoDir` shape — `screenshots/<sessionId>-<isoTs>/`. Same shape
+ *  `screenshot_schedule` uses; the MCP handler joins it against
+ *  `$BROWX_WORKSPACE` via `resolveWorkspacePath`. */
+export declare function defaultOnDir(sessionId: string, now?: Date): string;

package/dist/page/screenshot-on.js

@@ -0,0 +1,150 @@
+// `screenshot_on` — event-driven screenshot capture. Arm a trigger over a
+// bounded observation window; snap a screenshot every time the trigger
+// fires; return when the window closes (or the per-window cap is hit).
+//
+// Sibling of `screenshot_schedule` (periodic cadence): both share the
+// workspace-rooted disk-write contract and the `file-io` capability gate.
+//
+// Anti-wedge: the call is bounded by `durationMs` (required); the per-window
+// capture cap (`MAX_TRIGGERS_PER_WINDOW`) prevents runaway in event storms
+// (e.g. a console-error-on-every-frame loop). The outer MCP handler wraps
+// the controller in `withDeadline` against the action-timeout.
+//
+// Trigger surface is fixed:
+//   - `navigation`         → page `framenavigated` (main-frame only)
+//   - `console-error`      → page `console` type === "error" OR `pageerror`
+//   - `network-mutation`   → CDP `Network.responseReceived` for a write-shaped
+//                            method (POST/PUT/PATCH/DELETE) with 2xx status
+//   - `dialog`             → page `dialog` (alert/confirm/prompt/beforeunload)
+//
+// Trigger sources are injectable so the controller stays browser-agnostic for
+// unit tests. The real wiring (in server.ts) hooks into Playwright's `Page`
+// event API + the per-session `CDPSession`.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import { resolveWorkspacePath } from "../session/storage.js";
+export const TRIGGERS = ["navigation", "console-error", "network-mutation", "dialog"];
+/** Max captures per `screenshot_on` window. The window is already bounded by
+ *  `durationMs`; this cap prevents an event-storm trigger (e.g. console-error
+ *  fired every animation frame) from filling disk with thousands of frames in
+ *  a multi-second window. Surfaced as a `warnings[]` entry when reached. */
+export const MAX_TRIGGERS_PER_WINDOW = 50;
+export const MIN_DURATION_MS = 1;
+export const MAX_DURATION_MS = 600_000; // 10 minutes
+export function validateOnArgs(args) {
+    if (!TRIGGERS.includes(args.trigger)) {
+        throw new Error(`screenshot_on: \`trigger\` must be one of [${TRIGGERS.join(", ")}] — got "${args.trigger}"`);
+    }
+    if (!Number.isFinite(args.durationMs) ||
+        args.durationMs < MIN_DURATION_MS ||
+        args.durationMs > MAX_DURATION_MS) {
+        throw new Error(`screenshot_on: \`durationMs\` must be in [${MIN_DURATION_MS}, ${MAX_DURATION_MS}] — got ${args.durationMs}`);
+    }
+}
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => {
+        const handle = setTimeout(fn, Math.max(0, ms));
+        return () => clearTimeout(handle);
+    },
+};
+/** Trigger handler: capture one frame per visible state. Drops overlapping fires
+ *  (a single screenshot per state is the useful unit), ends the window on the
+ *  per-window cap, else fires a fire-and-forget snap that writes the PNG. */
+function onScreenshotFire(st) {
+    if (st.capHit || st.snapping)
+        return;
+    if (st.paths.length >= MAX_TRIGGERS_PER_WINDOW) {
+        st.capHit = true;
+        st.warnings.push(`reached MAX_TRIGGERS_PER_WINDOW=${MAX_TRIGGERS_PER_WINDOW} for trigger "${st.trigger}"; window stopped early`);
+        st.endWindow();
+        return;
+    }
+    st.snapping = true;
+    const t = st.clock.now();
+    st.snap()
+        .then((buf) => {
+        const ts = t - st.tStart;
+        const name = `${String(st.i++).padStart(4, "0")}-${ts}.${st.ext}`;
+        // $BROWX_WORKSPACE-rooted by construction (resolveWorkspacePath in caller).
+        const p = join(st.resolvedDir, name);
+        writeFileSync(p, buf);
+        st.paths.push(p);
+        st.capturedAt.push(ts);
+    })
+        .catch((err) => {
+        st.warnings.push(`capture on "${st.trigger}" at +${st.clock.now() - st.tStart}ms: ${err instanceof Error ? err.message : String(err)}`);
+    })
+        .finally(() => {
+        st.snapping = false;
+    });
+}
+export async function runScreenshotOn(snap, source, args, workspaceRoot, clock = REAL_CLOCK) {
+    validateOnArgs(args);
+    // Resolve + create the target dir under $BROWX_WORKSPACE.
+    // `resolveWorkspacePath` rejects path escapes before any byte hits disk.
+    const resolvedDir = resolveWorkspacePath(workspaceRoot, args.intoDir, "screenshot_on");
+    mkdirSync(resolvedDir, { recursive: true });
+    const fmt = args.format ?? "png";
+    const ext = fmt === "jpeg" ? "jpg" : "png";
+    const paths = [];
+    const capturedAt = [];
+    const warnings = [];
+    // Resolver for the window's natural end. The trigger source can also push us
+    // to early-finish when the per-window cap is hit.
+    let resolveWindow = () => undefined;
+    const windowDone = new Promise((r) => {
+        resolveWindow = r;
+    });
+    const cancelTimer = clock.setTimeout(() => resolveWindow(), args.durationMs);
+    const st = {
+        paths,
+        capturedAt,
+        warnings,
+        i: 0,
+        capHit: false,
+        snapping: false,
+        tStart: clock.now(),
+        resolvedDir,
+        ext,
+        snap,
+        clock,
+        trigger: args.trigger,
+        endWindow: () => {
+            cancelTimer();
+            resolveWindow();
+        },
+    };
+    const dispose = source.subscribe(args.trigger, () => onScreenshotFire(st));
+    try {
+        await windowDone;
+    }
+    finally {
+        dispose();
+        cancelTimer();
+    }
+    // A snap may still be in flight when the timer fires — drain briefly so the
+    // final capture lands. Bounded so a wedged snap can't extend the window; the
+    // outer `withDeadline` is the ultimate ceiling.
+    const drainDeadline = clock.now() + 250;
+    while (st.snapping && clock.now() < drainDeadline) {
+        await new Promise((r) => setTimeout(r, 10));
+    }
+    if (st.snapping) {
+        warnings.push(`screenshot_on: final capture did not settle within 250ms drain window — result may omit one frame`);
+    }
+    return {
+        intoDir: resolvePath(resolvedDir),
+        trigger: args.trigger,
+        capturedAt,
+        paths,
+        warnings,
+    };
+}
+/** Default `intoDir` shape — `screenshots/<sessionId>-<isoTs>/`. Same shape
+ *  `screenshot_schedule` uses; the MCP handler joins it against
+ *  `$BROWX_WORKSPACE` via `resolveWorkspacePath`. */
+export function defaultOnDir(sessionId, now = new Date()) {
+    const ts = now.toISOString().replace(/[:.]/g, "-");
+    return `screenshots/${sessionId}-${ts}`;
+}

package/dist/page/screenshot-save.d.ts

@@ -0,0 +1,36 @@
+/** Image format the bytes were encoded as. Matches the existing tool surface
+ *  (`png` / `jpeg`); kept narrow so the result is self-describing without
+ *  the caller having to remember what they asked for. */
+export type ScreenshotFormat = "png" | "jpeg";
+export interface ScreenshotSaveArgs {
+    /** Workspace-rooted file path. Resolved inside `$BROWX_WORKSPACE` — a path
+     *  escaping the workspace is rejected up-front (same chokepoint
+     *  `pdf_save` / `start_har` / `dump_storage_state` use). */
+    path: string;
+    /** Format the bytes are encoded as — recorded on the result so the caller
+     *  doesn't have to re-derive it from a file extension. */
+    format: ScreenshotFormat;
+    /** Whether the bytes were captured with `fullPage:true`. Recorded on the
+     *  result for trace / debug visibility. */
+    fullPage: boolean;
+}
+export interface ScreenshotSaveResult {
+    ok: true;
+    /** Absolute, workspace-rooted path the bytes were written to. */
+    path: string;
+    /** Final on-disk size, in bytes. */
+    bytes: number;
+    /** Format the bytes were encoded as. */
+    format: ScreenshotFormat;
+    /** Whether the capture was full-page (vs viewport / element-scoped). */
+    fullPage: boolean;
+}
+/** Write screenshot bytes to a workspace-rooted path. The caller has already
+ *  encoded the buffer (via Playwright `page.screenshot()` /
+ *  `locator.screenshot()`); this layer resolves the path safely, ensures the
+ *  parent directory exists, and writes the bytes synchronously.
+ *
+ *  Throws on:
+ *  - `path` escaping `$BROWX_WORKSPACE` (via `resolveWorkspacePath`).
+ *  - Underlying `writeFileSync` failure (re-thrown with original message). */
+export declare function screenshotSave(buf: Buffer, workspaceRoot: string, args: ScreenshotSaveArgs): ScreenshotSaveResult;