@reticlehq/server 3.2.0 → 3.4.0

package/dist/portal/bridge/auth-failure-reason.d.ts

@@ -4,7 +4,7 @@
  * A daemon left running by one project answers the next project's app and rejects it on token, and
  * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
  * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
- * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, use your own port".
  *
  * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
  * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those

package/dist/portal/bridge/auth-failure-reason.js

@@ -4,7 +4,7 @@
  * A daemon left running by one project answers the next project's app and rejects it on token, and
  * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
  * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
- * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, use your own port".
  *
  * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
  * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
@@ -28,8 +28,11 @@ const PLAIN = 'authentication failed';
  * before `~/.reticle` was replaced. Both need the same first move: ask `status`, which can say which.
  */
 const WRONG_TOKEN = 'authentication failed: wrong pairing token — run `reticle status` for the cause';
-/** A paste-in snippet or a Next config that never saw a token. Reload cannot mint one. */
-const NO_TOKEN = 'authentication failed: no pairing token on the page';
+/**
+ * A paste-in snippet or a Next config that never saw a token. Reload cannot mint one; restarting the
+ * dev server re-runs the substitution that should have put it there (#1047).
+ */
+const NO_TOKEN = 'authentication failed: no pairing token on the page; the build did not substitute it, so restart the dev server';
 /** WebSocket close reasons are capped at 123 bytes; a longer one throws and closes with nothing. */
 const MAX_REASON_BYTES = 123;
 const DIFFERENT_PROJECT_PREFIX = 'this daemon serves a different project';
@@ -59,7 +62,9 @@ export function authFailureReason(servedProjects, helloProject, helloToken) {
     if (helloProject !== undefined &&
         1 === servedProjects.size &&
         !servedProjects.has(helloProject)) {
-        const reason = `${DIFFERENT_PROJECT_PREFIX} — run \`reticle stop\` and retry`;
+        // Not "stop it": that daemon is serving somebody else's app. This project needs its own port,
+        // which the CLI and the build plugins both read from `.reticle.json`.
+        const reason = `${DIFFERENT_PROJECT_PREFIX} — set a free "port" in .reticle.json, then restart the dev server`;
         return Buffer.byteLength(reason, 'utf8') <= MAX_REASON_BYTES ? reason : PLAIN;
     }
     if (helloToken === undefined || 0 === helloToken.length)

package/dist/portal/bridge/bridge.d.ts

@@ -38,6 +38,14 @@ export declare const WS_CLOSE_REASON: {
      * refusal on this path: nothing about the app is wrong and retrying is the correct response.
      */
     readonly HANDSHAKE_POOL_FULL: string;
+    /**
+     * A page's HELLO failed the wire schema for a reason other than its protocol number — the SDK and
+     * this daemon are different releases whose contracts no longer agree. The socket is still closed
+     * with the short `invalid message` the SDK already prints; this is the sentence the no-session
+     * diagnosis records, because "never dialled the bridge" was what `init` said about a page this
+     * daemon had just turned away. Same `cause — fix` shape as the protocol-skew reasons.
+     */
+    readonly INVALID_HELLO: string;
 };
 interface BridgeOptions {
     port: number;

package/dist/portal/bridge/bridge.js

@@ -69,6 +69,16 @@ export const WS_CLOSE_REASON = {
         'this dial never got to identify itself. Nothing is wrong with the app; the pool drains on its ' +
         'own and reloading the page reconnects. If it persists, something else on this machine is ' +
         'opening sockets to this port.',
+    /**
+     * A page's HELLO failed the wire schema for a reason other than its protocol number — the SDK and
+     * this daemon are different releases whose contracts no longer agree. The socket is still closed
+     * with the short `invalid message` the SDK already prints; this is the sentence the no-session
+     * diagnosis records, because "never dialled the bridge" was what `init` said about a page this
+     * daemon had just turned away. Same `cause — fix` shape as the protocol-skew reasons.
+     */
+    INVALID_HELLO: "invalid message: the page's hello does not match this daemon's wire contract — put " +
+        '@reticlehq/browser, the build plugin and @reticlehq/server on one release, run `reticle stop`, ' +
+        'then restart the dev server',
 };
 /**
  * A dial turned away at the ORIGIN gate, in words the reader can act on.
@@ -179,6 +189,25 @@ function helloProtocolMismatch(text) {
     }
     return null;
 }
+/**
+ * What a HELLO says about the page it came from, read loosely enough to survive the schema failing.
+ * Null when the message is not a hello at all — only an SDK sends one, so only then is a refusal
+ * evidence about an app.
+ */
+function peekHelloPage(text) {
+    try {
+        const json = JSON.parse(text);
+        if (json.kind !== MessageKind.HELLO)
+            return null;
+        return {
+            ...('string' === typeof json.url ? { url: json.url } : {}),
+            ...('string' === typeof json.projectId ? { projectId: json.projectId } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
 /** Normalize ws RawData (string | Buffer | Buffer[] | ArrayBuffer) into a UTF-8 string. */
 function rawToString(raw) {
     if ('string' === typeof raw)
@@ -436,10 +465,19 @@ export class Bridge {
                         // Told to the AGENT too, not only to the SDK that is about to stop retrying. Without this
                         // the next tool call answers "no browser session connected", which reads as "no app is
                         // running" — so an SDK too old to connect is invisible.
-                        this.sessions.noteClosure(reason, this.#clock());
+                        this.sessions.noteClosure(reason, this.#clock(), peekHelloPage(text) ?? {});
                         socket.close(WS_CLOSE.PROTOCOL_MISMATCH[0], reason);
                         return;
                     }
+                    // Recorded only for a HELLO on a socket that has none yet: that is a page being turned
+                    // away, and it used to leave no trace, so `init` reported "never dialled the bridge" about
+                    // a page this daemon had just refused. A malformed frame on a live session is a different
+                    // failure and says nothing about whether the app can connect.
+                    const refused = undefined === session ? peekHelloPage(text) : null;
+                    if (null !== refused) {
+                        log('hello_invalid', { ...refused });
+                        this.sessions.noteClosure(WS_CLOSE_REASON.INVALID_HELLO, this.#clock(), refused);
+                    }
                     socket.close(...WS_CLOSE.INVALID_MESSAGE);
                     return;
                 }
@@ -498,7 +536,10 @@ export class Bridge {
                             presented: parsed.token !== undefined && 0 < parsed.token.length,
                             tokenSource: this.#tokenSource,
                         });
-                        this.sessions.noteClosure(reason, this.#clock());
+                        this.sessions.noteClosure(reason, this.#clock(), {
+                            url: parsed.url,
+                            ...(parsed.projectId === undefined ? {} : { projectId: parsed.projectId }),
+                        });
                         socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                         return;
                     }

package/dist/portal/input/js-coverage.d.ts

@@ -0,0 +1,25 @@
+import type { Page } from 'playwright';
+/**
+ * V8 JS coverage on a page Reticle drives — the raw half of "what of the app ever ran".
+ *
+ * Started once per page with `resetOnNavigation: false`, so a reload keeps counting instead of
+ * starting over. A take stops and immediately restarts: the counts it returns are since the last
+ * take, and the reader folds them as a union (see features/exhaust/code-coverage.ts).
+ *
+ * Chromium only. Anything else — or a page that closed — answers false/undefined rather than
+ * throwing: coverage is an addition to a drive, never a reason for one to fail.
+ */
+/** One script's coverage — the shape `stopJSCoverage` returns, narrowed to what is read. */
+export interface ScriptCoverage {
+    url: string;
+    functions: {
+        functionName: string;
+        ranges: {
+            startOffset: number;
+            endOffset: number;
+            count: number;
+        }[];
+    }[];
+}
+export declare function startJsCoverage(page: Page, covering: WeakSet<Page>): Promise<boolean>;
+export declare function takeJsCoverage(page: Page, covering: WeakSet<Page>): Promise<ScriptCoverage[] | undefined>;

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

@@ -0,0 +1,30 @@
+export async function startJsCoverage(page, covering) {
+    if (covering.has(page))
+        return true;
+    try {
+        await page.coverage.startJSCoverage({ resetOnNavigation: false });
+        covering.add(page);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function takeJsCoverage(page, covering) {
+    // Nothing collects until something asks: collection slows every script on the page. The first
+    // take starts it and has nothing to report yet.
+    if (!covering.has(page)) {
+        await startJsCoverage(page, covering);
+        return undefined;
+    }
+    try {
+        const entries = await page.coverage.stopJSCoverage();
+        covering.delete(page);
+        await startJsCoverage(page, covering);
+        return entries;
+    }
+    catch {
+        covering.delete(page);
+        return undefined;
+    }
+}

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

@@ -9,6 +9,7 @@
  * Node-only. Playwright is loaded via DYNAMIC `import('playwright')` so non-CDP users never
  * pay for it; the type-only import is elided by `tsc`, so the build stays green without it.
  */
+import { type ScriptCoverage } from './js-coverage.js';
 import type { Browser, Page } from 'playwright';
 import { ActionType, DriveErrorCode } from '@reticlehq/core';
 import { type MockRule } from './network-mock.js';
@@ -77,6 +78,14 @@ export interface RealInputProvider {
      * Optional: a provider with no owned browser simply omits it.
      */
     setMocks?(sessionUrl: string, rules: MockRule[]): Promise<boolean>;
+    /**
+     * What of the app's own code ran since the last take (V8 coverage, Chromium only), or undefined
+     * when no driven page matches or collection had not started. The first call starts collecting,
+     * because collection slows every script on the page and a slower page can let a console error land
+     * after a clean-console check passed. Optional: a provider with no owned browser cannot see the
+     * engine's counters.
+     */
+    takeCodeCoverage?(sessionUrl: string): Promise<ScriptCoverage[] | undefined>;
     /**
      * Pin the correlated page's viewport to fixed pixel dimensions so a screenshot baseline is
      * reproducible across machines (the missing piece of CI-stable visual regression, alongside masks
@@ -144,6 +153,7 @@ interface CdpProviderOptions {
 export declare class CdpRealInputProvider implements RealInputProvider {
     #private;
     constructor(options: CdpProviderOptions);
+    takeCodeCoverage(sessionUrl: string): Promise<ScriptCoverage[] | undefined>;
     isAvailableFor(sessionUrl: string): Promise<boolean>;
     perform(sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
     /** PNG of the correlated page, or undefined if none matches. */
@@ -236,6 +246,7 @@ export declare class LaunchedRealInputProvider implements OwnedRealInputProvider
         width: number;
         height: number;
     }): Promise<boolean>;
+    takeCodeCoverage(_sessionUrl: string): Promise<ScriptCoverage[] | undefined>;
     /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
     setMocks(_sessionUrl: string, rules: MockRule[]): Promise<boolean>;
     /** Close the owned browser once. Idempotent and safe before navigate. */

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

@@ -1,12 +1,25 @@
+/**
+ * Optional CDP/Playwright real-input mode.
+ *
+ * Synthetic `dispatchEvent` cannot drive native hover/pointer state (an onMouseEnter never
+ * fires, hit-testing never runs). When a CDP endpoint is configured, this module connects a
+ * Playwright `Browser` over CDP and drives REAL pointer/keyboard input against the element box
+ * the SDK resolves (viewport CSS px from getBoundingClientRect).
+ *
+ * Node-only. Playwright is loaded via DYNAMIC `import('playwright')` so non-CDP users never
+ * 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 { stampedDriveUrl } from './drive-url-stamp.js';
-import { chromiumLaunchOptions } from '../../chromium-launch-options.js';
-import { gotoOptions } from '../pool/playwright-launcher.js';
+import { launchChromium } from '../../launch-chromium.js';
+import { chromiumLaunchHint, gotoOptions } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG } 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;
@@ -130,6 +143,8 @@ export class CdpRealInputProvider {
     /** Pages already listening. #pageFor resolves on EVERY call, so without this each action would add
      *  another listener and every response would be emitted once per action taken so far. */
     #listening = new WeakSet();
+    /** Pages collecting V8 coverage — see js-coverage.ts. */
+    #covering = new WeakSet();
     #browser;
     constructor(options) {
         this.#cdpUrl = options.cdpUrl;
@@ -175,6 +190,10 @@ export class CdpRealInputProvider {
             this.#listen(page);
         return page;
     }
+    async takeCodeCoverage(sessionUrl) {
+        const page = await this.#pageFor(sessionUrl);
+        return page === undefined ? undefined : takeJsCoverage(page, this.#covering);
+    }
     async isAvailableFor(sessionUrl) {
         try {
             return (await this.#pageFor(sessionUrl)) !== undefined;
@@ -272,13 +291,14 @@ export const launchedChromium = async (headless) => {
     }
     const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.LAUNCHED);
     try {
-        const browser = await mod.chromium.launch(chromiumLaunchOptions(headless));
+        const browser = await launchChromium(mod.chromium, headless);
         settle();
         return browser;
     }
     catch (e) {
         settle(classifyConnectFailure(e));
-        throw new DriveError(DriveErrorCode.LAUNCH_FAILED, e instanceof Error ? e.message : String(e));
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new DriveError(DriveErrorCode.LAUNCH_FAILED, chromiumLaunchHint(msg) ?? msg);
     }
 };
 /**
@@ -295,6 +315,8 @@ export class LaunchedRealInputProvider {
     #onNetworkDetail;
     #browser;
     #page;
+    /** Pages collecting V8 coverage — see js-coverage.ts. */
+    #covering = new WeakSet();
     constructor(options) {
         this.#driveUrl = options.driveUrl;
         this.#headless = options.headless;
@@ -338,7 +360,7 @@ export class LaunchedRealInputProvider {
             await page.waitForFunction('!!globalThis.__reticleInstance', {
                 timeout: INJECT_CONNECT_WAIT_MS,
             });
-            const arg = JSON.stringify({ allowNonLocalhost: true, token: opts.token, url: opts.url });
+            const arg = JSON.stringify(injectedConnectArgs(opts));
             await page.evaluate(`globalThis.__reticleInstance.connect(${arg})`);
         }
         catch {
@@ -441,6 +463,10 @@ export class LaunchedRealInputProvider {
         await page.setViewportSize({ width: size.width, height: size.height });
         return true;
     }
+    takeCodeCoverage(_sessionUrl) {
+        const page = this.#livePage();
+        return page === undefined ? Promise.resolve(undefined) : takeJsCoverage(page, this.#covering);
+    }
     /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
     async setMocks(_sessionUrl, rules) {
         const page = this.#livePage();

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

@@ -18,6 +18,11 @@ export interface Lease {
     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.
+     */
+    injectReader?(): 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;
@@ -32,6 +37,11 @@ interface BrowserPoolOptions {
     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;
 }
 /**
  * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.

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

@@ -30,6 +30,7 @@ export class BrowserPool {
     #genId;
     #now;
     #ttl;
+    #zeroInstall;
     #navTimeout;
     #browser;
     #launching;
@@ -70,6 +71,7 @@ export class BrowserPool {
         this.#now = opts.now ?? (() => Date.now());
         this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
+        this.#zeroInstall = opts.zeroInstallScript;
     }
     /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
     leaseTtlMs() {
@@ -405,6 +407,14 @@ export class BrowserPool {
                 url,
                 ...(navStatus !== undefined ? { navStatus } : {}),
                 release: () => this.#release(sessionId),
+                injectReader: async () => {
+                    const script = this.#zeroInstall?.();
+                    if (script === undefined || page.evaluate === undefined)
+                        return false;
+                    await page.addInitScript?.(script);
+                    await page.evaluate(script);
+                    return true;
+                },
             };
         }
         catch (err) {

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

@@ -25,6 +25,12 @@ export declare function gotoOptions(timeoutMs: number | undefined): {
 export declare function playwrightLauncher(opts?: {
     headless?: boolean;
 }): Launcher;
+/**
+ * Turn Playwright's raw launch error into the one command that fixes it, or undefined when it is
+ * not a missing-browser failure. Shared by the pooled and the drive launch, so `reticle verify` on
+ * a fresh machine gets the same advice as a lease.
+ */
+export declare function chromiumLaunchHint(msg: string): string | undefined;
 /**
  * Resolve the pool's concurrency cap. An explicit RETICLE_MAX_CONTEXTS wins (clamped to
  * [1, hard ceiling]); otherwise scale with the machine but never above the CPU-derived ceiling.

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

@@ -6,7 +6,7 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
-import { chromiumLaunchOptions } from '../../chromium-launch-options.js';
+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';
@@ -41,6 +41,7 @@ function wrapBrowser(browser) {
                     return {
                         goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
                         close: () => page.close(),
+                        evaluate: (script) => page.evaluate(script),
                         // Playwright returns a Buffer; Uint8Array is what the visual store and differ take.
                         screenshot: async (opts) => new Uint8Array(await page.screenshot({ fullPage: true === opts?.fullPage })),
                         // Three moves, same as performGesture: a single move to the center can be a no-op if
@@ -104,27 +105,34 @@ export function playwrightLauncher(opts = {}) {
         // number that actually costs memory and the one that explains a slow machine.
         const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
         try {
-            const browser = wrapBrowser(await chromium.launch(chromiumLaunchOptions(headless)));
+            const browser = wrapBrowser(await launchChromium(chromium, headless));
             settle();
             return browser;
         }
         catch (err) {
             settle(classifyConnectFailure(err));
-            // Turn Playwright's raw "Executable doesn't exist" into the one command that fixes it.
             const msg = err instanceof Error ? err.message : String(err);
-            // Checked FIRST: Playwright's host-requirement validation error also contains
-            // "browserType.launch", so the generic check below would otherwise misdiagnose it as a
-            // missing binary and send the user through a fix that changes nothing.
-            if (/host system is missing dependencies/i.test(msg)) {
-                throw new Error(CHROMIUM_MISSING_DEPS_HINT);
-            }
-            if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
-                throw new Error(CHROMIUM_MISSING_HINT);
-            }
-            throw err;
+            const hint = chromiumLaunchHint(msg);
+            throw hint !== undefined ? new Error(hint) : err;
         }
     };
 }
+/**
+ * Turn Playwright's raw launch error into the one command that fixes it, or undefined when it is
+ * not a missing-browser failure. Shared by the pooled and the drive launch, so `reticle verify` on
+ * a fresh machine gets the same advice as a lease.
+ */
+export function chromiumLaunchHint(msg) {
+    // Checked FIRST: Playwright's host-requirement validation error also contains
+    // "browserType.launch", so the generic check below would otherwise misdiagnose it as a
+    // missing binary and send the user through a fix that changes nothing.
+    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 undefined;
+}
 const MAX_CONTEXTS_CEILING = 8;
 const MAX_CONTEXTS_FLOOR = 1;
 /**

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

@@ -34,6 +34,8 @@ export interface PooledPage {
      * reports dispatched/settled while the styles never ran.
      */
     hover?(x: number, y: number): 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. */
     addInitScript?<Arg>(script: ((arg: Arg) => void) | string, arg?: Arg): Promise<InitScriptHandle | void>;
     /**

package/dist/portal/pool/storage-seed.d.ts

@@ -2,7 +2,7 @@ import { type SeedStorage } from '@reticlehq/core';
 import type { InitScriptHandle, PooledContext, PooledCookie, PooledPage } from './pool-contract.js';
 export declare function targetOriginOf(navUrl: string): string | undefined;
 export declare function normalizeCookies(cookies: SeedStorage['cookies'], navUrl: string): PooledCookie[];
-export interface StorageSeedResult {
+interface StorageSeedResult {
     handle?: InitScriptHandle;
     checkError?: () => void;
 }
@@ -21,3 +21,4 @@ export interface StorageSeedResult {
  * has resolved, ensuring one-time semantics (reloads or future navigations do not reapply the seed).
  */
 export declare function seedStorageInto(context: PooledContext, page: PooledPage, targetUrl: string, seed: SeedStorage): Promise<StorageSeedResult | void>;
+export {};

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

@@ -0,0 +1,27 @@
+export interface InjectedConnect {
+    url: string;
+    /** Absent when this daemon runs without a pairing token; the bridge then asks for none. */
+    token?: string;
+}
+/**
+ * The connect options a page is given when WE supply the connection rather than the app.
+ *
+ * One builder for both injection paths — this one, and re-pointing an SDK a hosted preview already
+ * 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>;
+/**
+ * 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.
+ */
+export declare function zeroInstallScript(bundle: string, opts: InjectedConnect): string;
+/**
+ * The single-file build, or undefined when this install has none.
+ *
+ * Read once and kept: it is ~450KB and identical for every lease. Absent means an older browser
+ * package or a broken install, and the caller then behaves exactly as it did before this existed.
+ */
+export declare function readReaderBundle(): string | undefined;

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

@@ -0,0 +1,54 @@
+/**
+ * The zero-install reader: how a page whose app never ran `init` still reaches a verdict.
+ *
+ * `@reticlehq/browser` builds itself into one file (`dist/reticle-inject.js`). The daemon reads that
+ * file as TEXT and evaluates it in a leased page that never connected, so the server never imports DOM
+ * code and the page needs no build step. What comes back is an ordinary session that reports no
+ * framework adapter and no source mapping, which is the honest description of what it can see.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/** The subpath `@reticlehq/browser` exports its single-file build under. */
+const READER_SPECIFIER = '@reticlehq/browser/inject';
+/**
+ * The connect options a page is given when WE supply the connection rather than the app.
+ *
+ * One builder for both injection paths — this one, and re-pointing an SDK a hosted preview already
+ * ships (`real-input.ts`) — so the two cannot come to disagree about what a daemon-driven page needs.
+ */
+export function injectedConnectArgs(opts) {
+    return {
+        allowNonLocalhost: true,
+        ...(opts.token === undefined ? {} : { token: opts.token }),
+        url: opts.url,
+    };
+}
+/**
+ * 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.
+ */
+export function zeroInstallScript(bundle, opts) {
+    const args = JSON.stringify(injectedConnectArgs(opts));
+    return `(() => {\nif (!globalThis.__reticleInstance) {\n${bundle}\n}\nglobalThis.__reticleInstance.connect(${args});\n})();`;
+}
+let cached;
+/**
+ * The single-file build, or undefined when this install has none.
+ *
+ * Read once and kept: it is ~450KB and identical for every lease. Absent means an older browser
+ * package or a broken install, and the caller then behaves exactly as it did before this existed.
+ */
+export function readReaderBundle() {
+    if (cached === undefined) {
+        try {
+            cached = readFileSync(createRequire(import.meta.url).resolve(READER_SPECIFIER), 'utf8');
+        }
+        catch {
+            cached = null;
+        }
+    }
+    return cached ?? undefined;
+}

package/dist/portal/realm/web-realm.js

@@ -93,6 +93,11 @@ export const CHANNEL_OF_PREFIX = {
     // channel at all.
     anim: ProtocolChannel.UI,
     dialog: ProtocolChannel.UI,
+    // A form field's value is on the subject's surface in exactly the sense `ui` means: it is what
+    // the person is looking at and typing into. The protocol has no `input` channel and does not
+    // want one — a field is a rendered thing, and the observation carries the field's NAME and
+    // length, never its contents for a password or a card.
+    field: ProtocolChannel.UI,
     focus: ProtocolChannel.UI,
     render: ProtocolChannel.UI,
     reveal: ProtocolChannel.UI,
@@ -124,6 +129,7 @@ export const NOT_EVIDENCE = {
     context: "Reticle's own context tool opening, not something the application did",
     flow: 'a flow being recorded by the tool',
     human: 'a person driving the HUD: pause, resume, a mark. The operator, not the subject',
+    hud: "usage telemetry about Reticle's own panel, taken off before the buffer. The tool, not the subject",
     page: "the SDK's own health report about the page it is inside",
     sdk: 'the SDK itself failing, which is a fact about the observer',
     transport: "the tool's own buffer overflowing",

package/dist/portal/session/dev-server/dev-command.d.ts

@@ -12,8 +12,8 @@
 export interface DevCommand {
     /** The literal shell command, e.g. `pnpm run dev`. */
     command: string;
-    /** The package.json script it runs. */
-    script: string;
+    /** The package.json script it runs. Absent when the command runs a CLI directly (`npx tauri dev`). */
+    script?: string;
     /** The port the script PINS, when it pins one. Absent means the tool picks — never a guess. */
     port?: number;
 }