@reticlehq/server 3.8.0 → 3.8.2

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

@@ -10,25 +10,20 @@
  * 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 { 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, } 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 +58,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;
-    }
-    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;
+/** 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 };
     }
-    if (explicitCodeFromArgs(args) !== undefined) {
-        return InputModeReason.SYNTHETIC_KEY_CODE_PRESS_PREFERRED;
-    }
-    if (0 < ref.length)
-        return InputModeReason.SYNTHETIC_ELEMENT_PRESS_PREFERRED;
     return undefined;
 }
 /**
@@ -241,19 +99,32 @@ now = Date.now) {
         await sleep(REAL_INPUT_SETTLE_MS);
         return real(true);
     }
-    if (action === ActionType.CLICK) {
-        await page.mouse.move(cx, cy);
-        await page.mouse.click(cx, cy);
-        return real(true);
-    }
-    if (action === ActionType.DBLCLICK) {
+    if (action === ActionType.CLICK || 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 +212,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 +226,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 +242,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 +265,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 +294,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 +327,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,8 +346,9 @@ 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;
@@ -519,8 +405,9 @@ export class LaunchedRealInputProvider {
         const page = await this.#browser.newPage(this.#storageState !== undefined ? { storageState: this.#storageState } : undefined);
         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
@@ -542,8 +429,9 @@ export class LaunchedRealInputProvider {
      */
     async #tryInjectConnect(page) {
         const opts = this.#injectConnect;
-        if (opts === undefined)
+        if (opts === undefined) {
             return;
+        }
         try {
             await page.waitForFunction('!!globalThis.__reticleInstance', {
                 timeout: INJECT_CONNECT_WAIT_MS,
@@ -567,8 +455,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 +466,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 +484,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 +495,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 +545,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 +558,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 +569,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 +590,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.d.ts

@@ -1,24 +1,28 @@
 import { z } from 'zod';
 import type { ToolDef } from '../../surface/tools/tool-kit.js';
 import { type LeaseEmulation, type LeaseMedia } from '../pool/lease-emulation.js';
-export declare const COLOR_SCHEME_ARG: z.ZodOptional<z.ZodEnum<["light", "dark", "no-preference"]>>;
-export declare const REDUCED_MOTION_ARG: z.ZodOptional<z.ZodEnum<["reduce", "no-preference"]>>;
+export declare const COLOR_SCHEME_ARG: z.ZodOptional<z.ZodEnum<{
+    light: "light";
+    dark: "dark";
+    "no-preference": "no-preference";
+}>>;
+export declare const REDUCED_MOTION_ARG: z.ZodOptional<z.ZodEnum<{
+    reduce: "reduce";
+    "no-preference": "no-preference";
+}>>;
 export declare const LEASE_EMULATE_ARG: z.ZodOptional<z.ZodObject<{
-    colorScheme: z.ZodOptional<z.ZodEnum<["light", "dark", "no-preference"]>>;
-    reducedMotion: z.ZodOptional<z.ZodEnum<["reduce", "no-preference"]>>;
+    colorScheme: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        "no-preference": "no-preference";
+    }>>;
+    reducedMotion: z.ZodOptional<z.ZodEnum<{
+        reduce: "reduce";
+        "no-preference": "no-preference";
+    }>>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
-}, "strict", z.ZodTypeAny, {
-    width?: number | undefined;
-    height?: number | undefined;
-    colorScheme?: "light" | "dark" | "no-preference" | undefined;
-    reducedMotion?: "reduce" | "no-preference" | undefined;
-}, {
-    width?: number | undefined;
-    height?: number | undefined;
-    colorScheme?: "light" | "dark" | "no-preference" | undefined;
-    reducedMotion?: "reduce" | "no-preference" | undefined;
-}>>;
+}, z.core.$strict>>;
 /** The media part of what a caller asked for, or undefined when it asked for none. */
 export declare function mediaOf(raw: {
     colorScheme?: unknown;

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

@@ -14,61 +14,9 @@ import type { Launcher, PooledMockRule, ScreenshotOptions } from './pool-contrac
 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';
-/** A leased context+page for one flow. `release` frees the slot and closes the context. */
-export interface Lease {
-    readonly sessionId: string;
-    readonly url: string;
-    readonly navStatus?: number;
-    release(): Promise<void>;
-    /**
-     * Hand the page the zero-install reader: evaluated in the live document, and added ahead of every
-     * document this lease loads next. False when there is no reader, or the page cannot run one.
-     * Rejects with `NotHtmlDocumentError` when the page is not an HTML document.
-     */
-    injectReader?(): Promise<boolean>;
-    /** Whether the page's document has not reached `complete` yet. False when it cannot be read. */
-    isLoading?(): Promise<boolean>;
-}
-/** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
-export declare const DEFAULT_LEASE_TTL_MS: number;
-/**
- * How long a lease outlives the MCP connection that took it. Long enough for an agent whose
- * connection only blipped to touch it again; short enough that a gone agent's window closes soon.
- */
-export declare const ORPHANED_LEASE_GRACE_MS = 30000;
-interface BrowserPoolOptions {
-    /** Max simultaneous leased contexts. Over-cap acquires queue. */
-    maxContexts: number;
-    /** Stable id generator for lease sessionIds (injected to stay clock-/random-free in logic). */
-    genSessionId: () => string;
-    /** Injected clock (ms). Defaults to Date.now; tests pass a controllable one. */
-    now?: () => number;
-    /** A lease untouched for longer than this is reclaimed by sweepExpired. */
-    leaseTtlMs?: number;
-    /** Per-lease navigation timeout — a page that won't load fails its own lease, never blocks a slot. */
-    navTimeoutMs?: number;
-    /**
-     * The zero-install reader, built where the daemon knows its own port and pairing token. A thunk so
-     * the ~450KB build is only read if some page ever needs it; undefined when there is none to give.
-     */
-    zeroInstallScript?: () => string | undefined;
-    /**
-     * Launches a browser with a window, for a lease somebody wants to watch. Launched only when the
-     * first headed lease is asked for. Absent: a headed lease is refused.
-     */
-    launchHeaded?: Launcher;
-}
-/** What a headed lease is refused with where no window can be opened. */
-export declare const NO_HEADED_BROWSER = "no headed browser can be opened here";
-/**
- * An acquire that asked to be refused rather than queued found every slot taken (#1535). Queued,
- * it waited behind the cap with no deadline and no status, and `reticle drive` reported the 60 s
- * timeout as a daemon shutting down. The message names the cap and the one override for it.
- */
-export declare class PoolAtCapacityError extends Error {
-    readonly max: number;
-    constructor(max: number);
-}
+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';
 /**
  * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
  * capped at `maxContexts` across both.
@@ -171,6 +119,8 @@ export declare class BrowserPool {
     hoverLease(sessionId: string, x: number, y: number): 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. */
+    leaseLoading(sessionId: string): Promise<boolean>;
     /** Whether this session is a lease whose page has a real keyboard. */
     hasKeyboard(sessionId: string): boolean;
     /**