@reticlehq/server 3.9.0 → 3.10.1

package/dist/portal/pool/context-permissions.d.ts

@@ -35,10 +35,24 @@ export declare function grantLocalNetworkAccess(context: PooledContext, url: str
  * instead of holding the caller.
  */
 export declare function readNotificationPermission(page: PooledPage): Promise<string | undefined>;
+/** How long the loopback CSP probe may take. Bounded because acquire waits on it. */
+export declare const CSP_PROBE_TIMEOUT_MS = 2000;
+/** The part of `fetch` the probe uses. */
+export type CspProbeFetch = (url: string, init: {
+    signal: AbortSignal;
+}) => Promise<Pick<Response, 'headers' | 'text'>>;
 /**
- * On a lease off loopback, add `daemonOrigin` to the page CSP `connect-src` (#2016). The returned
- * record gets `widenedFor` once a response was really widened, so the lease can say so.
+ * Whether the document at `url` sends a CSP (header or meta tag) that would block a dial to
+ * `daemonOrigin` (#2163). False when it cannot be asked: the lease then opens as before.
  */
-export declare function widenLeaseCsp(context: PooledContext, url: string, daemonOrigin: string | undefined): Promise<{
+export declare function pageCspBlocksDaemon(url: string, daemonOrigin: string, probe?: CspProbeFetch): Promise<boolean>;
+/**
+ * On a lease whose page's CSP would block the daemon, add `daemonOrigin` to its `connect-src`
+ * (#2016). Off loopback this always installs the route. On loopback it installs it only when a
+ * probe of the page finds a CSP that blocks the dial (#2163), because the route sees every request
+ * in the context, and a dev server that sends no CSP should not pay for it. The returned record
+ * gets `widenedFor` once a response was really widened, so the lease can say so.
+ */
+export declare function widenLeaseCsp(context: PooledContext, url: string, daemonOrigin: string | undefined, probe?: CspProbeFetch): Promise<{
     widenedFor?: string;
 }>;

package/dist/portal/pool/context-permissions.js

@@ -16,6 +16,7 @@
  * "granted" there would be reporting something the page cannot see.
  */
 import { isLoopbackHostname } from '@reticlehq/core';
+import { allowDaemonInCsp, allowDaemonInHtml } from './csp-widen.js';
 /** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
 export const NOTIFICATIONS_PERMISSION = 'notifications';
 /** Evaluated in the leased page. A string, because the pool's page surface evaluates scripts. */
@@ -106,14 +107,44 @@ export async function readNotificationPermission(page) {
         clearTimeout(timer);
     }
 }
+/** How long the loopback CSP probe may take. Bounded because acquire waits on it. */
+export const CSP_PROBE_TIMEOUT_MS = 2_000;
 /**
- * On a lease off loopback, add `daemonOrigin` to the page CSP `connect-src` (#2016). The returned
- * record gets `widenedFor` once a response was really widened, so the lease can say so.
+ * Whether the document at `url` sends a CSP (header or meta tag) that would block a dial to
+ * `daemonOrigin` (#2163). False when it cannot be asked: the lease then opens as before.
  */
-export async function widenLeaseCsp(context, url, daemonOrigin) {
+export async function pageCspBlocksDaemon(url, daemonOrigin, probe = fetch) {
+    try {
+        const response = await probe(url, { signal: AbortSignal.timeout(CSP_PROBE_TIMEOUT_MS) });
+        const header = response.headers.get('content-security-policy');
+        if (header !== null && allowDaemonInCsp(header, daemonOrigin).changed) {
+            return true;
+        }
+        if (!/html/i.test(response.headers.get('content-type') ?? '')) {
+            return false;
+        }
+        return allowDaemonInHtml(await response.text(), daemonOrigin).changed;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * On a lease whose page's CSP would block the daemon, add `daemonOrigin` to its `connect-src`
+ * (#2016). Off loopback this always installs the route. On loopback it installs it only when a
+ * probe of the page finds a CSP that blocks the dial (#2163), because the route sees every request
+ * in the context, and a dev server that sends no CSP should not pay for it. The returned record
+ * gets `widenedFor` once a response was really widened, so the lease can say so.
+ */
+export async function widenLeaseCsp(context, url, daemonOrigin, probe) {
     const widening = {};
-    if (daemonOrigin !== undefined && offLoopbackOrigin(url) !== undefined) {
-        await context.widenCsp?.(daemonOrigin, () => {
+    if (daemonOrigin === undefined || context.widenCsp === undefined) {
+        return widening;
+    }
+    const needed = offLoopbackOrigin(url) !== undefined ||
+        (URL.canParse(url) && (await pageCspBlocksDaemon(url, daemonOrigin, probe)));
+    if (needed) {
+        await context.widenCsp(daemonOrigin, () => {
             widening.widenedFor = daemonOrigin;
         });
     }

package/dist/portal/pool/determinism.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A deterministic lease: the same page, driven the same way, gives the same pixels and text.
+ *
+ * Two runs of a canvas game differ because time and randomness differ. This script replaces both
+ * before any page script runs. Math.random and crypto take values from a seeded generator. Date,
+ * performance.now, the timers and requestAnimationFrame read a virtual clock that starts at a fixed
+ * epoch. The clock moves only when the caller steps frames, through `reticle_clock { stepFrames }`.
+ *
+ * The SDK in the page must keep real time, or it cannot wait, reconnect or send its heartbeat. The
+ * script keeps the real timers under `DETERMINISM_GLOBAL_KEY`, and the SDK reads them from there.
+ */
+import { z } from 'zod';
+/** What the caller asks for. */
+export interface DeterminismOptions {
+    seed?: number;
+    /** The value of `navigator.platform`, for example "Linux x86_64". Absent keeps the real one. */
+    platform?: string;
+}
+/** What the page script is given. Plain data, because Playwright sends it as JSON. */
+export interface DeterminismConfig {
+    key: string;
+    seed: number;
+    epochMs: number;
+    frameMs: number;
+    platform?: string;
+}
+/** What one step reports: the frames stepped since the page loaded, and the virtual time. */
+export interface DeterminismStep {
+    frame: number;
+    nowMs: number;
+}
+export declare const DeterminismSchema: z.ZodObject<{
+    seed: z.ZodOptional<z.ZodNumber>;
+    platform: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const LEASE_DETERMINISTIC_ARG: z.ZodOptional<z.ZodObject<{
+    seed: z.ZodOptional<z.ZodNumber>;
+    platform: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+/** A lease's `deterministic` argument, read; a field it does not know is refused by name. */
+export declare function leaseDeterminismOf(raw: unknown): DeterminismOptions | undefined;
+export declare function determinismConfigOf(opts: DeterminismOptions): DeterminismConfig;
+export declare const StepFramesSchema: z.ZodNumber;
+/** Step the page's virtual clock by `frames` frames. Undefined when the page runs no such clock. */
+export declare function stepPage(page: {
+    evaluate?(script: string): Promise<unknown>;
+}, frames: number): Promise<DeterminismStep | undefined>;
+/**
+ * The page script. It must stay self-contained: Playwright sends its source text into the page, so
+ * it can read nothing from this module. The unit test runs it from its source text for that reason.
+ */
+export declare function installDeterminism(config: DeterminismConfig): void;

package/dist/portal/pool/determinism.js

@@ -0,0 +1,259 @@
+/**
+ * A deterministic lease: the same page, driven the same way, gives the same pixels and text.
+ *
+ * Two runs of a canvas game differ because time and randomness differ. This script replaces both
+ * before any page script runs. Math.random and crypto take values from a seeded generator. Date,
+ * performance.now, the timers and requestAnimationFrame read a virtual clock that starts at a fixed
+ * epoch. The clock moves only when the caller steps frames, through `reticle_clock { stepFrames }`.
+ *
+ * The SDK in the page must keep real time, or it cannot wait, reconnect or send its heartbeat. The
+ * script keeps the real timers under `DETERMINISM_GLOBAL_KEY`, and the SDK reads them from there.
+ */
+import { z } from 'zod';
+import { DETERMINISM_DEFAULT_SEED, DETERMINISM_EPOCH_MS, DETERMINISM_FRAME_MS, DETERMINISM_GLOBAL_KEY, DETERMINISM_MAX_STEP_FRAMES, } from '@reticlehq/core';
+export const DeterminismSchema = z
+    .object({
+    seed: z.number().int().min(0).max(0xffffffff).optional(),
+    platform: z.string().min(1).max(64).optional(),
+})
+    .strict();
+export const LEASE_DETERMINISTIC_ARG = DeterminismSchema.optional().describe('Make the leased tab deterministic, for canvas games and animations. Before any page script ' +
+    'runs, Math.random and crypto.getRandomValues use a seeded generator (seed, default 1). Date, ' +
+    'performance.now, setTimeout, setInterval and requestAnimationFrame use a virtual clock that ' +
+    'starts at 2026-01-01T00:00:00Z and moves only when you call reticle_clock { stepFrames: N }. ' +
+    'devicePixelRatio is 1. platform sets navigator.platform, for example "Linux x86_64". CSS ' +
+    'animations, workers and media still run on real time. Example: deterministic: { seed: 7 }.');
+/** A lease's `deterministic` argument, read; a field it does not know is refused by name. */
+export function leaseDeterminismOf(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = DeterminismSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const field = issue?.path.join('.') ?? '';
+        throw new Error(`deterministic${'' === field ? '' : `.${field}`}: ${issue?.message ?? 'not valid'}`);
+    }
+    const { seed, platform } = parsed.data;
+    return {
+        ...(seed === undefined ? {} : { seed }),
+        ...(platform === undefined ? {} : { platform }),
+    };
+}
+export function determinismConfigOf(opts) {
+    return {
+        key: DETERMINISM_GLOBAL_KEY,
+        seed: opts.seed ?? DETERMINISM_DEFAULT_SEED,
+        epochMs: DETERMINISM_EPOCH_MS,
+        frameMs: DETERMINISM_FRAME_MS,
+        ...(opts.platform === undefined ? {} : { platform: opts.platform }),
+    };
+}
+export const StepFramesSchema = z.number().int().min(1).max(DETERMINISM_MAX_STEP_FRAMES);
+const StepResultSchema = z.object({ frame: z.number(), nowMs: z.number() });
+/** Step the page's virtual clock by `frames` frames. Undefined when the page runs no such clock. */
+export async function stepPage(page, frames) {
+    if (page.evaluate === undefined) {
+        return undefined;
+    }
+    const key = JSON.stringify(DETERMINISM_GLOBAL_KEY);
+    const script = `globalThis[Symbol.for(${key})]?.step(${String(StepFramesSchema.parse(frames))})`;
+    const parsed = StepResultSchema.safeParse(await page.evaluate(script));
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * The page script. It must stay self-contained: Playwright sends its source text into the page, so
+ * it can read nothing from this module. The unit test runs it from its source text for that reason.
+ */
+export function installDeterminism(config) {
+    const g = globalThis;
+    const define = (target, name, value) => {
+        Object.defineProperty(target, name, { value, configurable: true, writable: true });
+    };
+    const getter = (target, name, value) => {
+        Object.defineProperty(target, name, { get: () => value, configurable: true });
+    };
+    // The real timers, kept before anything is replaced, for the SDK and for this script.
+    const realSetTimeout = g.setTimeout?.bind(g);
+    const realClearTimeout = g.clearTimeout?.bind(g);
+    const realFrame = 'function' === typeof g.requestAnimationFrame ? g.requestAnimationFrame.bind(g) : undefined;
+    const realPerformanceNow = g.performance?.now.bind(g.performance);
+    // Random: mulberry32, a small 32-bit generator. The same seed gives the same sequence.
+    let state = config.seed >>> 0;
+    const next = () => {
+        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;
+    };
+    g.Math.random = next;
+    const fill = (view) => {
+        const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+        for (let i = 0; i < bytes.length; i += 1) {
+            bytes[i] = Math.floor(next() * 256);
+        }
+        return view;
+    };
+    if (g.crypto !== undefined) {
+        define(g.crypto, 'getRandomValues', fill);
+        define(g.crypto, 'randomUUID', () => {
+            const b = fill(new Uint8Array(16));
+            b[6] = ((b[6] ?? 0) & 0x0f) | 0x40;
+            b[8] = ((b[8] ?? 0) & 0x3f) | 0x80;
+            const hex = Array.from(b, (n) => n.toString(16).padStart(2, '0')).join('');
+            return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+        });
+    }
+    // Clock: `elapsed` is the virtual performance.now. It moves only in `step`.
+    let elapsed = 0;
+    let frame = 0;
+    const RealDate = g.Date;
+    const wallNow = () => config.epochMs + elapsed;
+    const VirtualDate = function (...args) {
+        if (new.target === undefined) {
+            return new RealDate(wallNow()).toString();
+        }
+        return Reflect.construct(RealDate, 0 === args.length ? [wallNow()] : args, new.target);
+    };
+    VirtualDate.prototype = RealDate.prototype;
+    define(VirtualDate, 'now', wallNow);
+    define(VirtualDate, 'parse', RealDate.parse.bind(RealDate));
+    define(VirtualDate, 'UTC', RealDate.UTC.bind(RealDate));
+    g.Date = VirtualDate;
+    if (g.performance !== undefined) {
+        define(g.performance, 'now', () => elapsed);
+    }
+    let nextId = 1;
+    const timers = new Map();
+    const schedule = (cb, ms, args, repeat) => {
+        const id = nextId;
+        nextId += 1;
+        if ('function' !== typeof cb) {
+            return id;
+        }
+        const delay = Math.max(0, Number(ms) || 0);
+        const run = () => {
+            cb(...args);
+        };
+        timers.set(id, {
+            id,
+            at: elapsed + delay,
+            run,
+            ...(repeat ? { every: Math.max(1, delay) } : {}),
+        });
+        return id;
+    };
+    const cancel = (id) => {
+        timers.delete(Number(id));
+    };
+    g.setTimeout = (cb, ms, ...args) => schedule(cb, ms, args, false);
+    g.setInterval = (cb, ms, ...args) => schedule(cb, ms, args, true);
+    g.clearTimeout = cancel;
+    g.clearInterval = cancel;
+    let frames = [];
+    g.requestAnimationFrame = (cb) => {
+        const id = nextId;
+        nextId += 1;
+        if ('function' === typeof cb) {
+            frames.push({ id, cb: cb });
+        }
+        return id;
+    };
+    g.cancelAnimationFrame = (id) => {
+        frames = frames.filter((f) => f.id !== Number(id));
+    };
+    // A callback that throws is reported as the page reports it, and the rest still run. After each
+    // callback the microtasks run, as they do in a browser between two tasks.
+    const settle = () => new Promise((resolve) => {
+        if (g.MessageChannel === undefined) {
+            void Promise.resolve().then(resolve);
+            return;
+        }
+        const channel = new g.MessageChannel();
+        channel.port1.onmessage = () => {
+            resolve();
+        };
+        channel.port2.postMessage(0);
+    });
+    const invoke = async (run) => {
+        try {
+            run();
+        }
+        catch (error) {
+            realSetTimeout?.(() => {
+                throw error;
+            }, 0);
+        }
+        await settle();
+    };
+    const earliestDue = (until) => {
+        let found;
+        for (const t of timers.values()) {
+            if (t.at <= until && (found === undefined || t.at < found.at)) {
+                found = t;
+            }
+        }
+        return found;
+    };
+    const step = async (count) => {
+        for (let i = 0; i < count; i += 1) {
+            frame += 1;
+            const target = frame * config.frameMs;
+            for (let guard = 0; guard < 100000; guard += 1) {
+                const due = earliestDue(target);
+                if (due === undefined) {
+                    break;
+                }
+                elapsed = Math.max(elapsed, due.at);
+                timers.delete(due.id);
+                if (due.every !== undefined) {
+                    timers.set(due.id, { ...due, at: due.at + due.every });
+                }
+                await invoke(due.run);
+            }
+            elapsed = target;
+            const flush = frames;
+            frames = [];
+            for (const f of flush) {
+                await invoke(() => {
+                    f.cb(target);
+                });
+            }
+        }
+        return { frame, nowMs: elapsed };
+    };
+    // Keyboard labels and shortcuts differ between Mac and Linux, so the platform can be set.
+    const nav = g.navigator;
+    if (config.platform !== undefined && nav !== undefined) {
+        const platform = config.platform;
+        const families = [
+            ['Mac', 'macOS', '(Macintosh; Intel Mac OS X 10_15_7)'],
+            ['Win', 'Windows', '(Windows NT 10.0; Win64; x64)'],
+            ['Linux', 'Linux', `(X11; ${platform})`],
+        ];
+        const family = families.find(([prefix]) => platform.startsWith(prefix));
+        getter(nav, 'platform', platform);
+        if (family !== undefined) {
+            if (nav.userAgentData !== undefined) {
+                getter(nav.userAgentData, 'platform', family[1]);
+            }
+            if (nav.userAgent !== undefined) {
+                getter(nav, 'userAgent', nav.userAgent.replace(/\([^)]*\)/, family[2]));
+            }
+        }
+    }
+    Object.defineProperty(g, Symbol.for(config.key), {
+        value: {
+            step,
+            natives: {
+                setTimeout: realSetTimeout,
+                clearTimeout: realClearTimeout,
+                requestAnimationFrame: realFrame,
+                performanceNow: realPerformanceNow,
+            },
+        },
+        configurable: false,
+        enumerable: false,
+    });
+}

package/dist/portal/pool/lease-emulation.d.ts

@@ -5,6 +5,7 @@
  * so the CSS half of reduced motion and the dark theme could not be checked live. A lease is a
  * Playwright context, which takes all three before the first paint and the media again per call.
  */
+import type { DeterminismOptions } from './determinism.js';
 export declare const ColorScheme: {
     readonly LIGHT: "light";
     readonly DARK: "dark";
@@ -16,18 +17,50 @@ export declare const ReducedMotion: {
     readonly NO_PREFERENCE: "no-preference";
 };
 export type ReducedMotion = (typeof ReducedMotion)[keyof typeof ReducedMotion];
+export declare const Pointer: {
+    readonly FINE: "fine";
+    readonly COARSE: "coarse";
+};
+export type Pointer = (typeof Pointer)[keyof typeof Pointer];
 /** The media features a page reads with matchMedia. */
 export interface LeaseMedia {
     colorScheme?: ColorScheme;
     reducedMotion?: ReducedMotion;
 }
-/** What a lease opens with: the media, and a viewport. */
+/** What a lease opens with: the media, a viewport, and the pointer the page reads. */
 export interface LeaseEmulation extends LeaseMedia {
     viewport?: {
         width: number;
         height: number;
     };
+    /**
+     * The primary pointer `@media (pointer: ...)` reports. Unlike the media features, it is fixed
+     * when the context opens: Playwright's touch support is a context option, so a live lease cannot
+     * be given one. Without it a touch-only rule could not be reached at all, and a lease answered
+     * every `(pointer: coarse)` query with a mouse (#1903).
+     */
+    pointer?: Pointer;
+    /** A seeded random source and a stepped clock, installed before any page script (determinism.ts). */
+    deterministic?: DeterminismOptions;
 }
+/** The same emulation in the names Playwright's own context options use. */
+export interface ContextEmulation extends LeaseMedia {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    hasTouch?: boolean;
+    deviceScaleFactor?: number;
+}
+/**
+ * Translate a lease's emulation into context options. `pointer` is not one of Playwright's: a
+ * coarse primary pointer is what touch support produces, so it travels as `hasTouch`.
+ *
+ * Measured in real headless Chromium: `hasTouch: true` makes `(pointer: coarse)` match and
+ * `(pointer: fine)` stop matching, with `maxTouchPoints` at 1. `isMobile` does the same and also
+ * changes viewport-meta handling, so it is deliberately left out.
+ */
+export declare function contextEmulationOf(emulate: LeaseEmulation): ContextEmulation;
 /** The size a page reports for itself, or undefined when it cannot be read. */
 export declare function readViewport(page: {
     evaluate?(script: string): Promise<unknown>;

package/dist/portal/pool/lease-emulation.js

@@ -11,6 +11,24 @@ export const ColorScheme = {
     NO_PREFERENCE: 'no-preference',
 };
 export const ReducedMotion = { REDUCE: 'reduce', NO_PREFERENCE: 'no-preference' };
+export const Pointer = { FINE: 'fine', COARSE: 'coarse' };
+/**
+ * Translate a lease's emulation into context options. `pointer` is not one of Playwright's: a
+ * coarse primary pointer is what touch support produces, so it travels as `hasTouch`.
+ *
+ * Measured in real headless Chromium: `hasTouch: true` makes `(pointer: coarse)` match and
+ * `(pointer: fine)` stop matching, with `maxTouchPoints` at 1. `isMobile` does the same and also
+ * changes viewport-meta handling, so it is deliberately left out.
+ */
+export function contextEmulationOf(emulate) {
+    const { pointer, deterministic, ...rest } = emulate;
+    return {
+        ...rest,
+        ...(pointer === undefined ? {} : { hasTouch: Pointer.COARSE === pointer }),
+        // A deterministic page draws at one density on every machine.
+        ...(deterministic === undefined ? {} : { deviceScaleFactor: 1 }),
+    };
+}
 /** The page's own layout viewport, read back after a resize. */
 const VIEWPORT_READ_SCRIPT = '[window.innerWidth, window.innerHeight]';
 /** The size a page reports for itself, or undefined when it cannot be read. */

package/dist/portal/pool/lease-marker-stamp.d.ts

@@ -5,6 +5,7 @@ interface LeaseMarkerArg {
     targetOrigin: string;
     sessionParam: string;
     projectParam: string;
+    sessionStorageKey: string;
 }
 /**
  * Init script restoring the marker a server redirect dropped, so the SDK registers under the lease id.
@@ -13,6 +14,11 @@ interface LeaseMarkerArg {
  * target origin (never an identity provider's or any third party's URL), and the pool installs it
  * only when the navigated URL's marker matches this lease's id. Must stay self-contained: Playwright
  * serialises the function source into the page.
+ *
+ * It also writes the lease id to the tab session store before page scripts run. An SPA that calls
+ * `history.replaceState` on load drops the URL marker before `connect()`, and the SDK then reads
+ * the id from that store (#2026). A value the tab holds already stays: a reload holds the lease id,
+ * and a different value is one the SDK stored for an explicit `connect({ session })`.
  */
 export declare function stampLeaseMarker(arg: LeaseMarkerArg): void;
 export declare function installLeaseMarker(page: PooledPage, leaseId: string, targetOrigin: string | undefined, project: string | undefined): Promise<void>;

package/dist/portal/pool/lease-marker-stamp.js

@@ -1,4 +1,4 @@
-import { RETICLE_URL_PARAM } from '@reticlehq/core';
+import { RETICLE_SESSION_STORAGE_KEY, RETICLE_URL_PARAM } from '@reticlehq/core';
 /**
  * Init script restoring the marker a server redirect dropped, so the SDK registers under the lease id.
  * It runs only in pages of the lease's own browser context, so a person's tab at the same URL never
@@ -6,11 +6,24 @@ import { RETICLE_URL_PARAM } from '@reticlehq/core';
  * target origin (never an identity provider's or any third party's URL), and the pool installs it
  * only when the navigated URL's marker matches this lease's id. Must stay self-contained: Playwright
  * serialises the function source into the page.
+ *
+ * It also writes the lease id to the tab session store before page scripts run. An SPA that calls
+ * `history.replaceState` on load drops the URL marker before `connect()`, and the SDK then reads
+ * the id from that store (#2026). A value the tab holds already stays: a reload holds the lease id,
+ * and a different value is one the SDK stored for an explicit `connect({ session })`.
  */
 export function stampLeaseMarker(arg) {
     const win = globalThis.window;
     if (win === undefined || win.top !== win || win.location.origin !== arg.targetOrigin)
         return;
+    try {
+        if (null === win.sessionStorage.getItem(arg.sessionStorageKey)) {
+            win.sessionStorage.setItem(arg.sessionStorageKey, arg.session);
+        }
+    }
+    catch {
+        // A page with storage blocked still gets the URL marker below.
+    }
     try {
         const url = new URL(win.location.href);
         if (url.searchParams.has(arg.sessionParam))
@@ -34,6 +47,7 @@ export async function installLeaseMarker(page, leaseId, targetOrigin, project) {
         targetOrigin,
         sessionParam: RETICLE_URL_PARAM.SESSION,
         projectParam: RETICLE_URL_PARAM.PROJECT,
+        sessionStorageKey: RETICLE_SESSION_STORAGE_KEY,
     });
 }
 export function leaseMarkerOf(url) {

package/dist/portal/pool/lease-page-error.d.ts

@@ -1,29 +1,56 @@
-/**
- * The page-error side of a lease: listen for the throws the SDK will never see, and tell the
- * wiring when the lease is gone.
- *
- * An app whose module graph throws during the first navigation fires its `error` event while the
- * page still has no Reticle SDK in it — the zero-install reader is only evaluated after `goto`
- * resolves — so nothing on the page records it, and a blank page reported as a bare console-error
- * count (#1966). The server's Playwright handle is attached before the navigation, so it is the
- * one witness that cannot miss the throw. This module owns that wiring for `BrowserPool`; the
- * journal that buffers and journals what arrives lives in `page-error-journal.ts`.
- */
-import type { PooledPage, PooledPageError } from './pool-contract.js';
+import type { PooledDialog, PooledPage, PooledPageError } from './pool-contract.js';
 /** The page-error hooks `BrowserPoolOptions` carries, forwarded here verbatim. */
 export interface LeasePageErrorHooks {
     onPageError?: ((leaseId: string, error: PooledPageError) => void) | undefined;
     onLeaseClosed?: ((leaseId: string) => void) | undefined;
+    /** Each native dialog the pool dismissed. See `BrowserPoolOptions.onDialog`. */
+    onDialog?: ((leaseId: string, dialog: Pick<PooledDialog, 'kind' | 'message'>) => void) | undefined;
 }
 /**
- * Install the lease's uncaught-error listener. Call BEFORE the first navigation — the listener
- * timing is the whole fix: an import-time throw lands during `goto`, and one attached after it
- * reads a broken page as healthy. Forwarded with the lease id, because the session for this lease
- * usually does not exist yet, so the sink buffers.
+ * Install the lease's uncaught-error listener and its early console queue. Call BEFORE the first
+ * navigation — the timing is the whole fix: an import-time throw lands during `goto`, and one
+ * attached after it reads a broken page as healthy. Forwarded with the lease id, because the
+ * session for this lease usually does not exist yet, so the sink buffers.
  */
-export declare function listenForPageErrors(page: PooledPage, leaseId: string, hooks: LeasePageErrorHooks | undefined): void;
+export declare function listenForPageErrors(page: PooledPage, leaseId: string, hooks: LeasePageErrorHooks | undefined): Promise<void>;
 /**
  * Report a closed lease — manual release, reaper and crash reclaim all funnel through the pool's
  * one release path. The wiring owns whether anything was kept FOR that lease and drops it.
  */
 export declare function reportLeaseClosed(hooks: LeasePageErrorHooks | undefined, leaseId: string): void;
+/** How many console calls and error events a page keeps for an SDK that has not installed yet. */
+export declare const EARLY_CAPTURE_LIMIT = 200;
+/**
+ * The argument for `queueEarlyConsole`. Every driven page gets the same one: a pool lease, and
+ * `verify`'s own page. It looks for the SDK every `pollMs`, for at most `maxPolls` looks (30 s).
+ */
+export declare const EARLY_CAPTURE_ARG: {
+    key: string;
+    limit: number;
+    pollMs: number;
+    maxPolls: number;
+};
+interface EarlyCaptureArg {
+    key: string;
+    limit: number;
+    pollMs: number;
+    maxPolls: number;
+}
+/**
+ * Init script: keep the console errors and warnings a page logs before the SDK installs.
+ *
+ * An app connects the SDK from a module script or a bundle, and both run after the page's own
+ * classic scripts. An error such a script logs while the page loads was lost, so "no console
+ * errors" passed on a page that logged one on every load. Playwright's own console event is not a
+ * substitute: it also reports messages the browser writes itself (a failed WebSocket, which is how
+ * the SDK's own first dial can fail), and the SDK's console channel has never counted those.
+ *
+ * So this keeps the RAW calls and events. Once the SDK has wrapped the console, this hands them to
+ * it: each call goes through the console again and each event is dispatched again, so the SDK's own
+ * handlers report them and the meaning of "console error" stays the SDK's. The SDK needs no code for
+ * this, so a page that Reticle does not drive downloads nothing for it. Entries the bound did not
+ * keep are declared with one console warning. Must stay self-contained: Playwright serialises the
+ * function source into the page.
+ */
+export declare function queueEarlyConsole(arg: EarlyCaptureArg): void;
+export {};