@reticlehq/server 3.9.0 → 3.10.1

package/dist/memory/journal/session-journal.js

@@ -146,11 +146,13 @@ export class SessionJournal {
     #droppedBytes = 0;
     /** Parsed records evicted from the retained set. Exact — these were counted, not estimated. */
     #droppedEvents = 0;
-    /**
-     * Latest parsed eviction timestamp, or +Infinity after unparsed bytes were skipped.
-     * -Infinity means no loss. Later intact reads cannot narrow an unknown discarded time range.
-     */
+    /** Latest `t` that a cut or an eviction can reach, inclusive. -Infinity means no loss. */
     #lostThroughT = Number.NEGATIVE_INFINITY;
+    /** A cut skipped bytes and no record after it has been parsed yet, so its bound is unknown. */
+    #cutPending = false;
+    /** The last record parsed, so a cut can tell whether the clock started again across it. */
+    #lastParsed;
+    #now;
     constructor(fs, root, sessionId, options = {}) {
         if (!isValidSessionId(sessionId)) {
             throw new Error(`refusing to journal an unsafe session id: ${sessionId}`);
@@ -171,6 +173,7 @@ export class SessionJournal {
         this.#maxRetainedBytes = boundedOption(options.maxRetainedBytes, JOURNAL_READ_LIMITS.MAX_RETAINED_BYTES, 'maxRetainedBytes');
         this.#maxRetainedEvents = boundedOption(options.maxRetainedEvents, JOURNAL_READ_LIMITS.MAX_RETAINED_EVENTS, 'maxRetainedEvents');
         this.#eventBytesCap = cap;
+        this.#now = options.now;
     }
     /**
      * Append a batch, or refuse it at the byte cap and say so.
@@ -416,10 +419,15 @@ export class SessionJournal {
             // never skips, so its start IS the offset we asked for.
             const from = chunk.from ?? this.#eventBytesConsumed;
             const skipped = Math.max(0, from - this.#eventBytesConsumed);
-            this.#ingestTail(chunk.text);
+            // Before the ingest, so the first record parsed after the cut bounds it.
             if (skipped > 0) {
                 this.#noteCut(skipped);
             }
+            this.#ingestTail(chunk.text);
+            const now = this.#now;
+            if (this.#cutPending && now !== undefined) {
+                this.#boundCut({ t: now() });
+            }
             // Resume at the end of the last COMPLETE line, counted forward over the bytes that actually
             // ARRIVED. Not from `chunk.size`: that is the file's end as `fstat` reported it, and a read
             // truncated or cut short returns less — a cursor there would skip every unread byte, silently
@@ -494,6 +502,10 @@ export class SessionJournal {
             }
             const result = ReticleEventSchema.safeParse(parsed);
             if (result.success) {
+                if (this.#cutPending) {
+                    this.#boundCut(result.data);
+                }
+                this.#lastParsed = result.data;
                 this.#eventCache.push(result.data);
                 // Its cost in the file, newline included — so the retained bound is in the same unit the
                 // read ceiling and the loss report are.
@@ -543,13 +555,37 @@ export class SessionJournal {
         }
     }
     /**
-     * Skipped bytes have unknown timestamps: page clocks can reset while the journal id survives.
-     * A surviving tail cannot bound records that were never parsed. Later intact reads cannot
-     * reconstruct that history; finite bounds apply only to parsed cache evictions.
+     * Skipped bytes are not parsed, so their `t` is not known at the cut. The first record parsed
+     * after the cut, or the time of the read, can bound them (see `#boundCut`). Until then, the cut
+     * reaches every window.
      */
     #noteCut(skippedBytes) {
         this.#droppedBytes += skippedBytes;
-        this.#lostThroughT = Number.POSITIVE_INFINITY;
+        this.#cutPending = true;
+    }
+    /**
+     * Bound the pending cut at `next`: the first record parsed after it, or the time of the read.
+     *
+     * The file is append-only, and one connection stamps `t` from one monotonic clock
+     * (`Session.elapsed`). So when the clock did not start again across the cut, each skipped record
+     * has a `t` at or before `next.t`.
+     *
+     * A reload or a reconnect keeps the session id and starts the clock again, and one window can
+     * span it: a window opened at t=150 on the old connection can hold skipped old records at t=200
+     * while the new connection's records start at t=10. A bound from the new clock then clears a
+     * window that lost evidence. So the cut stays unbounded, for good, when the reset cannot be
+     * ruled out: no record was parsed before the cut, or `t` or `seq` went down, or the document
+     * changed. This check is conservative but not complete. A reconnect in the same document whose
+     * new clock already passed the old `t` shows none of the three signs.
+     */
+    #boundCut(next) {
+        const last = this.#lastParsed;
+        this.#cutPending = false;
+        if (last === undefined || clockStartedAgain(last, next)) {
+            this.#lostThroughT = Number.POSITIVE_INFINITY;
+            return;
+        }
+        this.#lostThroughT = Math.max(this.#lostThroughT, next.t);
     }
     /**
      * What these reads could not produce, or `undefined` when nothing was lost.
@@ -562,7 +598,7 @@ export class SessionJournal {
         if (0 === this.#droppedBytes && 0 === this.#droppedEvents) {
             return undefined;
         }
-        const bounded = Number.isFinite(this.#lostThroughT);
+        const bounded = !this.#cutPending && Number.isFinite(this.#lostThroughT);
         return {
             droppedBytes: this.#droppedBytes,
             droppedEvents: this.#droppedEvents,
@@ -621,6 +657,18 @@ export class SessionJournal {
         return out;
     }
 }
+/** Did the clock start again between `last` and `next`? A field one record lacks proves nothing. */
+function clockStartedAgain(last, next) {
+    if (next.t < last.t) {
+        return true;
+    }
+    if (last.seq !== undefined && next.seq !== undefined && next.seq < last.seq) {
+        return true;
+    }
+    return (last.documentId !== undefined &&
+        next.documentId !== undefined &&
+        next.documentId !== last.documentId);
+}
 /**
  * The closure report a session's sidecar holds — details when it can be read, the bare fact when not.
  *

package/dist/memory/project/root-claims.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The `.reticle` folder a caller meant by `root`. Agents pass the project folder, the one they work
+ * in, so a folder that holds a `.reticle` stands for it — and so does any existing directory, since
+ * a fresh worktree has none until the first run writes one, the same way a `.reticle` path is
+ * accepted before it exists. A path nowhere on disk is the caller's to fix, and the refusals name
+ * the path to pass. Openings exported so error-recovery classifies both as the caller's mistake.
+ */
+export declare const ARTIFACT_ROOT_ABSOLUTE_REFUSAL: string;
+export declare const ARTIFACT_ROOT_MISSING_REFUSAL: string;
 /** Claim `root` for the session a lease registers. Takes a `.reticle` folder or the project folder holding one. */
 export declare function claimArtifactRoot(leaseId: string, root: string): void;
 /** Every root a lease claimed in this process, released or not. Sync reads it to find the work. */

package/dist/memory/project/root-claims.js

@@ -17,20 +17,25 @@ const claims = new Map();
 const everClaimed = new Set();
 /**
  * The `.reticle` folder a caller meant by `root`. Agents pass the project folder, the one they work
- * in, so a folder that holds a `.reticle` stands for it. Anything else is refused with the path to pass.
+ * in, so a folder that holds a `.reticle` stands for it — and so does any existing directory, since
+ * a fresh worktree has none until the first run writes one, the same way a `.reticle` path is
+ * accepted before it exists. A path nowhere on disk is the caller's to fix, and the refusals name
+ * the path to pass. Openings exported so error-recovery classifies both as the caller's mistake.
  */
+export const ARTIFACT_ROOT_ABSOLUTE_REFUSAL = `root must be an absolute path to a ${ReticleDir.ROOT} folder`;
+export const ARTIFACT_ROOT_MISSING_REFUSAL = `root must be an existing directory, or the ${ReticleDir.ROOT} folder inside one`;
 function resolveArtifactRoot(root) {
     if (!isAbsolute(root)) {
-        throw new Error(`root must be an absolute path to a ${ReticleDir.ROOT} folder, got ${root}`);
+        throw new Error(`${ARTIFACT_ROOT_ABSOLUTE_REFUSAL}, got ${root}`);
     }
     if (ReticleDir.ROOT === basename(root)) {
         return root;
     }
     const inside = join(root, ReticleDir.ROOT);
-    if (isDirectory(inside)) {
+    if (isDirectory(inside) || isDirectory(root)) {
         return inside;
     }
-    throw new Error(`root must be the ${ReticleDir.ROOT} folder, or a project folder that contains one, got ${root}. Pass ${inside}`);
+    throw new Error(`${ARTIFACT_ROOT_MISSING_REFUSAL}, got ${root}. Pass ${inside}`);
 }
 function isDirectory(path) {
     try {

package/dist/portal/input/download-capture.d.ts

@@ -0,0 +1,7 @@
+import { type NetworkDetail } from './network-detail.js';
+/** The part of a CDP session this needs, kept structural so it can be tested with a fake. */
+export interface CdpLike {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    on(event: string, handler: (event: unknown) => void): void;
+}
+export declare function attachDownloadCapture(cdp: CdpLike, emit: (detail: NetworkDetail) => void, pageUrl: () => string): Promise<void>;

package/dist/portal/input/download-capture.js

@@ -0,0 +1,92 @@
+import { buildNetworkDetail } from './network-detail.js';
+import { drivenRedactionPolicy } from './driven-redaction.js';
+/**
+ * Capture a file the server sends as a download, on a page Reticle drives.
+ *
+ * A click that becomes a download leaves the page as a navigation the browser turns into a file.
+ * Measured on Chromium, nothing the page can see records it: no page `request`/`response` event, no
+ * CDP `Network.responseReceived` on the page target, and a Playwright route does not intercept it.
+ * So a `net` check on a working export missed. CDP request interception at the response stage does
+ * see it, with the status and headers, so this listens there.
+ *
+ * Document responses only, and every paused response is let through at once: the capture must never
+ * change or delay what the page receives. Chromium only; a browser without the Fetch domain gets no
+ * capture rather than an error.
+ */
+const DOCUMENT_RESPONSES = { patterns: [{ resourceType: 'Document', requestStage: 'Response' }] };
+/**
+ * The body is read only for a text attachment of known, small size. Reading it holds the whole file
+ * in memory, so a large or binary download keeps its status and headers and gets no body: a body
+ * check on it stays undecidable rather than costing the run its memory.
+ */
+const MAX_BODY_READ_BYTES = 1024 * 1024;
+const TEXTUAL = /text\/|json|csv|xml/i;
+function readableBodySize(headers) {
+    const length = Number(headers['content-length']);
+    return (Number.isFinite(length) &&
+        length <= MAX_BODY_READ_BYTES &&
+        TEXTUAL.test(headers['content-type'] ?? ''));
+}
+async function readBody(cdp, requestId) {
+    try {
+        const got = (await cdp.send('Fetch.getResponseBody', { requestId }));
+        if ('string' !== typeof got.body) {
+            return undefined;
+        }
+        return true === got.base64Encoded ? Buffer.from(got.body, 'base64').toString('utf8') : got.body;
+    }
+    catch {
+        return undefined;
+    }
+}
+function headersOf(raw) {
+    const headers = {};
+    if (!Array.isArray(raw)) {
+        return headers;
+    }
+    for (const entry of raw) {
+        const { name, value } = (entry ?? {});
+        if ('string' === typeof name && 'string' === typeof value) {
+            headers[name.toLowerCase()] = value;
+        }
+    }
+    return headers;
+}
+function isAttachment(headers) {
+    return /^\s*attachment\b/i.test(headers['content-disposition'] ?? '');
+}
+async function onPaused(cdp, paused, emit, pageUrl) {
+    const requestId = 'string' === typeof paused.requestId ? paused.requestId : undefined;
+    try {
+        const headers = headersOf(paused.responseHeaders);
+        const url = paused.request?.url;
+        const status = paused.responseStatusCode;
+        if (isAttachment(headers) && 'string' === typeof url && 'number' === typeof status) {
+            const method = paused.request?.method;
+            const responseBody = requestId !== undefined && readableBodySize(headers)
+                ? await readBody(cdp, requestId)
+                : undefined;
+            emit(buildNetworkDetail({
+                url,
+                ...('string' === typeof method ? { method } : {}),
+                status,
+                headers,
+                resourceType: 'document',
+                ...(responseBody === undefined ? {} : { responseBody }),
+                pageUrl: pageUrl(),
+            }, drivenRedactionPolicy()));
+        }
+    }
+    catch {
+        // Recording is best-effort; letting the response through below is not.
+    }
+    if (requestId !== undefined) {
+        await cdp.send('Fetch.continueRequest', { requestId }).catch(() => undefined);
+    }
+}
+export async function attachDownloadCapture(cdp, emit, pageUrl) {
+    cdp.on('Fetch.requestPaused', (event) => {
+        void onPaused(cdp, event ?? {}, emit, pageUrl);
+    });
+    await cdp.send('Fetch.enable', DOCUMENT_RESPONSES);
+}

package/dist/portal/input/network-detail.d.ts

@@ -49,6 +49,10 @@ export interface NetworkDetail {
      * Omitted when the whole body fits, so the caveat means something when it appears.
      */
     requestBodyTruncated?: boolean;
+    /** The response body, captured only where the page cannot (a server-sent download); capped. */
+    responseBody?: string;
+    /** True when `responseBody` was cut to the cap: a body check on the rest cannot be decided. */
+    responseBodyTruncated?: boolean;
     /**
      * The document that ISSUED the request, which is what identifies the session it belongs to.
      *
@@ -73,6 +77,8 @@ export declare function buildNetworkDetail(raw: {
     headers: Record<string, string>;
     resourceType?: string;
     requestBody?: string;
+    /** The response body, when the capture could read it (a server-sent download). */
+    responseBody?: string;
     pageUrl?: string;
 }, policy?: RedactionPolicy): NetworkDetail;
 /** The minimal Playwright surfaces this attachment reads — kept structural so it's fake-testable. */

package/dist/portal/input/network-detail.js

@@ -19,8 +19,9 @@ const DEFAULT_POLICY = { isSensitiveKey: defaultIsSensitiveKey };
  * which is key-based over a parsed object — not string-shaped.
  */
 function redactByKey(value, policy) {
-    if (Array.isArray(value))
+    if (Array.isArray(value)) {
         return value.map((v) => redactByKey(v, policy));
+    }
     if (value !== null && 'object' === typeof value) {
         const out = {};
         for (const [k, v] of Object.entries(value)) {
@@ -86,6 +87,10 @@ function projectHeaders(headers, policy) {
  * about the function's inputs.
  */
 export function buildNetworkDetail(raw, policy = DEFAULT_POLICY) {
+    // Capped and redacted exactly like the request body, and the cut is declared the same way.
+    const responseBody = raw.responseBody === undefined || 0 === raw.responseBody.length
+        ? undefined
+        : projectWireBody(raw.responseBody, policy);
     const wireBody = raw.requestBody === undefined || 0 === raw.requestBody.length
         ? undefined
         : projectWireBody(raw.requestBody, policy);
@@ -101,6 +106,12 @@ export function buildNetworkDetail(raw, policy = DEFAULT_POLICY) {
                 requestBody: wireBody.body,
                 ...(wireBody.truncated ? { requestBodyTruncated: true } : {}),
             }),
+        ...(responseBody === undefined
+            ? {}
+            : {
+                responseBody: responseBody.body,
+                ...(responseBody.truncated ? { responseBodyTruncated: true } : {}),
+            }),
         ...(raw.pageUrl === undefined || 0 === raw.pageUrl.length ? {} : { pageUrl: raw.pageUrl }),
     };
 }

package/dist/portal/input/network-mock-tools.js

@@ -8,6 +8,17 @@ function mockProvider(deps) {
     const p = deps.realInput;
     return p !== undefined && 'function' === typeof p.setMocks ? p : undefined;
 }
+/**
+ * Whether this call can mock the session: a lease of this caller, or a page the driven browser has.
+ * Having a driven browser is not enough: it mocks its own page, whatever session was named.
+ */
+async function canMock(deps, session) {
+    if (true === deps.pool?.heldBy(session.id, deps.attachId)) {
+        return true;
+    }
+    const driven = mockProvider(deps);
+    return driven !== undefined && driven.isAvailableFor(session.url);
+}
 const ruleShape = z.object({
     urlContains: z
         .string()
@@ -22,6 +33,11 @@ const ruleShape = z.object({
         .boolean()
         .optional()
         .describe('Simulate a network failure (offline) instead of a response.'),
+    forwardTo: z
+        .string()
+        .url()
+        .optional()
+        .describe('Send the matching request on to this origin, e.g. "http://127.0.0.1:15500"; the path and query stay and the real server answers.'),
 });
 /**
  * Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes).
@@ -41,8 +57,9 @@ const ruleShape = z.object({
  * to parse.
  */
 export function toRules(value) {
-    if (value === undefined)
+    if (value === undefined) {
         return [];
+    }
     const parsed = z.array(ruleShape).safeParse(value);
     if (!parsed.success) {
         const problem = parsed.error.issues
@@ -50,23 +67,32 @@ export function toRules(value) {
             .join('; ');
         throw new Error(`reticle_network_mock could not read \`mocks\` (${problem}). Nothing was applied and mocking ` +
             'was left unchanged — an unreadable rule is NOT treated as a request to clear. A rule is ' +
-            '{ urlContains, method?, status?, body?, contentType?, delayMs?, abort? }; pass `clear: true` ' +
+            '{ urlContains, method?, status?, body?, contentType?, delayMs?, abort?, forwardTo? }; pass `clear: true` ' +
             'or an empty array if you meant to turn mocking off.');
     }
     return parsed.data.map((r) => {
         const rule = { urlContains: r.urlContains };
-        if (r.method !== undefined)
+        if (r.method !== undefined) {
             rule.method = r.method;
-        if (r.status !== undefined)
+        }
+        if (r.status !== undefined) {
             rule.status = r.status;
-        if (r.body !== undefined)
+        }
+        if (r.body !== undefined) {
             rule.body = r.body;
-        if (r.contentType !== undefined)
+        }
+        if (r.contentType !== undefined) {
             rule.contentType = r.contentType;
-        if (r.delayMs !== undefined)
+        }
+        if (r.delayMs !== undefined) {
             rule.delayMs = r.delayMs;
-        if (r.abort !== undefined)
+        }
+        if (r.abort !== undefined) {
             rule.abort = r.abort;
+        }
+        if (r.forwardTo !== undefined) {
+            rule.forwardTo = r.forwardTo;
+        }
         return rule;
     });
 }
@@ -95,7 +121,7 @@ export const NETWORK_MOCK_TOOLS = [
             mocks: z
                 .array(ruleShape)
                 .optional()
-                .describe('Interception rules, first match wins: { urlContains, method?, status?, body?, contentType?, delayMs?, abort? }. Omit or pass [] to clear.'),
+                .describe('Interception rules, first match wins: { urlContains, method?, status?, body?, contentType?, delayMs?, abort?, forwardTo? }. Omit or pass [] to clear.'),
             clear: z.boolean().optional().describe('Clear all active mocks (same as mocks: []).'),
             ...sessionIdShape,
         },
@@ -107,20 +133,30 @@ export const NETWORK_MOCK_TOOLS = [
             recommendation: z.string().optional(),
         },
         handler: async (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const session = await deps.sessions.resolveServing(asString(args['sessionId']), (s) => canMock(deps, s));
             const rules = true === args['clear'] ? [] : toRules(args['mocks']);
-            const provider = mockProvider(deps);
+            // A lease is mocked as the lease, and the driven browser mocks only a page it has. The driven
+            // provider mocks its own page whatever session was named: taken first, it mocked another tab,
+            // answered `applied: true`, and the lease's real write reached the backend.
+            const driven = mockProvider(deps);
+            const provider = driven !== undefined &&
+                deps.pool?.leaseUrl(session.id) === undefined &&
+                (await driven.isAvailableFor(session.url))
+                ? driven
+                : undefined;
             if (provider !== undefined) {
                 const applied = await provider.setMocks(session.url, rules);
-                if (applied)
+                if (applied) {
                     return mocksApplied(deps, session.id, rules.length);
+                }
             }
             // A lease is a Playwright-owned page — CDP intercept was always there, this tool just had no
             // route to it. Tried after the driven provider: when both exist, drive is the page the caller
             // means, and a lease is the fallback rather than a competitor.
             const leased = await deps.pool?.setMocksLease(session.id, rules);
-            if (true === leased)
+            if (true === leased) {
                 return mocksApplied(deps, session.id, rules.length);
+            }
             return {
                 applied: false,
                 count: 0,

package/dist/portal/input/network-mock.d.ts

@@ -26,6 +26,12 @@ export interface MockRule {
     delayMs?: number;
     /** Simulate a network failure (offline / connection refused) instead of a response. */
     abort?: boolean;
+    /**
+     * Send the request on to this origin (protocol, host and port; the path and query stay). An app that
+     * calls a fixed address (`http://localhost:5000`) can then reach its API on any port, for example when
+     * the host already uses that port. The real server answers.
+     */
+    forwardTo?: string;
 }
 /** What to do with a request after matching: fulfill a canned response, abort it, or let it through. */
 interface MockOutcome {
@@ -34,6 +40,8 @@ interface MockOutcome {
     body?: string;
     contentType?: string;
     delayMs?: number;
+    /** For `continue`: the url the request goes on with (a `forwardTo` rule). */
+    url?: string;
 }
 /**
  * Decide the outcome for a request from the active rules. Pure: no IO, no clock. The first rule

package/dist/portal/input/network-mock.js

@@ -6,12 +6,26 @@ const DEFAULT_CONTENT_TYPE = 'application/json';
  */
 export function matchMock(rules, req) {
     for (const rule of rules) {
-        if (!req.url.includes(rule.urlContains))
+        if (!req.url.includes(rule.urlContains)) {
             continue;
-        if (rule.method !== undefined && rule.method.toUpperCase() !== req.method.toUpperCase())
+        }
+        if (rule.method !== undefined && rule.method.toUpperCase() !== req.method.toUpperCase()) {
             continue;
-        if (true === rule.abort)
+        }
+        if (true === rule.abort) {
             return { kind: 'abort' };
+        }
+        if (rule.forwardTo !== undefined) {
+            const to = new URL(rule.forwardTo);
+            const next = new URL(req.url);
+            next.protocol = to.protocol;
+            next.host = to.host;
+            const outcome = { kind: 'continue', url: next.toString() };
+            if (rule.delayMs !== undefined) {
+                outcome.delayMs = rule.delayMs;
+            }
+            return outcome;
+        }
         /*
          * A rule that says only WHEN says nothing about WHAT.
          *
@@ -35,10 +49,12 @@ export function matchMock(rules, req) {
             status: rule.status ?? DEFAULT_STATUS,
             contentType: rule.contentType ?? DEFAULT_CONTENT_TYPE,
         };
-        if (rule.body !== undefined)
+        if (rule.body !== undefined) {
             outcome.body = rule.body;
-        if (rule.delayMs !== undefined)
+        }
+        if (rule.delayMs !== undefined) {
             outcome.delayMs = rule.delayMs;
+        }
         return outcome;
     }
     return { kind: 'continue' };
@@ -49,17 +65,19 @@ export async function applyOutcome(route, outcome, sleep) {
         // Sleep FIRST, then let it through: the delay is the whole perturbation, and the response that
         // comes back is the server's own. Fallback, not continue: a lease's context route (the CSP
         // widening, #2016) must still see the request.
-        if (outcome.delayMs !== undefined && outcome.delayMs > 0)
+        if (outcome.delayMs !== undefined && outcome.delayMs > 0) {
             await sleep(outcome.delayMs);
-        await route.fallback();
+        }
+        await (outcome.url === undefined ? route.fallback() : route.fallback({ url: outcome.url }));
         return;
     }
     if ('abort' === outcome.kind) {
         await route.abort('failed');
         return;
     }
-    if (outcome.delayMs !== undefined && outcome.delayMs > 0)
+    if (outcome.delayMs !== undefined && outcome.delayMs > 0) {
         await sleep(outcome.delayMs);
+    }
     await route.fulfill({
         status: outcome.status ?? DEFAULT_STATUS,
         contentType: outcome.contentType ?? DEFAULT_CONTENT_TYPE,
@@ -74,8 +92,9 @@ const realSleep = (ms) => new Promise((res) => setTimeout(res, ms));
  */
 export async function installNetworkMocks(page, rules, sleep = realSleep) {
     await page.unroute('**/*').catch(() => undefined);
-    if (0 === rules.length)
+    if (0 === rules.length) {
         return;
+    }
     await page.route('**/*', (route) => {
         const req = route.request();
         const outcome = matchMock(rules, { url: req.url(), method: req.method() });

package/dist/portal/input/page-capture.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A screenshot of a Playwright page, shared by the CDP and launched providers so the capture path
+ * lives in one place.
+ */
+import type { Page } from 'playwright';
+import type { ElementBox } from './real-input.js';
+/** Options for a page screenshot — full-page scroll capture and/or a clip box. */
+export interface ScreenshotOpts {
+    fullPage?: boolean;
+    /** Restrict the capture to one element/region (viewport CSS px). */
+    clip?: ElementBox;
+    /**
+     * A live picture, as a JPEG at this quality: what a person is watching, taken as it is. The
+     * baseline tweaks (hiding the HUD, stopping animations) would make their window flicker each second.
+     */
+    jpegQuality?: number;
+    /** One image pixel per CSS pixel, so a high-density display does not double a step screenshot. */
+    cssScale?: boolean;
+}
+/**
+ * Capture a PNG from a Playwright page. Shared by the CDP + launched providers so the
+ * screenshot path lives in one place (mirrors performGesture). Returns the raw PNG bytes.
+ */
+export declare function capturePage(page: Page, opts: ScreenshotOpts): Promise<Uint8Array>;

package/dist/portal/input/page-capture.js

@@ -0,0 +1,33 @@
+import { SCREENSHOT_DETERMINISM, captureWithChromeHidden, } from '../pool/playwright-launcher.js';
+/**
+ * Capture a PNG from a Playwright page. Shared by the CDP + launched providers so the
+ * screenshot path lives in one place (mirrors performGesture). Returns the raw PNG bytes.
+ */
+export async function capturePage(page, opts) {
+    // A step capture injects nothing into the page, so Reticle's own hosts are hidden another way.
+    if (true === opts.cssScale) {
+        return captureWithChromeHidden({ evaluate: (script) => page.evaluate(script) }, () => shoot(page, opts));
+    }
+    return shoot(page, opts);
+}
+/** Playwright screenshot options for one capture: a JPEG, a clip, the full page, or the viewport. */
+function screenshotOptions(opts) {
+    if (opts.jpegQuality !== undefined) {
+        return {
+            type: 'jpeg',
+            quality: opts.jpegQuality,
+            ...(true === opts.cssScale ? { scale: 'css' } : {}),
+        };
+    }
+    if (opts.clip !== undefined) {
+        return { ...SCREENSHOT_DETERMINISM, clip: opts.clip };
+    }
+    if (true === opts.fullPage) {
+        return { ...SCREENSHOT_DETERMINISM, fullPage: true };
+    }
+    return { ...SCREENSHOT_DETERMINISM };
+}
+async function shoot(page, opts) {
+    const buf = await page.screenshot(screenshotOptions(opts));
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}