browxai 0.7.0

package/dist/page/screenshot-save.js

@@ -0,0 +1,53 @@
+// `screenshot` — workspace-rooted file-write extension.
+//
+// The `screenshot` tool's default mode returns inline base64 image bytes (an
+// MCP `image` content part). When the caller supplies a `path`, the bytes are
+// written to a workspace-rooted file instead, and the result swaps the inline
+// image for a `{ ok, path, bytes, format, fullPage }` JSON envelope.
+//
+// This module owns the disk-write side only — buffer encoding stays with the
+// tool layer (Playwright's `page.screenshot()` / `locator.screenshot()` already
+// produced the buffer by the time we're called). Mirrors the `pdf_save` split:
+// the consequential write goes through `resolveWorkspacePath` so a path
+// escaping `$BROWX_WORKSPACE` is rejected before any byte hits disk.
+//
+// Capability gating happens at the tool layer (see `src/server.ts`): when
+// `path` is set, `file-io` is required in addition to the screenshot tool's
+// own `read` gate. Default (no `path`) behaviour is unchanged — no capability
+// change, no disk write.
+import { resolve as resolvePath, dirname } from "node:path";
+import { statSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolveWorkspacePath } from "../session/storage.js";
+/** 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 function screenshotSave(buf, workspaceRoot, args) {
+    const resolved = resolveWorkspacePath(workspaceRoot, args.path, "screenshot");
+    // Ensure parent dir exists — `resolved` is rooted in BROWX_WORKSPACE by
+    // construction (resolveWorkspacePath rejects escapes); `writeFileSync`
+    // fails if the dir is missing. Same pattern as `pdfSave`.
+    mkdirSync(dirname(resolved), { recursive: true });
+    writeFileSync(resolved, buf);
+    let bytes = 0;
+    try {
+        bytes = statSync(resolved).size;
+    }
+    catch {
+        /* best-effort */
+    }
+    // Belt-and-braces: re-run resolve to surface the absolute path (the input
+    // may have been a workspace-relative path).
+    const absolute = resolvePath(resolved);
+    return {
+        ok: true,
+        path: absolute,
+        bytes,
+        format: args.format,
+        fullPage: args.fullPage,
+    };
+}

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

@@ -0,0 +1,50 @@
+export declare const MIN_INTERVAL_MS = 100;
+export declare const MAX_INTERVAL_MS = 60000;
+/** Hard cap on captures-per-call. The schedule is already bounded by
+ *  count/durationMs; this is a belt-and-braces ceiling so a 100ms cadence over
+ *  the 1h action-timeout ceiling can't blow up disk space in one call. */
+export declare const MAX_CAPTURES_PER_CALL = 1000;
+export interface ScheduleArgs {
+    everyMs: number;
+    /** Mutually exclusive with `durationMs`. */
+    count?: number;
+    /** Mutually exclusive with `count`. */
+    durationMs?: number;
+    /** Destination directory (workspace-rooted). Defaulted by the server
+     *  handler before this layer ever sees it (so the controller's contract
+     *  stays "give me a resolved dir"). */
+    intoDir: string;
+    /** Image format — `"png"` (default) or `"jpeg"`. Recorded in each file's
+     *  extension so the caller can spot the format from the dir alone. */
+    format?: "png" | "jpeg";
+}
+export interface ScheduleResult {
+    intoDir: string;
+    count: number;
+    capturedAt: number[];
+    paths: string[];
+    warnings: string[];
+}
+/** Validate the shape; throw early so the MCP handler can return a structured
+ *  error before any disk write. */
+export declare function validateScheduleArgs(args: ScheduleArgs): void;
+/** Inject a `snap()` for tests; the real wiring passes a closure over
+ *  Playwright's `page.screenshot()`. Returns the encoded bytes. */
+export type SnapFn = () => Promise<Buffer>;
+/** Injectable timing seam (real impl uses `setTimeout` + `Date.now`). */
+export interface ScheduleClock {
+    now(): number;
+    /** Sleep for `ms`. Returns when the timer fires; never rejects. */
+    sleep(ms: number): Promise<void>;
+}
+export declare function runSchedule(snap: SnapFn, args: ScheduleArgs, workspaceRoot: string, clock?: ScheduleClock): Promise<ScheduleResult>;
+/** Default `intoDir` shape — `screenshots/<sessionId>-<isoTs>/`. The MCP
+ *  handler joins this against `$BROWX_WORKSPACE` via `resolveWorkspacePath`,
+ *  same as a user-supplied path. ISO timestamp uses `:` / `.` → `-` so the
+ *  path is filesystem-friendly on every platform. */
+export declare function defaultScheduleDir(sessionId: string, now?: Date): string;
+/** Shared dir-creation helper — re-used by `screenshot_on`. Rooted inside
+ *  $BROWX_WORKSPACE (path escape is rejected by `resolveWorkspacePath`). */
+export declare function ensureWorkspaceDir(workspaceRoot: string, intoDir: string, tool: string): string;
+/** Stat helper used by the result envelope — best-effort byte count per file. */
+export declare function fileBytes(path: string): number;

package/dist/page/screenshot-schedule.js

@@ -0,0 +1,155 @@
+// `screenshot_schedule` — periodic screenshot captures at a fixed interval,
+// stopped by a hard count or a wall-clock duration. Sibling of
+// `screenshot_on` (event-driven). The controller itself is browser-agnostic:
+// the *snap* function is injected, so the policy (cadence + stop) and the
+// path-write side stay independently unit-testable.
+//
+// Anti-wedge: every call is bounded — either `count` OR `durationMs` must be
+// supplied (mutually exclusive), so an unbounded interval-fire-forever loop
+// can't exist. The outer MCP handler additionally wraps the controller in
+// `withDeadline` against the action-timeout so the call returns even if a
+// single `snap` wedges. Capability `file-io` (the bytes hit disk).
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import { resolveWorkspacePath } from "../session/storage.js";
+export const MIN_INTERVAL_MS = 100;
+export const MAX_INTERVAL_MS = 60_000;
+/** Hard cap on captures-per-call. The schedule is already bounded by
+ *  count/durationMs; this is a belt-and-braces ceiling so a 100ms cadence over
+ *  the 1h action-timeout ceiling can't blow up disk space in one call. */
+export const MAX_CAPTURES_PER_CALL = 1000;
+/** Validate the shape; throw early so the MCP handler can return a structured
+ *  error before any disk write. */
+export function validateScheduleArgs(args) {
+    if (!Number.isFinite(args.everyMs) ||
+        args.everyMs < MIN_INTERVAL_MS ||
+        args.everyMs > MAX_INTERVAL_MS) {
+        throw new Error(`screenshot_schedule: \`everyMs\` must be in [${MIN_INTERVAL_MS}, ${MAX_INTERVAL_MS}] — got ${args.everyMs}`);
+    }
+    const hasCount = typeof args.count === "number";
+    const hasDuration = typeof args.durationMs === "number";
+    if (hasCount && hasDuration) {
+        throw new Error(`screenshot_schedule: \`count\` and \`durationMs\` are mutually exclusive — pass exactly one`);
+    }
+    if (!hasCount && !hasDuration) {
+        throw new Error(`screenshot_schedule: pass either \`count\` (N captures) or \`durationMs\` (window length, ms) — unbounded schedules are refused`);
+    }
+    if (hasCount &&
+        (!Number.isInteger(args.count) ||
+            args.count < 1 ||
+            args.count > MAX_CAPTURES_PER_CALL)) {
+        throw new Error(`screenshot_schedule: \`count\` must be an integer in [1, ${MAX_CAPTURES_PER_CALL}] — got ${args.count}`);
+    }
+    if (hasDuration &&
+        (!Number.isFinite(args.durationMs) || args.durationMs < args.everyMs)) {
+        throw new Error(`screenshot_schedule: \`durationMs\` must be >= \`everyMs\` — got durationMs=${args.durationMs}, everyMs=${args.everyMs}`);
+    }
+}
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms))),
+};
+/** Run the schedule. The caller is responsible for the outer `withDeadline`
+ *  wrap (anti-wedge), and supplies `workspaceRoot` so `intoDir` resolves
+ *  inside `$BROWX_WORKSPACE`. */
+/** Attempt one capture; on failure surface a warning and return null (a single
+ *  transient hiccup shouldn't poison the whole window). */
+async function tryCapture(snap, i, warnings) {
+    try {
+        return await snap();
+    }
+    catch (err) {
+        warnings.push(`capture ${i}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/** Sleep until the next scheduled tick (drift-tolerant: anchored to the capture
+ *  start, so a slow snap still fires the next tick on-cadence). Returns true when
+ *  the window has ended (caller should break). */
+async function cadenceSleep(clock, captureStart, everyMs, hasCount, windowEndMs) {
+    const sleepMs = Math.max(0, captureStart + everyMs - clock.now());
+    if (!hasCount && clock.now() + sleepMs >= windowEndMs) {
+        await clock.sleep(Math.max(0, windowEndMs - clock.now()));
+        return true;
+    }
+    await clock.sleep(sleepMs);
+    return false;
+}
+export async function runSchedule(snap, args, workspaceRoot, clock = REAL_CLOCK) {
+    validateScheduleArgs(args);
+    // Resolve + create the target dir under $BROWX_WORKSPACE. `resolveWorkspacePath`
+    // rejects path-escape attempts before any byte hits disk (same chokepoint as
+    // `screenshot({path})`).
+    const resolvedDir = resolveWorkspacePath(workspaceRoot, args.intoDir, "screenshot_schedule");
+    mkdirSync(resolvedDir, { recursive: true });
+    const fmt = args.format ?? "png";
+    const ext = fmt === "jpeg" ? "jpg" : "png";
+    const paths = [];
+    const capturedAt = [];
+    const warnings = [];
+    const tStart = clock.now();
+    const hasCount = typeof args.count === "number";
+    const targetCount = hasCount ? args.count : MAX_CAPTURES_PER_CALL;
+    const windowEndMs = hasCount ? Number.POSITIVE_INFINITY : tStart + args.durationMs;
+    let i = 0;
+    while (i < targetCount && clock.now() < windowEndMs) {
+        // Belt-and-braces ceiling — independent of count/duration. Ensures a
+        // 100ms-cadence over the 1h action-timeout ceiling can't blow up disk space.
+        if (paths.length >= MAX_CAPTURES_PER_CALL) {
+            warnings.push(`reached MAX_CAPTURES_PER_CALL=${MAX_CAPTURES_PER_CALL}; schedule stopped early`);
+            break;
+        }
+        const t = clock.now();
+        const buf = await tryCapture(snap, i, warnings);
+        if (buf === null) {
+            i++;
+            // Honour the cadence even on a failed capture.
+            if (i < targetCount && clock.now() < windowEndMs)
+                await clock.sleep(Math.max(0, args.everyMs));
+            continue;
+        }
+        const ts = clock.now() - tStart;
+        // `p` inherits its $BROWX_WORKSPACE-rooted dir from `resolvedDir`.
+        const p = join(resolvedDir, `${String(i).padStart(4, "0")}-${ts}.${ext}`);
+        writeFileSync(p, buf);
+        paths.push(p);
+        capturedAt.push(ts);
+        i++;
+        if (i >= targetCount)
+            break;
+        if (await cadenceSleep(clock, t, args.everyMs, hasCount, windowEndMs))
+            break;
+    }
+    return {
+        intoDir: resolvePath(resolvedDir),
+        count: paths.length,
+        capturedAt,
+        paths,
+        warnings,
+    };
+}
+/** Default `intoDir` shape — `screenshots/<sessionId>-<isoTs>/`. The MCP
+ *  handler joins this against `$BROWX_WORKSPACE` via `resolveWorkspacePath`,
+ *  same as a user-supplied path. ISO timestamp uses `:` / `.` → `-` so the
+ *  path is filesystem-friendly on every platform. */
+export function defaultScheduleDir(sessionId, now = new Date()) {
+    const ts = now.toISOString().replace(/[:.]/g, "-");
+    return `screenshots/${sessionId}-${ts}`;
+}
+/** Shared dir-creation helper — re-used by `screenshot_on`. Rooted inside
+ *  $BROWX_WORKSPACE (path escape is rejected by `resolveWorkspacePath`). */
+export function ensureWorkspaceDir(workspaceRoot, intoDir, tool) {
+    const resolved = resolveWorkspacePath(workspaceRoot, intoDir, tool);
+    // $BROWX_WORKSPACE-rooted by construction (resolveWorkspacePath above).
+    mkdirSync(resolved, { recursive: true });
+    return resolved;
+}
+/** Stat helper used by the result envelope — best-effort byte count per file. */
+export function fileBytes(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { Page } from "playwright-core";
+import type { SafariSessionHandle } from "../engine/index.js";
+/** The script capability port. One instance wraps one session's engine handle;
+ *  the method carries no engine type, so the handler above this seam is
+ *  engine-blind. Mirrors the ActionSubstrate / CaptureSubstrate shape. The
+ *  returned value is page-controlled (untrusted); the handler treats it the same
+ *  as snapshot text. The deadline race + error envelope stay in the handler — the
+ *  substrate only performs the raw evaluation. */
+export interface ScriptSubstrate {
+    readonly engine: string;
+    evaluate(expr: string): Promise<unknown>;
+}
+/** Playwright engines — delegates to `page.evaluate(expr)` verbatim. `page.evaluate`
+ *  carries no Playwright timeout (a never-resolving expr would wedge forever), so the
+ *  handler races the returned promise against the anti-wedge deadline exactly as it
+ *  did pre-seam. No behaviour change. */
+export declare class PlaywrightScriptSubstrate implements ScriptSubstrate {
+    private readonly page;
+    readonly engine: string;
+    constructor(page: () => Page, engine?: string);
+    evaluate(expr: string): Promise<unknown>;
+}
+/** Safari — the WebDriver-Classic eval path. safaridriver has no Playwright Page;
+ *  `execute/sync` takes a function BODY, so the bare expression is wrapped in
+ *  `return (…)` to evaluate it and return its value — the verbatim wrapping from the
+ *  handler's deleted Safari branch. */
+export declare class SafariScriptSubstrate implements ScriptSubstrate {
+    private readonly handle;
+    readonly engine = "safari";
+    constructor(handle: SafariSessionHandle);
+    evaluate(expr: string): Promise<unknown>;
+}

package/dist/page/script-substrate.js

@@ -0,0 +1,47 @@
+// The ScriptSubstrate interface — the engine-agnostic seam beneath page-side JS
+// evaluation (`eval_js` today; `exposeBinding` / `addInitScript` later). It keeps
+// engine specifics out of the handler: the `eval_js` handler asks a substrate to
+// evaluate an expression and gets back the page-controlled value; an engine-specific
+// implementation does the work. The handler never names Playwright, safaridriver,
+// or an engine — it calls `scriptFor(e).evaluate(expr)`, the same shape as
+// `actionsFor(e).click(args)` / `captureFor(e).screenshot(args)`.
+//
+// Dependency direction (architecture doctrine §1): tool handler → ScriptSubstrate
+// (this interface) → implementation → Playwright | safaridriver. Two impls today:
+//   - PlaywrightScriptSubstrate (chromium / firefox / webkit / android): wraps
+//     `page.evaluate(expr)` verbatim — byte-identical to the pre-seam handler, so
+//     the four engines' keystones stay green unchanged.
+//   - SafariScriptSubstrate (safari): wraps `webDriver.executeScript` over the
+//     WebDriver Classic `execute/sync` endpoint, wrapping the expression in
+//     `return (…)` (an expression, not a statement body) exactly as the handler's
+//     deleted `if (sh)` branch did — so the engine specifics live here, not as an
+//     engine check in the handler.
+/** Playwright engines — delegates to `page.evaluate(expr)` verbatim. `page.evaluate`
+ *  carries no Playwright timeout (a never-resolving expr would wedge forever), so the
+ *  handler races the returned promise against the anti-wedge deadline exactly as it
+ *  did pre-seam. No behaviour change. */
+export class PlaywrightScriptSubstrate {
+    page;
+    engine;
+    constructor(page, engine = "chromium") {
+        this.page = page;
+        this.engine = engine;
+    }
+    evaluate(expr) {
+        return this.page().evaluate(expr);
+    }
+}
+/** Safari — the WebDriver-Classic eval path. safaridriver has no Playwright Page;
+ *  `execute/sync` takes a function BODY, so the bare expression is wrapped in
+ *  `return (…)` to evaluate it and return its value — the verbatim wrapping from the
+ *  handler's deleted Safari branch. */
+export class SafariScriptSubstrate {
+    handle;
+    engine = "safari";
+    constructor(handle) {
+        this.handle = handle;
+    }
+    evaluate(expr) {
+        return this.handle.webDriver.executeScript(this.handle.sessionId, `return (${expr});`);
+    }
+}

package/dist/page/seed-random.d.ts

@@ -0,0 +1,45 @@
+import type { BrowserContext, Page } from "playwright-core";
+export interface SeedRandomInput {
+    /** Non-negative finite integer seed. 0 is valid. */
+    seed: number;
+}
+export interface SeedRandomState {
+    seed: number;
+}
+/**
+ * The page-side init script. Defined as a string so Playwright can serialise
+ * it intact to every new document. Re-reads `window.__browxSeed` on every
+ * call (set by the install-script closure) so a re-seed via the main-frame
+ * hook below is picked up by the next `Math.random()` without re-injection.
+ *
+ * Mulberry32 — small, fast, statistically reasonable for testing flake-repros;
+ * not cryptographic and explicitly NOT a `crypto` replacement.
+ */
+declare function buildInitScript(seed: number): string;
+/** Per-session seeded-random controller. One per SessionEntry. */
+export declare class SeededRandomRegistry {
+    private state;
+    /** Tracks whether we've installed a context-level init script yet. The
+     *  reference is the BrowserContext so a session-shared context only gets
+     *  one. */
+    private contextInstalled;
+    /** Tracks pages we've wired the re-apply hook on. */
+    private reattachInstalled;
+    /** Apply a seed override and remember it. */
+    apply(context: BrowserContext, page: Page, input: SeedRandomInput): Promise<{
+        state: SeedRandomState;
+    }>;
+    /** Test introspection. */
+    current(): SeedRandomState | undefined;
+    /** Defensive re-apply: `addInitScript` is per-document, but a renderer swap
+     *  or main-frame nav still benefits from a re-push for symmetry with
+     *  src/page/emulation.ts + src/page/clock.ts. We push the cached seed back
+     *  into the main frame on every main-frame `framenavigated`. */
+    private installReattach;
+}
+/** Test-only: expose the script-builder so tests can assert determinism by
+ *  evaluating the produced source in a sandbox without launching a browser. */
+export declare const _internal: {
+    buildInitScript: typeof buildInitScript;
+};
+export {};

package/dist/page/seed-random.js

@@ -0,0 +1,144 @@
+// Deterministic Math.random — capability `action`.
+//
+// Wraps Playwright `context.addInitScript` to inject a Mulberry32 PRNG that
+// replaces `Math.random` at every realm bootstrap. The seed is captured by
+// closure inside the init script so each navigation (and every iframe /
+// worker that uses an init-script-installed Math.random) gets a fresh
+// deterministic stream starting from the same state. Per-session.
+//
+// Reset semantics:
+//   - `seed_random({ seed })` with a finite, non-negative integer seed →
+//     installs the override (or replaces the cached seed if already set).
+//   - The init script is added ONCE per BrowserContext on first apply; the
+//     cached seed lives on a `window.__browxSeed` writeable closure-set by
+//     the init script. To re-seed we mutate that closure on the current page
+//     AND swap the context's init-script seed for any future page bootstrap.
+//
+// Re-apply on navigation:
+//   - Playwright `addInitScript` is a context-level primitive — it runs in
+//     every new document. To stay future-proof against renderer-swap edge
+//     cases (mirroring src/page/emulation.ts + src/page/clock.ts), we also
+//     install a `framenavigated` hook that pushes the cached seed back into
+//     the main-frame realm.
+//
+// MVP scope (not touched):
+//   - `crypto.randomUUID` / `crypto.getRandomValues` — web-crypto is a much
+//     bigger surface to deterministically stub; revisit later.
+//   - Workers — `addInitScript` runs in every document realm but not inside
+//     Web Workers / Service Workers. Out of scope for v1.
+//
+// BYOB note: the init script is installed on the attached Chrome's context
+// for as long as the context lives. After our session detaches, any tab
+// the human spawns from this context still hits the override on first load
+// — surfaced as a `warning` on the result.
+const MAX_SEED = 0xffffffff; // 2^32 - 1, Mulberry32's state domain
+/**
+ * The page-side init script. Defined as a string so Playwright can serialise
+ * it intact to every new document. Re-reads `window.__browxSeed` on every
+ * call (set by the install-script closure) so a re-seed via the main-frame
+ * hook below is picked up by the next `Math.random()` without re-injection.
+ *
+ * Mulberry32 — small, fast, statistically reasonable for testing flake-repros;
+ * not cryptographic and explicitly NOT a `crypto` replacement.
+ */
+function buildInitScript(seed) {
+    return `(() => {
+  // Idempotent: a refresh that re-runs the init script must not stack overrides.
+  if (Object.prototype.hasOwnProperty.call(globalThis, "__browxSeed")) {
+    globalThis.__browxSeed = ${seed} >>> 0;
+    return;
+  }
+  let state = ${seed} >>> 0;
+  Object.defineProperty(globalThis, "__browxSeed", {
+    configurable: true,
+    enumerable: false,
+    get() { return state; },
+    set(v) { state = (v | 0) >>> 0; },
+  });
+  const mulberry32 = () => {
+    state = (state + 0x6D2B79F5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  try {
+    Object.defineProperty(Math, "random", {
+      configurable: true,
+      writable: true,
+      value: mulberry32,
+    });
+  } catch {
+    // Fallback if Math.random is non-configurable in some embedder; assign anyway.
+    Math.random = mulberry32;
+  }
+})();`;
+}
+function normalize(input) {
+    const s = input.seed;
+    if (s === undefined ||
+        s === null ||
+        !Number.isFinite(s) ||
+        !Number.isInteger(s) ||
+        s < 0 ||
+        s > MAX_SEED) {
+        throw new Error(`seed_random: seed must be a non-negative integer in [0, ${MAX_SEED}] (got ${JSON.stringify(s)})`);
+    }
+    return { seed: s };
+}
+/** Per-session seeded-random controller. One per SessionEntry. */
+export class SeededRandomRegistry {
+    state;
+    /** Tracks whether we've installed a context-level init script yet. The
+     *  reference is the BrowserContext so a session-shared context only gets
+     *  one. */
+    contextInstalled = new WeakSet();
+    /** Tracks pages we've wired the re-apply hook on. */
+    reattachInstalled = new WeakSet();
+    /** Apply a seed override and remember it. */
+    async apply(context, page, input) {
+        const state = normalize(input);
+        if (!this.contextInstalled.has(context)) {
+            // First time: register the init script on the context so every new
+            // document (including the current one's NEXT navigation) sees it.
+            await context.addInitScript({ content: buildInitScript(state.seed) });
+            this.contextInstalled.add(context);
+        }
+        // Re-seed the CURRENT page's main realm immediately so a caller doesn't
+        // have to navigate to see the override take effect. This is best-effort —
+        // a closed page or detached frame raises, swallowed.
+        await page.evaluate(buildInitScript(state.seed)).catch(() => undefined);
+        this.state = state;
+        this.installReattach(page);
+        return { state };
+    }
+    /** Test introspection. */
+    current() {
+        return this.state;
+    }
+    /** Defensive re-apply: `addInitScript` is per-document, but a renderer swap
+     *  or main-frame nav still benefits from a re-push for symmetry with
+     *  src/page/emulation.ts + src/page/clock.ts. We push the cached seed back
+     *  into the main frame on every main-frame `framenavigated`. */
+    installReattach(page) {
+        if (this.reattachInstalled.has(page))
+            return;
+        this.reattachInstalled.add(page);
+        const onNav = async (frame) => {
+            if (frame.parentFrame())
+                return; // main frame only
+            if (!this.state)
+                return;
+            try {
+                await page.evaluate(buildInitScript(this.state.seed)).catch(() => undefined);
+            }
+            catch {
+                // page may have closed mid-navigation; swallow
+            }
+        };
+        page.on("framenavigated", onNav);
+    }
+}
+/** Test-only: expose the script-builder so tests can assert determinism by
+ *  evaluating the produced source in a sandbox without launching a browser. */
+export const _internal = { buildInitScript };

package/dist/page/set-of-marks.d.ts

@@ -0,0 +1,96 @@
+import type { CDPSession, Page } from "playwright-core";
+import { type FindCandidate } from "./find.js";
+import type { RefRegistry } from "./refs.js";
+import { type VisibleRect } from "./bbox.js";
+import type { SnapshotSubstrate } from "./snapshot-substrate.js";
+export type LabelMode = "index" | "ref" | "role";
+export interface MarkCandidateRef {
+    /** Stable `eN` ref previously surfaced by snapshot/find. */
+    ref: string;
+}
+/** A pre-computed `find()` candidate. The caller can pass the full object
+ *  through — we only consume `ref`, `role`, `name`, `testId`, and `bbox`. */
+export type MarkCandidate = MarkCandidateRef | Pick<FindCandidate, "ref" | "role" | "name" | "testId" | "bbox">;
+export interface SetOfMarksOptions {
+    candidates: MarkCandidate[];
+    /** How to label each painted box. Default `"index"` — the array-position
+     *  numbering 1..N (paired with `mapping` so the agent can convert to `eN`).
+     *  `"ref"` paints the existing `eN` directly. `"role"` paints the candidate's
+     *  role (useful when the agent already has refs and wants visual grounding
+     *  on what each box *is*). */
+    label?: LabelMode;
+    /** Configured test-attribute list — required if any candidate is a bare
+     *  `{ref}` and we have to resolve its bbox via `find()`'s tree walker.
+     *  When every candidate already carries `bbox`, unused. */
+    testAttributes?: string[];
+}
+export interface MarkEntry {
+    /** 1-based array position. Stable for the duration of the call result. */
+    index: number;
+    /** Existing `eN` ref — the cross-snapshot-stable identity. */
+    ref: string;
+    role?: string;
+    name?: string;
+    testId?: string;
+    bbox: VisibleRect | null;
+    /** True when this candidate was painted on the image. A candidate with a
+     *  null bbox (fully clipped / off-screen) is reported but not painted. */
+    painted: boolean;
+}
+export interface SetOfMarksResult {
+    /** base64-encoded PNG of the viewport with the painted overlay. */
+    imageBase64: string;
+    mimeType: "image/png";
+    /** Per-candidate row: array position, ref, role/name/testId, the bbox we
+     *  painted (or null), and whether it landed on the image. The agent can
+     *  index 1..N OR address `eN` — same identity. */
+    marks: MarkEntry[];
+    /** Convenience: `{ "1": "e7", "2": "e3", … }`. Lets the LLM say "click 2"
+     *  and the harness translate back to `click({ref:"e3"})`. */
+    mapping: Record<string, string>;
+    /** Non-fatal notes (candidates with no bbox, ref-only inputs we couldn't
+     *  resolve, etc.). Same convention as `find()`'s `warnings`. */
+    warnings: string[];
+}
+/**
+ * Resolve a list of `MarkCandidate`s (mixed `{ref}` and full-candidate shape)
+ * into `MarkEntry` rows. For bare `{ref}` inputs that aren't already bound to
+ * a locator in the registry, we fall back to `find()` over the existing tree
+ * to look up the bbox + role/name. Pure-ish: only does a `find()` walk when
+ * a bare ref needs resolving. Exported for unit-test composition.
+ */
+/** The page-side dependencies `resolveCandidates` threads through (bundled so the
+ *  signature stays within the parameter budget). `cdp` is the chromium-only
+ *  visible-rect fast path; off Chromium it is undefined and bbox computes via the
+ *  portable `locatorBoundingBox` fallback. */
+export interface MarksDeps {
+    page: Page;
+    substrate: SnapshotSubstrate;
+    refs: RefRegistry;
+    testAttributes: string[];
+    cdp?: CDPSession;
+}
+export declare function resolveCandidates(deps: MarksDeps, candidates: MarkCandidate[]): Promise<{
+    entries: MarkEntry[];
+    warnings: string[];
+}>;
+/** Pure label-builder. Exported for unit-test direct coverage. */
+export declare function labelFor(entry: MarkEntry, mode: LabelMode): string;
+/**
+ * Compose a single PNG screenshot of the current viewport with numbered
+ * bounding boxes painted over the supplied candidates. The numbering scheme
+ * shares the existing `eN` ref namespace (index↔ref mapping returned).
+ *
+ * `bbox` is honoured exactly as `find()` reported it — visible-rect with
+ * ancestor-overflow + viewport intersection applied (see `src/page/bbox.ts`).
+ * A candidate with `bbox: null` is **not** painted; it's listed in `marks`
+ * with `painted: false` and a `warnings` entry, so the caller knows the
+ * mapping still resolves but the box wasn't visible.
+ *
+ * The overlay is installed for the duration of the screenshot only and
+ * removed before this function returns. Failures during removal are
+ * best-effort (we still return the image + the warning).
+ */
+export declare function screenshotMarks(page: Page, substrate: SnapshotSubstrate, refs: RefRegistry, opts: SetOfMarksOptions, 
+/** CDP handle for the visible-rect bbox fast path — chromium only. */
+cdp?: CDPSession): Promise<SetOfMarksResult>;