@reticlehq/server 3.8.2 → 3.10.0

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,37 +107,55 @@ 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: {
             applied: z.boolean(),
-            width: z.number(),
-            height: z.number(),
+            width: z.number().optional(),
+            height: z.number().optional(),
             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))) {
-                    return { applied: true, width: 0, height: 0, ...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.
+                    const size = await deps.pool?.viewportOfLease(session.id);
+                    return { applied: true, ...size, ...media };
                 }
                 return { ...refused(), recommendation: MEDIA_NEEDS_A_LEASE };
             }
             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);
@@ -111,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
@@ -125,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 };
             }
@@ -144,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() {
@@ -164,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';
-export type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledCookie, PooledDialog, PooledMockRule, PooledPage, } from './pool-contract.js';
-import { type BrowserPoolOptions, type Lease } from './pool-lease.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 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';
 /**
@@ -101,6 +101,8 @@ export declare class BrowserPool {
      * reaper take it out from under a diff.
      */
     screenshotLease(sessionId: string, opts?: ScreenshotOptions): Promise<Uint8Array | undefined>;
+    /** The reason {@link screenshotLease} last failed for this session, if it did. */
+    leaseCaptureError(sessionId: string): string | undefined;
     /** The URL a lease was opened on — the one that carries its Reticle identity. */
     leaseUrl(sessionId: string): string | undefined;
     /**
@@ -117,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. */
@@ -153,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. */
@@ -205,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.
      *
@@ -243,6 +227,8 @@ export declare class BrowserPool {
     lastDialogMessage(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
+    /** The origin added to this lease's page CSP `connect-src`, or undefined if none was (#2016). */
+    cspWidenedFor(sessionId: string): string | undefined;
     /** Whether this lease's context skips certificate checks. A context cannot change it later. */
     ignoresHTTPSErrors(sessionId: string): boolean;
     /** Whether this lease lives in the headed browser. */

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

@@ -14,10 +14,12 @@ import { log } from '../../log.js';
 import { closeLeaseTab, LEASE_CLOSE_TIMED_OUT, settledWithin } from './bounded-close.js';
 import { seedStorageInto, targetOriginOf } from './storage-seed.js';
 import { installLeaseMarker, leaseMarkerOf } from './lease-marker-stamp.js';
-import { grantLeasePermissions, readNotificationPermission } from './context-permissions.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 { DEFAULT_LEASE_TTL_MS, DEFAULT_NAV_TIMEOUT_MS, INIT_SCRIPT_UNSUPPORTED, MAX_REMEMBERED_REAPED_LEASES, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, pageLoading, PoolAtCapacityError, } from './pool-lease.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';
 /**
  * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
@@ -30,6 +32,8 @@ export class BrowserPool {
     #now;
     #ttl;
     #zeroInstall;
+    #daemonOrigin;
+    #pageErrorHooks;
     #navTimeout;
     #headless;
     #headed;
@@ -73,6 +77,8 @@ export class BrowserPool {
         this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
         this.#zeroInstall = opts.zeroInstallScript;
+        this.#daemonOrigin = opts.daemonOrigin;
+        this.#pageErrorHooks = opts;
     }
     /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
     leaseTtlMs() {
@@ -109,17 +115,9 @@ export class BrowserPool {
             return undefined;
         }
         for (const [leaseId, lease] of this.#active) {
-            if (lease.owner !== owner) {
-                continue;
-            }
-            let leaseOrigin;
-            try {
-                leaseOrigin = new URL(lease.url).origin;
-            }
-            catch {
-                continue;
-            }
-            if (leaseOrigin !== origin) {
+            if (lease.owner !== owner ||
+                !URL.canParse(lease.url) ||
+                new URL(lease.url).origin !== origin) {
                 continue;
             }
             for (const [alias, id] of this.#aliases) {
@@ -247,15 +245,21 @@ export class BrowserPool {
             return undefined;
         }
         this.touch(sessionId);
+        delete lease.captureError;
         try {
             return await lease.page.screenshot(opts);
         }
-        catch {
-            // A capture that fails is not a broken lease. Report "could not capture" and leave the lease
-            // usable — the alternative is losing a working context to one bad frame.
+        catch (error) {
+            // A capture that fails is not a broken lease. Keep the reason and leave the lease usable,
+            // so the screenshot error says why the browser capture failed.
+            lease.captureError = error instanceof Error ? error.message : String(error);
             return undefined;
         }
     }
+    /** The reason {@link screenshotLease} last failed for this session, if it did. */
+    leaseCaptureError(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.captureError;
+    }
     /** The URL a lease was opened on — the one that carries its Reticle identity. */
     leaseUrl(sessionId) {
         return this.#active.get(this.#leaseIdOf(sessionId))?.url;
@@ -300,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));
@@ -392,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));
@@ -510,16 +540,17 @@ 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);
             if (opts.permissions !== undefined) {
                 await grantLeasePermissions(context, opts.permissions, url);
             }
+            await grantLocalNetworkAccess(context, url);
+            const csp = await widenLeaseCsp(context, url, this.#daemonOrigin);
             const page = await context.newPage();
-            // A caller-supplied init script is a stub of the bindings a desktop shell injects, and it has
-            // to exist before the app's first module runs. Installed here — before goto — so the very
-            // first document gets it, and kept for the lease (see hostStub) so a reload keeps it too.
+            // A desktop-shell stub must exist before the app's first module: added before goto, and kept.
             let hostStub;
             if (opts.initScript !== undefined) {
                 const added = await page.addInitScript?.(opts.initScript);
@@ -549,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) {
@@ -561,7 +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).
+            await listenForPageErrors(page, sessionId, this.#pageErrorHooks);
             const marker = leaseMarkerOf(url);
             if (marker?.session === sessionId) {
                 await installLeaseMarker(page, sessionId, targetOriginOf(url), marker.project);
@@ -593,24 +626,7 @@ export class BrowserPool {
             // Foreground it: a page opened beside other tabs can start hidden (#1351). Best-effort — a tab
             // that stays hidden is reported by name at the lease, which failing here would lose.
             await page.bringToFront?.().catch(() => undefined);
-            let navStatus;
-            if (null !== navRes && 'object' === typeof navRes && 'status' in navRes) {
-                const s = navRes.status;
-                if ('function' === typeof s) {
-                    try {
-                        const code = s.call(navRes);
-                        if ('number' === typeof code) {
-                            navStatus = code;
-                        }
-                    }
-                    catch {
-                        // ignore
-                    }
-                }
-                else if ('number' === typeof s) {
-                    navStatus = s;
-                }
-            }
+            const navStatus = navStatusOf(navRes);
             this.#active.set(sessionId, {
                 headed: slot.headed,
                 context,
@@ -620,6 +636,7 @@ export class BrowserPool {
                 touchedAt: this.#now(),
                 permissions: opts.permissions ?? [],
                 ignoresHTTPSErrors: true === opts.ignoreHTTPSErrors,
+                csp,
                 ...(pending === undefined ? {} : { dialFailureUrl: pending }),
                 ...(pendingDialogMessage === undefined ? {} : { lastDialogMessage: pendingDialogMessage }),
                 ...(hostStub === undefined || opts.initScript === undefined
@@ -631,17 +648,7 @@ export class BrowserPool {
                 url,
                 ...(navStatus !== undefined ? { navStatus } : {}),
                 release: () => this.#release(sessionId),
-                injectReader: async () => {
-                    const script = this.#zeroInstall?.();
-                    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),
             };
         }
@@ -703,6 +710,7 @@ export class BrowserPool {
             return;
         } // already released or lost to a crash
         this.#active.delete(sessionId);
+        reportLeaseClosed(this.#pageErrorHooks, sessionId);
         // Drop any alias pointing here, or the map grows for the life of the daemon and a later lease
         // reusing that registered name would resolve to a context that is already closed.
         for (const [registered, leaseId] of this.#aliases) {
@@ -863,6 +871,10 @@ export class BrowserPool {
             waiter();
         } // let them re-claim + relaunch
     }
+    /** The origin added to this lease's page CSP `connect-src`, or undefined if none was (#2016). */
+    cspWidenedFor(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.csp.widenedFor;
+    }
     /** Whether this lease's context skips certificate checks. A context cannot change it later. */
     ignoresHTTPSErrors(sessionId) {
         return true === this.#active.get(this.#leaseIdOf(sessionId))?.ignoresHTTPSErrors;

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

@@ -1,20 +1,3 @@
-/**
- * Browser permissions on a leased context: granted before the first navigation, and read back where
- * the browser can contradict the grant.
- *
- * Never changed on a lease that is already open. Acquire hands an origin's live lease to whoever asks
- * for that origin, so the lease may be another agent's tab mid-flow, and nothing here knows whose it
- * is. A different set means a fresh lease.
- *
- * Each grant is scoped to the origin the lease was opened on, so a third-party frame the app embeds
- * is not handed the same grant as the app.
- *
- * Notifications are why the read-back exists. Playwright's headless shell — what the pool launches
- * when Playwright's own Chromium is installed — has no notification support: after a grant,
- * `navigator.permissions.query` reports `granted` while `Notification.permission` still reads
- * `denied`. A page that gates its UI on the second never sees the grant, so a lease that reported
- * "granted" there would be reporting something the page cannot see.
- */
 import type { PooledContext, PooledPage } from './pool-contract.js';
 /** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
 export declare const NOTIFICATIONS_PERMISSION = "notifications";
@@ -31,6 +14,19 @@ export declare class LeasePermissionError extends Error {
 }
 /** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
 export declare function grantLeasePermissions(context: PooledContext, permissions: readonly string[], url: string): Promise<void>;
+/** The origin of `url` when the page is not on loopback, else undefined (also for no url). */
+export declare function offLoopbackOrigin(url: string | undefined): string | undefined;
+/** Playwright's name for Chrome's Local Network Access grant (local + loopback network). */
+export declare const LOCAL_NETWORK_ACCESS = "local-network-access";
+/**
+ * Let a page that is not on loopback dial the bridge on loopback. Chromium blocks that unless a
+ * person grants Local Network Access, and a leased browser has no person, so a lease on a hosted
+ * preview loaded, signed in, and answered `sdk_never_dialled`. A loopback page needs no grant.
+ *
+ * ponytail: best effort. A Playwright older than the permission name refuses it; the lease then
+ * opens as before, and a page that cannot dial still reports `sdk_never_dialled`.
+ */
+export declare function grantLocalNetworkAccess(context: PooledContext, url: string): Promise<void>;
 /**
  * What the page's `Notification.permission` says, or undefined when it cannot be asked.
  *
@@ -39,3 +35,24 @@ export declare function grantLeasePermissions(context: PooledContext, permission
  * 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'>>;
+/**
+ * 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 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;
+}>;