@reticlehq/server 3.9.0 → 3.10.1

package/dist/portal/input/real-input.d.ts

@@ -12,7 +12,7 @@
 import { type ScriptCoverage } from './js-coverage.js';
 import type { Browser, Page } from 'playwright';
 import { DriveError } from './drive-error.js';
-import { ActionType, InputMode } from '@reticlehq/core';
+import { ActionType, InputMode, type BoxFraction } from '@reticlehq/core';
 import { type MockRule } from './network-mock.js';
 import { type NetworkDetail } from './network-detail.js';
 /** Viewport CSS-px box as returned by the INSPECT command (getBoundingClientRect). */
@@ -49,8 +49,12 @@ export type RealInputArgs = {
      * for exactly as long as one driven in the page.
      */
     holdMs?: number;
-    /** For drag: the resolved box of the drop-target ref (toRef). */
+    /** For drag: the resolved box of the drop-target ref (toRef), or the source box for `to` alone. */
     toBox?: ElementBox;
+    /** For a pointer action: the point inside the box, as fractions of it. Absent means the centre. */
+    at?: BoxFraction;
+    /** For drag: the end point inside `toBox`, as fractions of it. Absent means its centre. */
+    to?: BoxFraction;
     steps?: number;
 };
 /** What a provider reports for one driven gesture. Exported so a fake can build it by name. */
@@ -80,19 +84,8 @@ export interface RealInputResult {
      */
     heldMs?: number;
 }
-/** 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;
-}
+export { capturePage, type ScreenshotOpts } from './page-capture.js';
+import { type ScreenshotOpts } from './page-capture.js';
 /** The capability surface reticle_act depends on. A FAKE implementing this is injected in tests. */
 export interface RealInputProvider {
     /** Whether a Playwright Page currently matches this SDK session URL. */
@@ -120,6 +113,14 @@ export interface RealInputProvider {
      */
     storageState?(sessionUrl: string): Promise<unknown>;
     applyStorageState?(sessionUrl: string, state: unknown): Promise<boolean>;
+    /**
+     * Close every page of the driven context except the one this provider drives, and say how many.
+     *
+     * A flow that opens another tab (a modifier-click on a link) leaves it behind; its page connects
+     * as a second session, and everything after that asks for "the" session and is refused. Optional:
+     * only a provider that owns its context can know which pages are its own.
+     */
+    closeOtherPages?(): Promise<number>;
     /**
      * Install (or replace, or with [] clear) network-mock rules on the correlated page — stub a 500,
      * force offline, delay a response — for deterministic error/edge-state testing. Returns true when
@@ -162,6 +163,11 @@ export declare function boxCenter(box: ElementBox): {
     cx: number;
     cy: number;
 };
+/** The point `at` names inside a box, or its centre when `at` is absent. */
+export declare function boxPoint(box: ElementBox, at: BoxFraction | undefined): {
+    cx: number;
+    cy: number;
+};
 /**
  * Which actions are driven by a native pointer. `press` is excluded on purpose — a key has no
  * pointer, and widening this would change what every existing caller of it means.
@@ -191,11 +197,6 @@ now?: () => number): Promise<RealInputResult>;
 export declare function withChromePassThrough<T>(page: {
     evaluate: (script: string) => Promise<unknown>;
 }, gesture: () => Promise<T>): Promise<T>;
-/**
- * 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>;
 interface CdpProviderOptions {
     cdpUrl: string;
     /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
@@ -297,6 +298,7 @@ export declare class LaunchedRealInputProvider implements OwnedRealInputProvider
      * driven session had no fixture port at all, and every suite seeded nothing while reading as if it
      * seeded everything. Same two methods, same contract, one page instead of a page lookup.
      */
+    closeOtherPages(): Promise<number>;
     storageState(_sessionUrl: string): Promise<unknown>;
     /**
      * Put a captured state back: cookies through the context, per-origin storage through the page.

package/dist/portal/input/real-input.js

@@ -15,20 +15,33 @@ import { pressViaKeyboard } from './real-input-press.js';
 import { stampedDriveUrl } from './drive-url-stamp.js';
 import { launchChromium } from '../../launch-chromium.js';
 import { pageViewportOptions } from '../../chromium-launch-options.js';
-import { chromiumLaunchHint, gotoOptions, SCREENSHOT_DETERMINISM, captureWithChromeHidden, } from '../pool/playwright-launcher.js';
+import { chromiumLaunchHint, gotoOptions } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
-import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG, ClickButton, clickButtonFromArgs, InputMode, pressModifiersFromArgs, RETICLE_CHROME_PASS_THROUGH_SCRIPT, RETICLE_CHROME_RESTORE_POINTER_SCRIPT, } from '@reticlehq/core';
+import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG, ClickButton, clickButtonFromArgs, InputMode, pointInBox, pressModifiersFromArgs, RETICLE_CHROME_PASS_THROUGH_SCRIPT, RETICLE_CHROME_RESTORE_POINTER_SCRIPT, } from '@reticlehq/core';
 import { installNetworkMocks } from './network-mock.js';
 import { attachNetworkDetail } from './network-detail.js';
+import { attachDownloadCapture } from './download-capture.js';
 import { injectedConnectArgs } from '../pool/zero-install.js';
+import { EARLY_CAPTURE_ARG, queueEarlyConsole } from '../pool/lease-page-error.js';
+// The screenshot capture lives in page-capture.ts; re-exported for existing importers.
+export { capturePage } from './page-capture.js';
+import { capturePage } from './page-capture.js';
 export { DriveError };
 export { unspellablePressReason } from './real-input-press.js';
 /** Center of a viewport box in CSS px. Pure — unit-tested directly. */
 export function boxCenter(box) {
     return { cx: box.x + box.width / 2, cy: box.y + box.height / 2 };
 }
+/** The point `at` names inside a box, or its centre when `at` is absent. */
+export function boxPoint(box, at) {
+    if (at === undefined) {
+        return boxCenter(box);
+    }
+    const p = pointInBox(box, at);
+    return { cx: p.x, cy: p.y };
+}
 /**
  * Which actions are driven by a native pointer. `press` is excluded on purpose — a key has no
  * pointer, and widening this would change what every existing caller of it means.
@@ -107,7 +120,7 @@ export async function withChromePassThrough(page, gesture) {
 }
 /** The pointer half of `performGesture`: every action that lands at a point. */
 async function pointerGesture(page, action, box, args, sleep) {
-    const center = boxCenter(box);
+    const center = boxPoint(box, args.at);
     const { cx, cy } = center;
     const real = (performed) => ({
         performed,
@@ -147,7 +160,7 @@ async function pointerGesture(page, action, box, args, sleep) {
         if (args.toBox === undefined) {
             return real(false);
         }
-        const dst = boxCenter(args.toBox);
+        const dst = boxPoint(args.toBox, args.to);
         const steps = args.steps ?? DEFAULT_DRAG_STEPS;
         await page.mouse.move(cx, cy);
         await page.mouse.down();
@@ -166,31 +179,6 @@ async function pointerGesture(page, action, box, args, sleep) {
     }
     return real(false);
 }
-/**
- * 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);
-}
-async function shoot(page, opts) {
-    const buf = await page.screenshot(opts.jpegQuality !== undefined
-        ? {
-            type: 'jpeg',
-            quality: opts.jpegQuality,
-            ...(true === opts.cssScale ? { scale: 'css' } : {}),
-        }
-        : opts.clip !== undefined
-            ? { ...SCREENSHOT_DETERMINISM, clip: opts.clip }
-            : true === opts.fullPage
-                ? { ...SCREENSHOT_DETERMINISM, fullPage: true }
-                : { ...SCREENSHOT_DETERMINISM });
-    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-}
 const nodeSleep = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });
@@ -433,9 +421,19 @@ export class LaunchedRealInputProvider {
             ...(this.#storageState !== undefined ? { storageState: this.#storageState } : {}),
         });
         this.#page = page;
+        // Before goto: a console error the page logs while it loads comes before its SDK connects.
+        await page.addInitScript(queueEarlyConsole, EARLY_CAPTURE_ARG);
         // Capture CDP-authoritative response detail into the driven session's journal (best-effort).
-        if (this.#onNetworkDetail !== undefined) {
-            attachNetworkDetail(page, this.#onNetworkDetail);
+        const sink = this.#onNetworkDetail;
+        if (sink !== undefined) {
+            attachNetworkDetail(page, sink);
+            // A server-sent download never reaches the page's network events; CDP request interception
+            // does see it (download-capture.ts). Attached before the first navigation, best-effort.
+            await page
+                .context()
+                .newCDPSession(page)
+                .then((cdp) => attachDownloadCapture(cdp, sink, () => page.url()))
+                .catch(() => undefined);
         }
         try {
             // Same navigation rule as the pool, and for the same measured reason: Playwright's default
@@ -538,6 +536,18 @@ export class LaunchedRealInputProvider {
      * driven session had no fixture port at all, and every suite seeded nothing while reading as if it
      * seeded everything. Same two methods, same contract, one page instead of a page lookup.
      */
+    async closeOtherPages() {
+        const page = this.#livePage();
+        if (page === undefined) {
+            return 0;
+        }
+        const others = page
+            .context()
+            .pages()
+            .filter((other) => other !== page && !other.isClosed());
+        await Promise.all(others.map((other) => other.close()));
+        return others.length;
+    }
     async storageState(_sessionUrl) {
         const page = this.#livePage();
         if (page === undefined) {

package/dist/portal/input/viewport-tools.d.ts

@@ -10,6 +10,10 @@ export declare const REDUCED_MOTION_ARG: z.ZodOptional<z.ZodEnum<{
     reduce: "reduce";
     "no-preference": "no-preference";
 }>>;
+export declare const POINTER_ARG: z.ZodOptional<z.ZodEnum<{
+    fine: "fine";
+    coarse: "coarse";
+}>>;
 export declare const LEASE_EMULATE_ARG: z.ZodOptional<z.ZodObject<{
     colorScheme: z.ZodOptional<z.ZodEnum<{
         light: "light";
@@ -22,6 +26,10 @@ export declare const LEASE_EMULATE_ARG: z.ZodOptional<z.ZodObject<{
     }>>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
+    pointer: z.ZodOptional<z.ZodEnum<{
+        fine: "fine";
+        coarse: "coarse";
+    }>>;
 }, z.core.$strict>>;
 /** The media part of what a caller asked for, or undefined when it asked for none. */
 export declare function mediaOf(raw: {

package/dist/portal/input/viewport-tools.js

@@ -4,11 +4,12 @@ import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { MAX_VIEWPORT_PX, MIN_VIEWPORT_PX, viewportPxSchema, } from '../../surface/tools/args/numeric-bounds.js';
 import { asString } from '@reticlehq/core';
-import { ColorScheme, ReducedMotion, } from '../pool/lease-emulation.js';
+import { HEADLESS_VIEWPORT } from '../../chromium-launch-options.js';
+import { ColorScheme, Pointer, ReducedMotion, } from '../pool/lease-emulation.js';
 // ── Media and width, as a tool call names them (reticle_viewport here, reticle_lease acquire) ──
-/** Playwright's own default page size, used for the side a caller did not name. */
-const DEFAULT_WIDTH = 1280;
-const DEFAULT_HEIGHT = 720;
+/** The side a caller did not name is the page size a headless lease already opens with. */
+const DEFAULT_WIDTH = HEADLESS_VIEWPORT.width;
+const DEFAULT_HEIGHT = HEADLESS_VIEWPORT.height;
 export const COLOR_SCHEME_ARG = z
     .enum([ColorScheme.LIGHT, ColorScheme.DARK, ColorScheme.NO_PREFERENCE])
     .optional()
@@ -17,16 +18,24 @@ export const REDUCED_MOTION_ARG = z
     .enum([ReducedMotion.REDUCE, ReducedMotion.NO_PREFERENCE])
     .optional()
     .describe('prefers-reduced-motion for this page: reduce or no-preference.');
+export const POINTER_ARG = z
+    .enum([Pointer.FINE, Pointer.COARSE])
+    .optional()
+    .describe('The primary pointer this page reports to @media (pointer: ...): fine (a mouse) or coarse (touch). ' +
+    'Settable only when the lease opens, because touch support is fixed for a browser context.');
 const EmulateSchema = z
     .object({
     colorScheme: COLOR_SCHEME_ARG,
     reducedMotion: REDUCED_MOTION_ARG,
     width: viewportPxSchema.optional(),
     height: viewportPxSchema.optional(),
+    pointer: POINTER_ARG,
 })
     .strict();
-export const LEASE_EMULATE_ARG = EmulateSchema.optional().describe('Open the lease with these set before the first paint: { colorScheme, reducedMotion, width, height }. ' +
-    'A side you leave out keeps its default (1280 by 720). Change them later with reticle_viewport.');
+export const LEASE_EMULATE_ARG = EmulateSchema.optional().describe('Open the lease with these set before the first paint: { colorScheme, reducedMotion, width, height, pointer }. ' +
+    'A side you leave out keeps its default (1440 by 900). Change the media and the size later with ' +
+    'reticle_viewport; `pointer` cannot change on an open lease, so a touch-only rule needs a lease ' +
+    'acquired with pointer: "coarse".');
 /** The media part of what a caller asked for, or undefined when it asked for none. */
 export function mediaOf(raw) {
     const parsed = EmulateSchema.pick({ colorScheme: true, reducedMotion: true }).parse({
@@ -41,21 +50,27 @@ export function mediaOf(raw) {
 }
 /** A lease's `emulate` argument, read; a value it does not know is refused by name. */
 export function leaseEmulationOf(raw) {
-    if (raw === undefined)
+    if (raw === undefined) {
         return undefined;
+    }
     const parsed = EmulateSchema.safeParse(raw);
     if (!parsed.success) {
         const field = parsed.error.issues[0]?.path.join('.') ?? 'emulate';
         throw new Error(`emulate.${field}: ${parsed.error.issues[0]?.message ?? 'not valid'}`);
     }
-    const { width, height } = parsed.data;
+    const { width, height, pointer } = parsed.data;
     const media = mediaOf(parsed.data);
     const viewport = width === undefined && height === undefined
         ? undefined
         : { width: width ?? DEFAULT_WIDTH, height: height ?? DEFAULT_HEIGHT };
-    if (media === undefined && viewport === undefined)
+    if (media === undefined && viewport === undefined && pointer === undefined) {
         return undefined;
-    return { ...media, ...(viewport === undefined ? {} : { viewport }) };
+    }
+    return {
+        ...media,
+        ...(viewport === undefined ? {} : { viewport }),
+        ...(pointer === undefined ? {} : { pointer }),
+    };
 }
 /** Bounds so a viewport request stays sane (and a typo can't ask for a 1px or 100k-px window). */
 const MIN_DIM = MIN_VIEWPORT_PX;
@@ -66,6 +81,25 @@ function viewportProvider(deps) {
         ? p
         : undefined;
 }
+/**
+ * Whether this caller holds the session as a lease. Another agent's lease is never this caller's
+ * to change (#1226).
+ */
+function holdsLease(deps, sessionId) {
+    return true === deps.pool?.heldBy(sessionId, deps.attachId);
+}
+/** Whether this call can resize the session: a lease of this caller, or a driven page. */
+async function canResize(deps, session) {
+    if (holdsLease(deps, session.id)) {
+        return true;
+    }
+    // A driven browser resizes only a page it has. Having a driven browser is not enough.
+    const driven = viewportProvider(deps);
+    if (driven === undefined) {
+        return false;
+    }
+    return driven.isAvailableFor(session.url);
+}
 export const VIEWPORT_TOOLS = [
     {
         name: ReticleTool.VIEWPORT,
@@ -73,12 +107,14 @@ export const VIEWPORT_TOOLS = [
             'reproducible across machines — the missing piece of CI-stable visual regression, alongside ' +
             'reticle_visual_diff `masks` and a frozen clock (reticle_clock). Set it once before reticle_screenshot / ' +
             'reticle_visual_diff. On a lease it also sets prefers-color-scheme and prefers-reduced-motion; ' +
-            'give only those to change the media and keep the size. Returns { applied, width, height, observed } or the no-provider recommendation; `observed` is the size the leased page reports after the resize.',
+            'give only those to change the media and keep the size. A `pointer` is refused here: touch support is fixed when a lease opens, so ask for it with reticle_lease acquire `emulate.pointer`. ' +
+            'Returns { applied, width, height, observed } or the no-provider recommendation; `observed` is the size the leased page reports after the resize.',
         inputSchema: {
             width: viewportPxSchema.optional().describe('Viewport width in CSS px (e.g. 1280).'),
             height: viewportPxSchema.optional().describe('Viewport height in CSS px (e.g. 800).'),
             colorScheme: COLOR_SCHEME_ARG,
             reducedMotion: REDUCED_MOTION_ARG,
+            pointer: POINTER_ARG,
             ...sessionIdShape,
         },
         outputSchema: {
@@ -88,14 +124,27 @@ export const VIEWPORT_TOOLS = [
             observed: z.object({ width: z.number(), height: z.number() }).optional(),
             colorScheme: z.string().optional(),
             reducedMotion: z.string().optional(),
+            pointer: z.string().optional(),
             ok: z.boolean().optional(),
             reason: z.string().optional(),
             recommendation: z.string().optional(),
         },
         handler: async (deps, args) => {
+            // Touch support is a Playwright context option and a lease is one context, so a pointer can
+            // only be chosen when the lease opens. Said out loud instead of dropped: a silently ignored
+            // `pointer` would hand back a verdict about a touch-only rule that was taken with a mouse.
+            if (args['pointer'] !== undefined) {
+                return {
+                    applied: false,
+                    ok: false,
+                    reason: POINTER_IS_FIXED,
+                    recommendation: POINTER_NEEDS_A_NEW_LEASE,
+                };
+            }
             const media = mediaOf(args);
             if (media !== undefined && args['width'] === undefined && args['height'] === undefined) {
-                const session = deps.sessions.resolve(asString(args['sessionId']));
+                // Only a lease can set the media.
+                const session = await deps.sessions.resolveServing(asString(args['sessionId']), (s) => holdsLease(deps, s.id));
                 if (true === (await deps.pool?.emulateLease(session.id, media))) {
                     // No size was asked for, so answer the one the lease has; 0 by 0 reads as a broken
                     // viewport (#1902). When the page cannot be read, leave the size out.
@@ -106,7 +155,7 @@ export const VIEWPORT_TOOLS = [
             }
             const width = clampDim('width', args['width']);
             const height = clampDim('height', args['height']);
-            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const session = await deps.sessions.resolveServing(asString(args['sessionId']), (s) => canResize(deps, s));
             // A lease is resized as the lease. The driven provider resizes its own page, whatever
             // session was named, so taking it first resized the wrong tab and said `applied: true`.
             const driven = viewportProvider(deps);
@@ -114,10 +163,12 @@ export const VIEWPORT_TOOLS = [
             if (provider !== undefined) {
                 const applied = await provider.setViewport(session.url, { width, height });
                 // The driven page takes the size; its media stay as the person's browser has them.
-                if (applied && media === undefined)
+                if (applied && media === undefined) {
                     return { applied: true, width, height };
-                if (applied)
+                }
+                if (applied) {
                     return { applied: true, width, height, recommendation: MEDIA_NEEDS_A_LEASE };
+                }
             }
             // A lease is a Playwright-owned page, so the resize was always possible — this tool just had
             // no route to it. Tried after the driven provider, on the same rule reticle_network_mock
@@ -128,16 +179,18 @@ export const VIEWPORT_TOOLS = [
             // only mounts under a breakpoint — could not be driven at a desktop viewport at all, and the
             // recommendation printed alongside the refusal asked the reader to install a second browser.
             const leased = await deps.pool?.setViewportLease(session.id, { width, height });
-            if (true !== leased)
+            if (true !== leased) {
                 return refused();
+            }
             // What the page reports after the resize, so `applied` is a reading and not a hope.
             const observed = await deps.pool?.viewportOfLease(session.id);
             if (observed !== undefined && (observed.width !== width || observed.height !== height)) {
                 return { applied: false, width, height, observed, ok: false, reason: VIEWPORT_NOT_TAKEN };
             }
             const seen = observed === undefined ? {} : { observed };
-            if (media === undefined)
+            if (media === undefined) {
                 return { applied: true, width, height, ...seen };
+            }
             if (true === (await deps.pool?.emulateLease(session.id, media))) {
                 return { applied: true, width, height, ...seen, ...media };
             }
@@ -147,6 +200,9 @@ export const VIEWPORT_TOOLS = [
 ];
 /** The resize went through, but the page still reports another size. */
 const VIEWPORT_NOT_TAKEN = 'the page still reports the size in `observed` after the resize, so the size was not applied';
+/** Touch support rides on the browser context, so an open lease's pointer cannot be changed. */
+const POINTER_IS_FIXED = "a lease's pointer is fixed when its context opens, so it cannot be changed on a live lease";
+const POINTER_NEEDS_A_NEW_LEASE = 'Acquire a new lease with emulate.pointer: reticle_lease { action: "acquire", emulate: { pointer: "coarse" } }, then call this again with its sessionId.';
 /** prefers-color-scheme and prefers-reduced-motion are set on a leased page only. */
 const MEDIA_NEEDS_A_LEASE = 'Media features are set on a leased tab: open one with reticle_lease { action: "acquire", emulate }, then call this again with its sessionId.';
 function refused() {
@@ -167,8 +223,9 @@ function refused() {
  * snapshot, click and screenshot on that page read as broken (#1118).
  */
 function clampDim(key, value) {
-    if (value === undefined)
+    if (value === undefined) {
         return MIN_DIM;
+    }
     if ('number' !== typeof value || !Number.isFinite(value)) {
         throw new Error(`${ReticleTool.VIEWPORT}: \`${key}\` must be a number of CSS px, got ${JSON.stringify(value)} — NOT applied`);
     }

package/dist/portal/pool/browser-pool.d.ts

@@ -9,12 +9,12 @@
  * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
-import { type SeedStorage } from '@reticlehq/core';
-import type { Launcher, PooledMockRule, ScreenshotOptions } from './pool-contract.js';
+import type { Launcher, PooledCoverage, PooledMockRule, ScreenshotOptions } from './pool-contract.js';
 import type { RealInputArgs, RealInputResult } from '../input/real-input.js';
-import { type LeaseEmulation, type LeaseMedia } from './lease-emulation.js';
+import { type LeaseMedia } from './lease-emulation.js';
+import { type DeterminismStep } from './determinism.js';
 export type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledCookie, PooledDialog, PooledMockRule, PooledPage, PooledPageError, } from './pool-contract.js';
-import { type BrowserPoolOptions, type Lease } from './pool-lease.js';
+import { type AcquireOptions, type BrowserPoolOptions, type Lease } from './pool-lease.js';
 export { DEFAULT_LEASE_TTL_MS, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, PoolAtCapacityError, } from './pool-lease.js';
 export type { Lease } from './pool-lease.js';
 /**
@@ -119,6 +119,8 @@ export declare class BrowserPool {
      * Touches the lease like any other tool call, so hovering keeps it alive.
      */
     hoverLease(sessionId: string, x: number, y: number): Promise<boolean>;
+    /** Reload a lease with the browser cache ignored, or false when this is not a lease or its page cannot. */
+    hardReloadLease(sessionId: string): Promise<boolean>;
     /** Set a live lease's media features, or false when this is not a lease or its page cannot. */
     emulateLease(sessionId: string, media: LeaseMedia): Promise<boolean>;
     /** Whether this lease's page is still loading. False for a non-lease, or a page that cannot say. */
@@ -155,6 +157,10 @@ export declare class BrowserPool {
         height: number;
     } | undefined>;
     setMocksLease(sessionId: string, rules: readonly PooledMockRule[]): Promise<boolean>;
+    /** Step a deterministic lease's clock by `frames` frames; undefined when it is not one. */
+    stepLease(sessionId: string, frames: number): Promise<DeterminismStep | undefined>;
+    /** The JS coverage of a lease's page, or undefined when this is not a lease or cannot measure. */
+    coverageOf(sessionId: string): PooledCoverage | undefined;
     /** Guard a leased page's requests, or false when this is not a lease or its page cannot. */
     guardLease(sessionId: string, decide: (method: string, url: string) => string | undefined): Promise<boolean>;
     /** What a lease was granted when it opened, or undefined for a session that is not a lease. */
@@ -207,31 +213,7 @@ export declare class BrowserPool {
      * waits FIFO until a slot frees (or until `signal` aborts, if provided), unless `whenFull` is
      * `'refuse'`: then it throws {@link PoolAtCapacityError} at once and claims nothing.
      */
-    acquire(url: string, opts?: {
-        signal?: AbortSignal;
-        /**
-         * `'wait'` (the default) queues behind the cap. `'refuse'` is for a caller that has a person
-         * or an agent waiting on the answer and no way to see a queue: it is told the pool is full.
-         */
-        whenFull?: 'wait' | 'refuse';
-        sessionId?: string;
-        seedStorage?: SeedStorage;
-        owner?: string;
-        /** In a browser with a window the person can watch. */
-        headed?: boolean;
-        /**
-         * JavaScript installed before any page script runs, for this lease only. A view built for a
-         * desktop shell calls bindings the shell injects (`window.go`, `window.runtime`, a preload
-         * object) on mount; a stub here is what lets it reach its data path in a leased tab.
-         */
-        initScript?: string;
-        /** Granted on the lease's origin before the first navigation, so the first render sees them. */
-        permissions?: readonly string[];
-        /** Accept a self-signed or local-CA dev certificate for this lease's context only (#1255). */
-        ignoreHTTPSErrors?: boolean;
-        /** Media and viewport set on the context, so the first paint already has them. */
-        emulate?: LeaseEmulation;
-    }): Promise<Lease>;
+    acquire(url: string, opts?: AcquireOptions): Promise<Lease>;
     /**
      * The websocket address this lease's page reported it could not reach, if it reported one.
      *

package/dist/portal/pool/browser-pool.js

@@ -16,7 +16,8 @@ import { seedStorageInto, targetOriginOf } from './storage-seed.js';
 import { installLeaseMarker, leaseMarkerOf } from './lease-marker-stamp.js';
 import { grantLeasePermissions, grantLocalNetworkAccess, readNotificationPermission, widenLeaseCsp, } from './context-permissions.js';
 import { readViewport } from './lease-emulation.js';
-import { NotHtmlDocumentError, READER_NOT_HTML } from './zero-install.js';
+import { injectReaderInto } from './zero-install.js';
+import { stepPage } from './determinism.js';
 import { DEFAULT_LEASE_TTL_MS, DEFAULT_NAV_TIMEOUT_MS, INIT_SCRIPT_UNSUPPORTED, MAX_REMEMBERED_REAPED_LEASES, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, navStatusOf, pageLoading, PoolAtCapacityError, } from './pool-lease.js';
 import { listenForPageErrors, reportLeaseClosed, } from './lease-page-error.js';
 export { DEFAULT_LEASE_TTL_MS, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, PoolAtCapacityError, } from './pool-lease.js';
@@ -77,7 +78,7 @@ export class BrowserPool {
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
         this.#zeroInstall = opts.zeroInstallScript;
         this.#daemonOrigin = opts.daemonOrigin;
-        this.#pageErrorHooks = { onPageError: opts.onPageError, onLeaseClosed: opts.onLeaseClosed };
+        this.#pageErrorHooks = opts;
     }
     /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
     leaseTtlMs() {
@@ -303,6 +304,21 @@ export class BrowserPool {
             return false;
         }
     }
+    /** Reload a lease with the browser cache ignored, or false when this is not a lease or its page cannot. */
+    async hardReloadLease(sessionId) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease?.page.reloadIgnoringCache === undefined) {
+            return false;
+        }
+        this.touch(sessionId);
+        try {
+            await lease.page.reloadIgnoringCache();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /** Set a live lease's media features, or false when this is not a lease or its page cannot. */
     async emulateLease(sessionId, media) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
@@ -395,6 +411,17 @@ export class BrowserPool {
             return false;
         }
     }
+    /** Step a deterministic lease's clock by `frames` frames; undefined when it is not one. */
+    stepLease(sessionId, frames) {
+        const page = this.#active.get(this.#leaseIdOf(sessionId))?.page;
+        this.touch(sessionId);
+        return page === undefined ? Promise.resolve(undefined) : stepPage(page, frames);
+    }
+    /** The JS coverage of a lease's page, or undefined when this is not a lease or cannot measure. */
+    coverageOf(sessionId) {
+        this.touch(sessionId);
+        return this.#active.get(this.#leaseIdOf(sessionId))?.page.jsCoverage;
+    }
     /** Guard a leased page's requests, or false when this is not a lease or its page cannot. */
     async guardLease(sessionId, decide) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
@@ -513,6 +540,7 @@ export class BrowserPool {
             const browser = await this.#ensureBrowser(slot);
             const contextOpts = {
                 ...(true === opts.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
+                ...(true === opts.jsCoverage ? { jsCoverage: true } : {}),
                 ...opts.emulate,
             };
             context = await browser.newContext(0 < Object.keys(contextOpts).length ? contextOpts : undefined);
@@ -552,9 +580,8 @@ export class BrowserPool {
                     pending = dialled;
                 } // logged during goto, before the lease is registered below
             });
-            // Same "listen before goto" reasoning as onConsole above: a dialog opened during the initial
-            // navigation (an app that confirms something in an onload handler) must still be dismissed, not
-            // just ones opened after the lease is registered.
+            // Listen before goto, as onConsole does: a dialog in an onload handler is dismissed too. The SDK
+            // answers a dialog from its own input first; the hook records this "no" for the verdict (#1350).
             page.onDialog?.((dialog) => {
                 const active = this.#active.get(sessionId);
                 if (active !== undefined) {
@@ -564,9 +591,10 @@ export class BrowserPool {
                     pendingDialogMessage = dialog.message;
                 }
                 void dialog.dismiss();
+                this.#pageErrorHooks?.onDialog?.(sessionId, dialog);
             });
             // Listener on BEFORE goto — an import-time throw lands during it (#1966).
-            listenForPageErrors(page, sessionId, this.#pageErrorHooks);
+            await listenForPageErrors(page, sessionId, this.#pageErrorHooks);
             const marker = leaseMarkerOf(url);
             if (marker?.session === sessionId) {
                 await installLeaseMarker(page, sessionId, targetOriginOf(url), marker.project);
@@ -620,17 +648,7 @@ export class BrowserPool {
                 url,
                 ...(navStatus !== undefined ? { navStatus } : {}),
                 release: () => this.#release(sessionId),
-                injectReader: async () => {
-                    const script = this.#zeroInstall?.(url);
-                    if (script === undefined || page.evaluate === undefined) {
-                        return false;
-                    }
-                    await page.addInitScript?.(script);
-                    if (READER_NOT_HTML === (await page.evaluate(script))) {
-                        throw new NotHtmlDocumentError();
-                    }
-                    return true;
-                },
+                injectReader: () => injectReaderInto(page, this.#zeroInstall?.(url)),
                 isLoading: () => pageLoading(page),
             };
         }