@reticlehq/server 3.8.1 → 3.9.0

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

@@ -10,25 +10,21 @@
  * pay for it; the type-only import is elided by `tsc`, so the build stays green without it.
  */
 import { takeJsCoverage } from './js-coverage.js';
+import { DriveError } from './drive-error.js';
+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 { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
-import { ActionType, clampHoldMs, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG, explicitCodeFromArgs, InputMode, InputModeReason, pressKeyFromArgs, pressKeysFromArgs, pressModifiersFromArgs, } from '@reticlehq/core';
+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 { installNetworkMocks } from './network-mock.js';
 import { attachNetworkDetail } from './network-detail.js';
 import { injectedConnectArgs } from '../pool/zero-install.js';
-/** Structured, code-tagged failure so callers branch on cause, not message text. */
-export class DriveError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = 'DriveError';
-    }
-}
+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 };
@@ -63,149 +59,12 @@ function undriven(action, box) {
 const REAL_INPUT_SETTLE_MS = 16;
 /** Default number of interpolation steps for a native drag. */
 const DEFAULT_DRAG_STEPS = 8;
-/**
- * Drive a `press` with a real keyboard — coordinate-free; the key goes to whatever holds focus.
- * Key and modifiers come from the same core helpers the synthetic dispatcher uses, so the two paths
- * cannot read the same args differently.
- *
- * A `holdMs` splits the chord into down / wait / up, the same shape the page uses for a held key.
- * `keyboard.press` would send it instantly instead, reporting a hold-to-confirm that never held.
- * The one thing this cannot reproduce is the auto-repeat a held key emits: the driver sends a single
- * keydown, where the in-page path sends the repeats a browser would. Named rather than papered over
- * — an app that counts repeats needs the synthetic path, and a caller that sees a held key do
- * nothing now has a reason to try it.
- */
-async function pressViaKeyboard(page, args, sleep, now) {
-    const key = pressKeyFromArgs(args);
-    const modifiers = pressModifiersFromArgs(args);
-    const chord = 0 < modifiers.length ? `${modifiers.join('+')}+${key}` : key;
-    const holdMs = clampHoldMs(args.holdMs);
-    if (0 === holdMs) {
-        // `press` DOES take a chord string ("Control+k"), so the tap path needs no splitting.
-        await page.keyboard.press(chord);
-        return 0;
-    }
-    /*
-     * `down`/`up` take ONE key each, unlike `press`: `down('Control+k')` throws
-     * `Unknown key: "Control+k"` — measured on a real Chromium, not assumed. The chord string the
-     * tap path uses therefore cannot express a hold, so the chord is split here: modifiers down in
-     * chord order, the key last, and released in reverse (key first, modifiers reversed), which is
-     * what a hand does and what an app's keyup bookkeeping expects.
-     *
-     * Without the split a held shortcut threw before a single key moved, the caller fell back to
-     * the synthetic path, and a real hold was impossible for any press with modifiers — the exact
-     * gesture `holdMs` exists for.
-     *
-     * ## Why every key that went down is tracked, and every exit path cleans up
-     *
-     * The down calls are the ones that MOVE the keyboard, and they can fail partway: `Control` goes
-     * down, the key after it rejects, and the driver's copy of `Control` is still held. That path
-     * used to fall straight to the caller's synthetic replay — which presses the same chord again on
-     * a keyboard that is already holding a modifier. Tracking what actually went down is what makes
-     * the cleanup below able to release the right keys, and only those: releasing a key that never
-     * went down is its own lie, and it would turn a clean failure into an unnecessary refusal.
-     */
-    const pressed = [];
-    const pressDown = async (k) => {
-        await page.keyboard.down(k);
-        pressed.push(k);
-    };
-    try {
-        for (const modifier of modifiers)
-            await pressDown(modifier);
-        await pressDown(key);
-    }
-    catch (error) {
-        // The chord is PARTIALLY down. Release what is held before reporting the failure; if that
-        // cannot be proved, `releaseKeys` throws RELEASE_FAILED and the caller refuses the replay —
-        // the same rule as a failed release on the ordinary path, for the same reason. Only when the
-        // cleanup DOES succeed is the original error safe to hand back.
-        await releaseKeys(page, pressed);
-        throw error;
+/** The mouse options a click needs: the button, only when it is not the default left one. */
+function clickOptionsOf(args) {
+    const button = clickButtonFromArgs({ button: args.button });
+    if (button === ClickButton.RIGHT || button === ClickButton.MIDDLE) {
+        return { button };
     }
-    const startedAt = now();
-    try {
-        await sleep(holdMs);
-    }
-    catch (error) {
-        // The wait failed, and the caller is about to run the synthetic path — which presses this SAME
-        // key a second time. If the driver's copy stays down, a held modifier then colours every later
-        // action for the rest of the run. Best-effort on purpose: whatever went wrong with the wait is
-        // the error worth reporting. A cleanup that cannot be proved is the exception — that one is a
-        // stuck key, and it must reach the caller as a refusal rather than be swallowed.
-        try {
-            await releaseKeys(page, pressed);
-        }
-        catch {
-            throw new DriveError(DriveErrorCode.RELEASE_FAILED, 'the wait failed and the keys it pressed could not be released, so they may still be held');
-        }
-        throw error;
-    }
-    // NOT best-effort: on the ordinary path a failed release is a real failure the caller must hear
-    // about, and swallowing it would report a press whose key is still down.
-    await releaseKeys(page, pressed);
-    return now() - startedAt;
-}
-/**
- * Release the given keys, in reverse press order, and report a failure as one that leaves the
- * keyboard UNKNOWN rather than as an ordinary provider error.
- *
- * Every release is attempted even after one fails: a stuck `Control` is worse than a stuck letter,
- * so a failure on one key must not skip the rest. The first failure is what is thrown, since it is
- * the one that happened first, and it is wrapped in `DriveError` so the caller can tell "this
- * gesture failed" from "this gesture may have left a key down" — the difference between a safe
- * synthetic replay and an unsafe one.
- */
-async function releaseKeys(page, pressed) {
-    let failure;
-    for (const k of [...pressed].reverse()) {
-        try {
-            await page.keyboard.up(k);
-        }
-        catch (error) {
-            failure ??= error;
-        }
-    }
-    if (failure !== undefined) {
-        throw new DriveError(DriveErrorCode.RELEASE_FAILED, `the key was pressed but could not be released, so it may still be held: ${describeFailure(failure)}`);
-    }
-}
-/**
- * A thrown value as a line a reader can act on.
- *
- * Not `String(error)`: a non-Error thrown value (a rejected plain object, an SDK that throws a
- * record) stringifies to `[object Object]`, which names nothing and hides the one fact the message
- * exists to carry. Anything that is neither an Error nor a string says so rather than pretending.
- */
-function describeFailure(error) {
-    if (error instanceof Error)
-        return error.message;
-    return 'string' === typeof error ? error : 'an unknown error';
-}
-/**
- * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
- *
- * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
- * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
- * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
- * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
- * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
- * routed to the synthetic path by the caller, which reports the reason rather than pretending a
- * different gesture happened.
- *
- * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
- * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
- * should name that, not the generic "you passed a ref".
- */
-export function unspellablePressReason(ref, args) {
-    if (0 < pressKeysFromArgs(args).length) {
-        return InputModeReason.SYNTHETIC_MULTI_KEY_PRESS_PREFERRED;
-    }
-    if (explicitCodeFromArgs(args) !== undefined) {
-        return InputModeReason.SYNTHETIC_KEY_CODE_PRESS_PREFERRED;
-    }
-    if (0 < ref.length)
-        return InputModeReason.SYNTHETIC_ELEMENT_PRESS_PREFERRED;
     return undefined;
 }
 /**
@@ -227,6 +86,27 @@ now = Date.now) {
             ...(heldMs > 0 ? { heldMs } : {}),
         };
     }
+    return withChromePassThrough(page, () => pointerGesture(page, action, box, args, sleep));
+}
+/**
+ * Run a real pointer gesture with Reticle's own UI out of the hit test, and put it back after.
+ *
+ * A real pointer goes to the topmost element under it. When the HUD sat over the app's control, a
+ * driven click went to the HUD and the verdict said the app did nothing; a drag ended short (#992).
+ * The restore runs whatever the gesture did, so the HUD does not stay unclickable for a person.
+ */
+export async function withChromePassThrough(page, gesture) {
+    await page.evaluate(RETICLE_CHROME_PASS_THROUGH_SCRIPT);
+    try {
+        return await gesture();
+    }
+    finally {
+        // A click that navigated takes the old page and its held values with it.
+        await page.evaluate(RETICLE_CHROME_RESTORE_POINTER_SCRIPT).catch(() => undefined);
+    }
+}
+/** 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 { cx, cy } = center;
     const real = (performed) => ({
@@ -241,19 +121,32 @@ now = Date.now) {
         await sleep(REAL_INPUT_SETTLE_MS);
         return real(true);
     }
-    if (action === ActionType.CLICK) {
+    if (action === ActionType.CLICK || action === ActionType.DBLCLICK) {
         await page.mouse.move(cx, cy);
-        await page.mouse.click(cx, cy);
-        return real(true);
-    }
-    if (action === ActionType.DBLCLICK) {
-        await page.mouse.move(cx, cy);
-        await page.mouse.dblclick(cx, cy);
+        const options = clickOptionsOf(args);
+        const modifiers = pressModifiersFromArgs(args);
+        for (const modifier of modifiers) {
+            await page.keyboard.down(modifier);
+        }
+        try {
+            if (action === ActionType.CLICK) {
+                await page.mouse.click(cx, cy, options);
+            }
+            else {
+                await page.mouse.dblclick(cx, cy, options);
+            }
+        }
+        finally {
+            for (const modifier of [...modifiers].reverse()) {
+                await page.keyboard.up(modifier);
+            }
+        }
         return real(true);
     }
     if (action === ActionType.DRAG) {
-        if (args.toBox === undefined)
+        if (args.toBox === undefined) {
             return real(false);
+        }
         const dst = boxCenter(args.toBox);
         const steps = args.steps ?? DEFAULT_DRAG_STEPS;
         await page.mouse.move(cx, cy);
@@ -341,8 +234,9 @@ export class CdpRealInputProvider {
     /** Attach the response listener the first time we see a page; a no-op afterwards. */
     #listen(page) {
         const sink = this.#onNetworkDetail;
-        if (sink === undefined || this.#listening.has(page))
+        if (sink === undefined || this.#listening.has(page)) {
             return;
+        }
         this.#listening.add(page);
         attachNetworkDetail(page, sink);
     }
@@ -354,8 +248,9 @@ export class CdpRealInputProvider {
             // Playwright's Browser exposes isConnected(); a test fake may not, so only an EXPLICIT false
             // drops the cache — a fake without the method is assumed live.
             const alive = this.#browser.isConnected?.() ?? true;
-            if (alive)
+            if (alive) {
                 return this.#browser;
+            }
             this.#browser = undefined; // fall through and reconnect
         }
         try {
@@ -369,11 +264,13 @@ export class CdpRealInputProvider {
     }
     async #pageFor(sessionUrl) {
         const browser = await this.#ensureBrowser();
-        if (browser === undefined)
+        if (browser === undefined) {
             return undefined;
+        }
         const page = selectPage(browser.contexts().flatMap((c) => c.pages()), sessionUrl);
-        if (page !== undefined)
+        if (page !== undefined) {
             this.#listen(page);
+        }
         return page;
     }
     async takeCodeCoverage(sessionUrl) {
@@ -390,22 +287,25 @@ export class CdpRealInputProvider {
     }
     async perform(sessionUrl, action, box, args) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return undriven(action, box);
+        }
         return performGesture(page, action, box, args, this.#sleep, this.#now);
     }
     /** PNG of the correlated page, or undefined if none matches. */
     async screenshot(sessionUrl, opts) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return undefined;
+        }
         return capturePage(page, opts);
     }
     /** The context's cookies and per-origin storage; undefined when no driven page matches. */
     async storageState(sessionUrl) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return undefined;
+        }
         return page.context().storageState();
     }
     /**
@@ -416,27 +316,32 @@ export class CdpRealInputProvider {
      */
     async applyStorageState(sessionUrl, state) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         const saved = state;
-        if (saved.cookies !== undefined)
+        if (saved.cookies !== undefined) {
             await page.context().addCookies(saved.cookies);
+        }
         for (const origin of saved.origins ?? []) {
             // Only the document for an origin can write that origin's localStorage, so this is applied in
             // the page rather than through the context. A page sitting on a different origin cannot be
             // given another origin's storage, and silently succeeding there would be the quiet half-restore
             // this whole path exists to avoid.
-            if (!page.url().startsWith(origin.origin))
+            if (!page.url().startsWith(origin.origin)) {
                 continue;
+            }
             await page.evaluate((entries) => {
                 // Reached through `globalThis` rather than `window`: this body is serialised and runs in the
                 // PAGE, but it is typechecked here, and this package never pulls in the DOM lib — a server
                 // that can name `window` is one step from a server that uses it.
                 const store = globalThis.localStorage;
-                if (store === undefined)
+                if (store === undefined) {
                     return;
-                for (const entry of entries)
+                }
+                for (const entry of entries) {
                     store.setItem(entry.name, entry.value);
+                }
             }, origin.localStorage ?? []);
         }
         return true;
@@ -444,16 +349,18 @@ export class CdpRealInputProvider {
     /** Apply network-mock rules to the correlated page; false when no driven page matches. */
     async setMocks(sessionUrl, rules) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         await installNetworkMocks(page, rules);
         return true;
     }
     /** Pin the correlated page's viewport to fixed dimensions; false when no driven page matches. */
     async setViewport(sessionUrl, size) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         await page.setViewportSize({ width: size.width, height: size.height });
         return true;
     }
@@ -461,11 +368,14 @@ export class CdpRealInputProvider {
     async dispose() {
         const browser = this.#browser;
         this.#browser = undefined;
-        if (browser !== undefined)
+        if (browser !== undefined) {
             await browser.close();
+        }
     }
 }
 const INJECT_CONNECT_WAIT_MS = 8_000;
+/** True on a page whose Reticle SDK has loaded. */
+const SDK_PRESENT = '!!globalThis.__reticleInstance';
 /** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
 export const launchedChromium = async (headless) => {
     let mod;
@@ -500,6 +410,7 @@ export class LaunchedRealInputProvider {
     #injectConnect;
     #storageState;
     #onNetworkDetail;
+    #zeroInstallScript;
     #browser;
     #page;
     /** Pages collecting V8 coverage — see js-coverage.ts. */
@@ -513,14 +424,19 @@ export class LaunchedRealInputProvider {
         this.#injectConnect = options.injectConnect;
         this.#storageState = options.storageState;
         this.#onNetworkDetail = options.onNetworkDetail;
+        this.#zeroInstallScript = options.zeroInstallScript;
     }
     async navigate() {
         this.#browser = await this.#launch(this.#headless);
-        const page = await this.#browser.newPage(this.#storageState !== undefined ? { storageState: this.#storageState } : undefined);
+        const page = await this.#browser.newPage({
+            ...pageViewportOptions(this.#headless),
+            ...(this.#storageState !== undefined ? { storageState: this.#storageState } : {}),
+        });
         this.#page = page;
         // Capture CDP-authoritative response detail into the driven session's journal (best-effort).
-        if (this.#onNetworkDetail !== undefined)
+        if (this.#onNetworkDetail !== undefined) {
             attachNetworkDetail(page, this.#onNetworkDetail);
+        }
         try {
             // Same navigation rule as the pool, and for the same measured reason: Playwright's default
             // waits for `load`, which an app with one never-finishing subresource never fires — 30s of
@@ -533,8 +449,35 @@ export class LaunchedRealInputProvider {
         catch (e) {
             throw new DriveError(DriveErrorCode.NAVIGATE_FAILED, e instanceof Error ? e.message : String(e));
         }
+        await this.#supplyReader(page);
         await this.#tryInjectConnect(page);
     }
+    /**
+     * Give a page with no Reticle SDK the zero-install reader, so `verify` on an app with no `init`
+     * still gets a session. The wait for the page's own SDK comes first, as on a leased tab, and the
+     * script checks the singleton, so a page with an SDK never gets a second one.
+     */
+    async #supplyReader(page) {
+        const script = this.#zeroInstallScript?.();
+        if (script === undefined) {
+            return;
+        }
+        try {
+            await page.waitForFunction(SDK_PRESENT, { timeout: INJECT_CONNECT_WAIT_MS });
+            return;
+        }
+        catch {
+            // No SDK on the page: supply the reader below.
+        }
+        try {
+            // Also on every later document, so a full navigation keeps the session.
+            await page.addInitScript(script);
+            await page.evaluate(script);
+        }
+        catch {
+            // A page that refuses the reader has no session. verify's no-session guard reports it.
+        }
+    }
     /**
      * Wait for the page's Reticle singleton to exist, then re-invoke connect with our token + loopback
      * URL so a hosted (non-localhost) preview pairs to our bridge without the app being reconfigured.
@@ -542,10 +485,11 @@ export class LaunchedRealInputProvider {
      */
     async #tryInjectConnect(page) {
         const opts = this.#injectConnect;
-        if (opts === undefined)
+        if (opts === undefined) {
             return;
+        }
         try {
-            await page.waitForFunction('!!globalThis.__reticleInstance', {
+            await page.waitForFunction(SDK_PRESENT, {
                 timeout: INJECT_CONNECT_WAIT_MS,
             });
             const arg = JSON.stringify(injectedConnectArgs(opts));
@@ -567,8 +511,9 @@ export class LaunchedRealInputProvider {
      */
     #livePage() {
         const page = this.#page;
-        if (page === undefined)
+        if (page === undefined) {
             return undefined;
+        }
         if (true === page.isClosed?.()) {
             this.#page = undefined; // never ask a corpse twice
             return undefined;
@@ -577,10 +522,12 @@ export class LaunchedRealInputProvider {
     }
     isAvailableFor(sessionUrl) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return Promise.resolve(false);
-        if (page.url() === sessionUrl)
+        }
+        if (page.url() === sessionUrl) {
             return Promise.resolve(true);
+        }
         return Promise.resolve(stripVolatile(page.url()) === stripVolatile(sessionUrl));
     }
     /**
@@ -593,8 +540,9 @@ export class LaunchedRealInputProvider {
      */
     async storageState(_sessionUrl) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return undefined;
+        }
         return page.context().storageState();
     }
     /**
@@ -603,37 +551,44 @@ export class LaunchedRealInputProvider {
      */
     async applyStorageState(_sessionUrl, state) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         const saved = state;
-        if (saved.cookies !== undefined)
+        if (saved.cookies !== undefined) {
             await page.context().addCookies(saved.cookies);
+        }
         for (const origin of saved.origins ?? []) {
             // A page sitting on a different origin cannot be given another origin's storage, and silently
             // succeeding there is the quiet half-restore this whole path exists to avoid.
-            if (!page.url().startsWith(origin.origin))
+            if (!page.url().startsWith(origin.origin)) {
                 continue;
+            }
             await page.evaluate((entries) => {
                 const store = globalThis.localStorage;
-                if (store === undefined)
+                if (store === undefined) {
                     return;
-                for (const entry of entries)
+                }
+                for (const entry of entries) {
                     store.setItem(entry.name, entry.value);
+                }
             }, origin.localStorage ?? []);
         }
         return true;
     }
     perform(_sessionUrl, action, box, args) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return Promise.resolve(undriven(action, box));
+        }
         return performGesture(page, action, box, args, this.#sleep, this.#now);
     }
     /** PNG of the owned page, or undefined before navigate / after dispose. */
     screenshot(_sessionUrl, opts) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return Promise.resolve(undefined);
+        }
         return capturePage(page, opts);
     }
     /**
@@ -646,8 +601,9 @@ export class LaunchedRealInputProvider {
      */
     async setViewport(_sessionUrl, size) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         await page.setViewportSize({ width: size.width, height: size.height });
         return true;
     }
@@ -658,8 +614,9 @@ export class LaunchedRealInputProvider {
     /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
     async setMocks(_sessionUrl, rules) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         await installNetworkMocks(page, rules);
         return true;
     }
@@ -668,8 +625,9 @@ export class LaunchedRealInputProvider {
         const browser = this.#browser;
         this.#browser = undefined;
         this.#page = undefined;
-        if (browser !== undefined)
+        if (browser !== undefined) {
             await browser.close();
+        }
     }
 }
 /** Drop hash/query so a page whose URL drifted by fragment still correlates to the session. */
@@ -688,8 +646,9 @@ export class LaunchedRealInputProvider {
  */
 export function selectPage(pages, sessionUrl) {
     const exact = pages.find((p) => p.url() === sessionUrl);
-    if (exact !== undefined)
+    if (exact !== undefined) {
         return exact;
+    }
     const target = stripVolatile(sessionUrl);
     const loose = pages.filter((p) => stripVolatile(p.url()) === target);
     return 1 === loose.length ? loose[0] : undefined;

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

@@ -83,8 +83,8 @@ export const VIEWPORT_TOOLS = [
         },
         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(),
@@ -97,7 +97,10 @@ export const VIEWPORT_TOOLS = [
             if (media !== undefined && args['width'] === undefined && args['height'] === undefined) {
                 const session = deps.sessions.resolve(asString(args['sessionId']));
                 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 };
             }

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

@@ -13,7 +13,7 @@ import { type SeedStorage } from '@reticlehq/core';
 import type { Launcher, 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';
+export type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledCookie, PooledDialog, PooledMockRule, PooledPage, PooledPageError, } from './pool-contract.js';
 import { 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;
     /**
@@ -243,6 +245,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. */