@reticlehq/server 3.7.0 → 3.8.1

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

@@ -0,0 +1,37 @@
+/**
+ * What a lease can emulate: the two media features a person sets in their OS, and the width.
+ *
+ * Without them, prefers-reduced-motion and prefers-color-scheme could not be set on a leased tab,
+ * so the CSS half of reduced motion and the dark theme could not be checked live. A lease is a
+ * Playwright context, which takes all three before the first paint and the media again per call.
+ */
+export declare const ColorScheme: {
+    readonly LIGHT: "light";
+    readonly DARK: "dark";
+    readonly NO_PREFERENCE: "no-preference";
+};
+export type ColorScheme = (typeof ColorScheme)[keyof typeof ColorScheme];
+export declare const ReducedMotion: {
+    readonly REDUCE: "reduce";
+    readonly NO_PREFERENCE: "no-preference";
+};
+export type ReducedMotion = (typeof ReducedMotion)[keyof typeof ReducedMotion];
+/** The media features a page reads with matchMedia. */
+export interface LeaseMedia {
+    colorScheme?: ColorScheme;
+    reducedMotion?: ReducedMotion;
+}
+/** What a lease opens with: the media, and a viewport. */
+export interface LeaseEmulation extends LeaseMedia {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+/** The size a page reports for itself, or undefined when it cannot be read. */
+export declare function readViewport(page: {
+    evaluate?(script: string): Promise<unknown>;
+}): Promise<{
+    width: number;
+    height: number;
+} | undefined>;

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

@@ -0,0 +1,29 @@
+/**
+ * What a lease can emulate: the two media features a person sets in their OS, and the width.
+ *
+ * Without them, prefers-reduced-motion and prefers-color-scheme could not be set on a leased tab,
+ * so the CSS half of reduced motion and the dark theme could not be checked live. A lease is a
+ * Playwright context, which takes all three before the first paint and the media again per call.
+ */
+export const ColorScheme = {
+    LIGHT: 'light',
+    DARK: 'dark',
+    NO_PREFERENCE: 'no-preference',
+};
+export const ReducedMotion = { REDUCE: 'reduce', NO_PREFERENCE: 'no-preference' };
+/** The page's own layout viewport, read back after a resize. */
+const VIEWPORT_READ_SCRIPT = '[window.innerWidth, window.innerHeight]';
+/** The size a page reports for itself, or undefined when it cannot be read. */
+export async function readViewport(page) {
+    if (page.evaluate === undefined) {
+        return undefined;
+    }
+    try {
+        const size = await page.evaluate(VIEWPORT_READ_SCRIPT);
+        const [width, height] = Array.isArray(size) ? size : [];
+        return 'number' === typeof width && 'number' === typeof height ? { width, height } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/portal/pool/playwright-launcher.d.ts

@@ -31,6 +31,12 @@ export declare function screenshotOptions(opts: ScreenshotOptions): {
     type?: 'jpeg';
     quality?: number;
     scale?: 'css';
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
 };
 /**
  * A step screenshot with Reticle's own UI out of it. The step path injects nothing into the page

package/dist/portal/pool/playwright-launcher.js

@@ -6,12 +6,19 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
-import { HIDE_RETICLE_CHROME_CSS, RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
+import { ActionType, HIDE_RETICLE_CHROME_CSS, RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
 import { launchChromium } from '../../launch-chromium.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
 import { installNetworkMocks } from '../input/network-mock.js';
+import { performGesture } from '../input/real-input.js';
+/** A key addresses focus, not a point; the gesture driver takes a box for every action. */
+const NO_BOX = { x: 0, y: 0, width: 0, height: 0 };
+const sleepFor = (ms) => new Promise((r) => setTimeout(r, ms));
+// Every request, as a predicate: the mock installer clears the any-URL glob, and must not clear the
+// production guard with it.
+const ANY_URL = () => true;
 /**
  * Reticle paints its own UI (presenter HUD, glow, annotator marks, tour) into the page. It is
  * time-varying, since the activity log and border state change with every command, so capturing it
@@ -35,7 +42,11 @@ export function screenshotOptions(opts) {
     if (true === opts.cssScale && opts.jpegQuality !== undefined) {
         return { fullPage: false, type: 'jpeg', quality: opts.jpegQuality, scale: 'css' };
     }
-    const base = { ...SCREENSHOT_DETERMINISM, fullPage: true === opts.fullPage };
+    const base = {
+        ...SCREENSHOT_DETERMINISM,
+        fullPage: true === opts.fullPage,
+        ...(opts.clip === undefined ? {} : { clip: opts.clip }),
+    };
     return opts.jpegQuality === undefined
         ? base
         : { ...base, type: 'jpeg', quality: opts.jpegQuality };
@@ -84,7 +95,13 @@ function wrapBrowser(browser) {
     return {
         isConnected: () => browser.isConnected(),
         newContext: async (opts) => {
-            const context = await browser.newContext(true === opts?.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : undefined);
+            // Media and viewport ride on the context, so the first paint of the first page has them.
+            const { ignoreHTTPSErrors, ...emulate } = opts ?? {};
+            const contextOpts = {
+                ...(true === ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
+                ...emulate,
+            };
+            const context = await browser.newContext(0 < Object.keys(contextOpts).length ? contextOpts : undefined);
             return {
                 newPage: async () => {
                     const page = await context.newPage();
@@ -109,7 +126,24 @@ function wrapBrowser(browser) {
                             await page.mouse.move(x + 1, y);
                             await page.mouse.move(x, y);
                         },
+                        // The same driver `reticle drive` presses with, so a held key and a chord read alike.
+                        emulateMedia: (media) => page.emulateMedia(media),
+                        press: (args) => performGesture(page, ActionType.PRESS, NO_BOX, args, sleepFor),
                         installMocks: (rules) => installNetworkMocks(page, [...rules]),
+                        // Registered after any mocks, so it is asked first; what it lets go falls back to them.
+                        guardRequests: async (decide) => {
+                            await page.route(ANY_URL, (route) => {
+                                const request = route.request();
+                                const refusal = decide(request.method(), request.url());
+                                return refusal === undefined
+                                    ? route.fallback()
+                                    : route.fulfill({
+                                        status: 403,
+                                        contentType: 'application/json',
+                                        body: JSON.stringify({ error: refusal }),
+                                    });
+                            });
+                        },
                         setViewport: (size) => page.setViewportSize(size),
                         bringToFront: () => page.bringToFront(),
                         onCrash: (handler) => page.on('crash', handler),
@@ -140,10 +174,43 @@ function wrapBrowser(browser) {
  *
  * Pinned to the playwright this process bundles. Unpinned, `npx` fetches the latest playwright and
  * installs ITS browser revision — a build this launcher will never look at — so the user follows the
- * advice, it succeeds, and the next launch fails identically. Shares one builder with `doctor` so the
- * two cannot suggest different commands for the same missing browser.
+ * advice, it succeeds, and the next launch fails identically. Shares one builder with `doctor` so
+ * the two cannot suggest different commands for the same missing browser.
+ *
+ * When Playwright's error names the executable the failed launch looked for, the message names
+ * it too, the way the preflight refusal and the doctor line already do. Without it the launch
+ * translation was the one surface that hid the evidence: a daemon whose HOME
+ * or PLAYWRIGHT_BROWSERS_PATH differs from the shell that ran the install keeps refusing after a
+ * successful install, and a bare command gives the reader no way to see that the lookup is aimed at
+ * a root nothing was installed into (#691).
  */
-const CHROMIUM_MISSING_HINT = `Chromium is not installed for Playwright. Run: ${chromiumInstallCommand(bundledPlaywrightVersion())}`;
+function chromiumMissingHint(executablePath) {
+    const command = chromiumInstallCommand(bundledPlaywrightVersion());
+    return executablePath === undefined
+        ? `Chromium is not installed for Playwright. Run: ${command}`
+        : `Chromium is not installed for Playwright — looked for ${executablePath}. Run: ${command}`;
+}
+/**
+ * The executable Playwright's error says the failed launch looked for, or undefined when the
+ * error names none.
+ *
+ * Playwright reports the build the failed launch actually used — `Executable doesn't exist at
+ * <path>` — whether that is the bundled build, the RETICLE_CHROMIUM_PATH executable, or an
+ * installed Chrome or Edge. Reading it here keeps the hint honest: a fresh bundled-path lookup
+ * would name a build nobody tried whenever the launch used anything else.
+ */
+function pathFromPlaywrightError(msg) {
+    // Playwright puts the path at the end of the line, and a Windows path can hold a space
+    // (for example C:\Users\Jo Doe). Read to the end of the line and trim the result.
+    const found = /executable doesn.?t exist at (.+)$/im.exec(msg);
+    if (null === found)
+        return undefined;
+    const captured = found[1];
+    if (undefined === captured)
+        return undefined;
+    const path = captured.trim();
+    return '' === path ? undefined : path;
+}
 /**
  * A DIFFERENT first-run failure from the one above: the browser binary is already there, but the
  * host is missing the OS-level shared libraries (e.g. `libnspr4.so`) Playwright's own
@@ -190,7 +257,7 @@ export function chromiumLaunchHint(msg) {
     if (/host system is missing dependencies/i.test(msg))
         return CHROMIUM_MISSING_DEPS_HINT;
     if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
-        return CHROMIUM_MISSING_HINT;
+        return chromiumMissingHint(pathFromPlaywrightError(msg));
     }
     return undefined;
 }

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

@@ -5,6 +5,8 @@
  * `browser-pool.ts`, which imports IT. Real Playwright `Page`/`BrowserContext`/`Browser` satisfy
  * these structurally, which is how the pool stays testable without a real Chromium.
  */
+import type { RealInputArgs, RealInputResult } from '../input/real-input.js';
+import type { LeaseEmulation, LeaseMedia } from './lease-emulation.js';
 /** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
 export interface PooledPage {
     goto(url: string, opts?: {
@@ -32,6 +34,13 @@ export interface PooledPage {
      * reports dispatched/settled while the styles never ran.
      */
     hover?(x: number, y: number): Promise<void>;
+    /**
+     * Press a key with the real keyboard; it goes to whatever holds focus. OPTIONAL, like `hover`: a
+     * page without it keeps the in-page dispatcher, whose synthetic Tab moves no focus.
+     */
+    press?(args: RealInputArgs): Promise<RealInputResult>;
+    /** Set prefers-color-scheme and prefers-reduced-motion. OPTIONAL: without it the media stay. */
+    emulateMedia?(media: LeaseMedia): Promise<void>;
     /** Evaluate a script in the page's current document. OPTIONAL: without it no reader is injected. */
     evaluate?(script: string): Promise<unknown>;
     /** Add an init script to run after document creation but before any page scripts run. */
@@ -41,6 +50,12 @@ export interface PooledPage {
      * makes `reticle_network_mock` refuse rather than claiming it stubbed a request it cannot intercept.
      */
     installMocks?(rules: readonly PooledMockRule[]): Promise<void>;
+    /**
+     * Answer every request this page sends through `decide`: a string refuses it (403, the string as
+     * the error), undefined lets it go. OPTIONAL, like `installMocks`. A production drive uses it so a
+     * refused request never reaches the live service.
+     */
+    guardRequests?(decide: (method: string, url: string) => string | undefined): Promise<void>;
     /**
      * Resize this page's viewport. OPTIONAL, like `installMocks`: a fake that does not implement it
      * makes `reticle_viewport` refuse rather than claim a resize the page never took.
@@ -125,7 +140,7 @@ export interface PooledBrowser {
     /** `ignoreHTTPSErrors` accepts a self-signed or local-CA certificate for this context only. */
     newContext(opts?: {
         ignoreHTTPSErrors?: boolean;
-    }): Promise<PooledContext>;
+    } & LeaseEmulation): Promise<PooledContext>;
     close(): Promise<void>;
     /** Fires when the browser process dies/crashes so the pool can relaunch on the next acquire. */
     onDisconnected(handler: () => void): void;
@@ -138,4 +153,11 @@ export interface ScreenshotOptions {
     jpegQuality?: number;
     /** One image pixel per CSS pixel, so a high-density display does not double a step screenshot. */
     cssScale?: boolean;
+    /** One region of the page, in CSS pixels: what `reticle_screenshot { clip | ref }` asked for. */
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
 }

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

@@ -0,0 +1,128 @@
+/**
+ * The pool's lease handle and lease record, its options, and its limits: the types and constants
+ * `BrowserPool` is built from.
+ */
+import type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, 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;
+/** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
+export declare const DEFAULT_NAV_TIMEOUT_MS = 30000;
+/**
+ * How many reaped lease ids to remember. Only the most recent departure is ever asked about, so
+ * this is slack for a burst sweep, not a history.
+ */
+export declare const MAX_REMEMBERED_REAPED_LEASES = 64;
+export 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;
+}
+/** One browser the pool may hold, and the launch in flight for it. */
+export interface BrowserSlot {
+    readonly launch: Launcher | undefined;
+    readonly headed: boolean;
+    browser?: PooledBrowser | undefined;
+    launching?: Promise<PooledBrowser> | undefined;
+}
+/** 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);
+}
+/**
+ * What an acquire that asked for an init script is refused with when the page cannot run one.
+ *
+ * A refusal rather than a lease: the caller asked for a stub of the bindings a desktop shell
+ * injects, and a tab opened without it would throw in the app's view and read as a broken app.
+ */
+export declare const INIT_SCRIPT_UNSUPPORTED = "Init script failed: this page does not support init scripts, so the requested stub would not be there";
+export interface ActiveLease {
+    /** Whether it lives in the headed browser: that browser's death is this lease's death. */
+    headed: boolean;
+    context: PooledContext;
+    page: PooledPage;
+    url: string;
+    /** Who took it (one id per MCP attach). Only that caller is handed it again. */
+    owner?: string;
+    /** Last time an agent touched this lease (acquire or any tool call); drives orphan reclaim. */
+    touchedAt: number;
+    /** When the connection that took it closed, until it is touched again. */
+    detachedAt?: number;
+    /**
+     * The websocket address the page's SDK reported it could not reach, if it said so.
+     *
+     * One string, overwritten — not a buffer. The SDK retries and logs each failure, so accumulating
+     * them would grow without bound for exactly the app that is already misconfigured, and every entry
+     * after the first says the same thing.
+     */
+    dialFailureUrl?: string;
+    /**
+     * The message of the most recent native dialog dismissed on this lease, if any.
+     *
+     * One string, overwritten — not a buffer, same reasoning as `dialFailureUrl`: this is diagnostic
+     * context for "why did the page look frozen for a moment", not a log an agent needs to replay.
+     */
+    lastDialogMessage?: string;
+    /**
+     * The disposable handle of the caller's init script, when the lease was opened with one — a stub
+     * of the bindings a desktop shell injects. Disposed with the lease, so a reload or a later
+     * navigation inside the lease keeps the stub.
+     */
+    hostStub?: InitScriptHandle;
+    /** The production guard on this page's requests, re-asserted after mocks so it is asked first. */
+    guard?: (method: string, url: string) => string | undefined;
+    /**
+     * The text of that init script, kept so a lease that asks for the SAME stub again is recognised and
+     * reused instead of being torn down and remade — see `hostStubScript` and the lease tool's reuse.
+     */
+    hostStubScript?: string;
+    /** What this lease was granted when it opened. It never changes on an open lease. */
+    permissions: readonly string[];
+    /** Whether its context accepts any TLS certificate (#1255). Fixed when the context is made. */
+    ignoresHTTPSErrors: boolean;
+}
+/** Whether the page's document has not finished loading. A page that cannot be asked counts as loaded. */
+export declare function pageLoading(page: PooledPage): Promise<boolean>;

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

@@ -0,0 +1,49 @@
+/**
+ * The pool's lease handle and lease record, its options, and its limits: the types and constants
+ * `BrowserPool` is built from.
+ */
+/** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
+export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
+/**
+ * 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 const ORPHANED_LEASE_GRACE_MS = 30_000;
+/** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
+export const DEFAULT_NAV_TIMEOUT_MS = 30_000;
+/**
+ * How many reaped lease ids to remember. Only the most recent departure is ever asked about, so
+ * this is slack for a burst sweep, not a history.
+ */
+export const MAX_REMEMBERED_REAPED_LEASES = 64;
+/** What a headed lease is refused with where no window can be opened. */
+export 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 class PoolAtCapacityError extends Error {
+    max;
+    constructor(max) {
+        super(`all ${String(max)} lease slots are in use. Release one (reticle_lease{action:"release"}, or ` +
+            'stop a `reticle drive`), or raise RETICLE_MAX_CONTEXTS.');
+        this.max = max;
+        this.name = 'PoolAtCapacityError';
+    }
+}
+/**
+ * What an acquire that asked for an init script is refused with when the page cannot run one.
+ *
+ * A refusal rather than a lease: the caller asked for a stub of the bindings a desktop shell
+ * injects, and a tab opened without it would throw in the app's view and read as a broken app.
+ */
+export const INIT_SCRIPT_UNSUPPORTED = 'Init script failed: this page does not support init scripts, so the requested stub would not be there';
+/** Whether the page's document has not finished loading. A page that cannot be asked counts as loaded. */
+export async function pageLoading(page) {
+    if (page.evaluate === undefined) {
+        return false;
+    }
+    const state = await page.evaluate('document.readyState');
+    return 'string' === typeof state && state !== 'complete';
+}

package/dist/portal/pool/zero-install.d.ts

@@ -10,14 +10,21 @@ export interface InjectedConnect {
  * ships (`real-input.ts`) — so the two cannot come to disagree about what a daemon-driven page needs.
  */
 export declare function injectedConnectArgs(opts: InjectedConnect): Record<string, unknown>;
+/** What the reader script returns when it did nothing, because the page is not an HTML document. */
+export declare const READER_NOT_HTML = "reticle:not-html-document";
 /**
  * The script for a page: install the SDK if the page has none, then connect it to this daemon.
  *
  * The guard is on the SINGLETON, not on a timer: a page that loaded its own SDK already holds
  * `__reticleInstance`, and evaluating a second copy would register a second session for one tab.
- * `connect` is a no-op once connected, so calling it on the page's own instance is safe.
+ * `connect` is a no-op once connected, so calling it on the page's own instance is safe, except that
+ * the `lease` mark lets that instance replace a token the bridge refused.
  */
 export declare function zeroInstallScript(bundle: string, opts: InjectedConnect): string;
+/** The page is not an HTML document, so the lease did not give it the zero-install reader. */
+export declare class NotHtmlDocumentError extends Error {
+    constructor();
+}
 /**
  * The single-file build, or undefined when this install has none.
  *

package/dist/portal/pool/zero-install.js

@@ -19,20 +19,42 @@ const READER_SPECIFIER = '@reticlehq/browser/inject';
 export function injectedConnectArgs(opts) {
     return {
         allowNonLocalhost: true,
+        // Lets a page's own SDK take this token when the bridge refused the one its build baked in.
+        lease: true,
         ...(opts.token === undefined ? {} : { token: opts.token }),
         url: opts.url,
     };
 }
+/** What the reader script returns when it did nothing, because the page is not an HTML document. */
+export const READER_NOT_HTML = 'reticle:not-html-document';
+/** The document types that the reader runs on. `document.contentType` is set before the root element. */
+const HTML_CONTENT_TYPES = ['text/html', 'application/xhtml+xml'];
+/*
+ * Stop on a page that is not an HTML document, for example an `.svg`. The bundle needs an HTML DOM;
+ * #1701 reports `Cannot read properties of null (reading 'appendChild')` on an SVG. The check
+ * reads `document.contentType`, because an init script runs before the parser makes the root
+ * element. The check binds no name, so it cannot collide with a name that the bundle declares.
+ */
+const NOT_HTML_GUARD = `if (globalThis.document !== undefined && !${JSON.stringify(HTML_CONTENT_TYPES)}.includes(globalThis.document.contentType)) ` +
+    `return ${JSON.stringify(READER_NOT_HTML)};`;
 /**
  * The script for a page: install the SDK if the page has none, then connect it to this daemon.
  *
  * The guard is on the SINGLETON, not on a timer: a page that loaded its own SDK already holds
  * `__reticleInstance`, and evaluating a second copy would register a second session for one tab.
- * `connect` is a no-op once connected, so calling it on the page's own instance is safe.
+ * `connect` is a no-op once connected, so calling it on the page's own instance is safe, except that
+ * the `lease` mark lets that instance replace a token the bridge refused.
  */
 export function zeroInstallScript(bundle, opts) {
     const args = JSON.stringify(injectedConnectArgs(opts));
-    return `(() => {\nif (!globalThis.__reticleInstance) {\n${bundle}\n}\nglobalThis.__reticleInstance.connect(${args});\n})();`;
+    return `(() => {\n${NOT_HTML_GUARD}\nif (!globalThis.__reticleInstance) {\n${bundle}\n}\nglobalThis.__reticleInstance.connect(${args});\n})();`;
+}
+/** The page is not an HTML document, so the lease did not give it the zero-install reader. */
+export class NotHtmlDocumentError extends Error {
+    constructor() {
+        super('The page is not an HTML document, so the zero-install reader did not run.');
+        this.name = 'NotHtmlDocumentError';
+    }
 }
 let cached;
 /**

package/dist/portal/production/production-activation.d.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { HelloScope } from '@reticlehq/core';
+import type { ProductionDrive, ProductionGrant } from './production-drive.js';
+/**
+ * Turn `reticle_lease { production }` into a page that will connect on a live site, in one step.
+ *
+ * 1. Mint a single-use session nonce for the site's origin, bound to a production drive.
+ * 2. Ask the service for an activation ticket with the linked API key:
+ *    `POST /v1/production-mode/tickets { workspaceId, nonce, bridgePort, scope, origin, bridge }`.
+ * 3. Hand back `<url>?reticle_activate=<ticket>` for the lease to open.
+ *
+ * The service decides who may activate (an owner or admin of a workspace with production mode on)
+ * and signs the ticket. No static secret leaves the machine: the page only ever sees the nonce.
+ */
+/** Said when the service has no ticket route: an older or self-hosted service. */
+export declare const PRODUCTION_MODE_NOT_OFFERED: string;
+/** Said when this project has no linked cloud credentials to ask with. */
+export declare const PRODUCTION_MODE_NOT_LINKED = "production mode needs a linked Reticle cloud account: run `reticle connect`, or set RETICLE_API_KEY";
+/** The `production` argument of `reticle_lease { action: "acquire" }`. */
+export declare const ProductionLeaseArgSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    scope: z.ZodEnum<{
+        readonly OBSERVE: "observe";
+        readonly ACT: "act";
+    }>;
+    intent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TicketFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+/** The part of the nonce registry activation needs: the daemon's own, never one a page reaches. */
+export interface NonceMinter {
+    mint(options: {
+        origin?: string;
+        production?: ProductionGrant;
+    }): {
+        nonce: string;
+        expiresAt: number;
+        production?: ProductionDrive;
+    };
+}
+export interface ActivationInput {
+    production: unknown;
+    url: string;
+    nonces: NonceMinter | undefined;
+    bridgePort: number | undefined;
+    cloud: () => Promise<{
+        url: string;
+        apiKey: string;
+    } | null>;
+    fetch?: TicketFetch;
+}
+export interface Activation {
+    /** The site, carrying the ticket. */
+    url: string;
+    drive: ProductionDrive;
+    scope: HelloScope;
+    expiresAt: number;
+}
+export declare function activateProduction(input: ActivationInput): Promise<Activation>;
+/**
+ * The lease as the readiness wait sees it, minus the zero-install injector. An injected SDK would
+ * connect with the machine's pairing token as a development session, outside the policy; a
+ * production page connects only through its own activated loader.
+ */
+export declare function leaseWithoutInjection<L extends {
+    isLoading?: () => Promise<boolean>;
+}>(lease: L): {
+    isLoading?: () => Promise<boolean>;
+};
+/** `reticle_lease`'s `production` argument, described for the agent. */
+export declare const PRODUCTION_LEASE_ARG: z.ZodOptional<z.ZodObject<{
+    workspaceId: z.ZodString;
+    scope: z.ZodEnum<{
+        readonly OBSERVE: "observe";
+        readonly ACT: "act";
+    }>;
+    intent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/** What a production lease reports back. */
+export declare const PRODUCTION_LEASE_OUTPUT: z.ZodOptional<z.ZodObject<{
+    scope: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>>;
+/** The lease's ports activation reads. */
+interface ActivationPorts {
+    nonces?: NonceMinter | undefined;
+    bridgePort?: number | undefined;
+    linkedCloud?: ((root?: string) => Promise<{
+        url: string;
+        apiKey: string;
+    } | null>) | undefined;
+}
+/** Activate when the lease asked for production, else nothing. */
+export declare function activationFor(ports: ActivationPorts, asked: unknown, url: string, root: string | undefined): Promise<Activation | undefined>;
+/**
+ * Guard a production lease's requests with its drive, and hand the readiness wait a lease it
+ * cannot inject into. A development lease passes through untouched.
+ */
+export declare function guardedForProduction<L extends {
+    isLoading?: () => Promise<boolean>;
+}>(pool: {
+    guardLease(id: string, decide: (method: string, url: string) => string | undefined): Promise<boolean>;
+}, lease: L & {
+    sessionId: string;
+}, activated: Activation | undefined): Promise<L | {
+    isLoading?: () => Promise<boolean>;
+}>;
+/** The `production` field of the lease result. */
+export declare function summary(activated: Activation | undefined): {
+    production?: {
+        scope: HelloScope;
+        expiresAt: number;
+    };
+};
+/**
+ * Why an activated page never connected. The service redeems a ticket only for a browser signed in
+ * as the person who asked for it, and a leased browser starts signed out. The generic diagnosis
+ * blamed the page's CSP and said to allow the bridge for development only, which is wrong here.
+ */
+export declare function notActivatedHint(url: string): string;
+/**
+ * The permissions a lease is opened with. A production page on a public origin dials the bridge on
+ * loopback, which Chromium blocks unless a person grants Local Network Access, and a leased browser
+ * has no person. Granted on the lease's own origin only. Not a launch flag: a second
+ * `--disable-features` replaces the list Playwright launches with instead of adding to it.
+ */
+export declare function leasePermissions(asked: readonly string[] | undefined, production: unknown): readonly string[] | undefined;
+export {};