@reticlehq/server 3.9.0 → 3.10.0

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

@@ -1,13 +1,26 @@
 /**
- * Install the lease's uncaught-error listener. Call BEFORE the first navigation — the listener
- * timing is the whole fix: an import-time throw lands during `goto`, and one attached after it
- * reads a broken page as healthy. Forwarded with the lease id, because the session for this lease
- * usually does not exist yet, so the sink buffers.
+ * The page-error side of a lease: listen for the throws the SDK will never see, and tell the
+ * wiring when the lease is gone.
+ *
+ * An app whose module graph throws during the first navigation fires its `error` event while the
+ * page still has no Reticle SDK in it — the zero-install reader is only evaluated after `goto`
+ * resolves — so nothing on the page records it, and a blank page reported as a bare console-error
+ * count (#1966). The server's Playwright handle is attached before the navigation, so it is the
+ * one witness that cannot miss the throw. This module owns that wiring for `BrowserPool`; the
+ * journal that buffers and journals what arrives lives in `page-error-journal.ts`.
  */
-export function listenForPageErrors(page, leaseId, hooks) {
+import { RETICLE_EARLY_CAPTURE } from '@reticlehq/core';
+/**
+ * Install the lease's uncaught-error listener and its early console queue. Call BEFORE the first
+ * navigation — the timing is the whole fix: an import-time throw lands during `goto`, and one
+ * attached after it reads a broken page as healthy. Forwarded with the lease id, because the
+ * session for this lease usually does not exist yet, so the sink buffers.
+ */
+export async function listenForPageErrors(page, leaseId, hooks) {
     page.onPageError?.((error) => {
         hooks?.onPageError?.(leaseId, error);
     });
+    await page.addInitScript?.(queueEarlyConsole, EARLY_CAPTURE_ARG);
 }
 /**
  * Report a closed lease — manual release, reaper and crash reclaim all funnel through the pool's
@@ -16,3 +29,132 @@ export function listenForPageErrors(page, leaseId, hooks) {
 export function reportLeaseClosed(hooks, leaseId) {
     hooks?.onLeaseClosed?.(leaseId);
 }
+/** How many console calls and error events a page keeps for an SDK that has not installed yet. */
+export const EARLY_CAPTURE_LIMIT = 200;
+/**
+ * The argument for `queueEarlyConsole`. Every driven page gets the same one: a pool lease, and
+ * `verify`'s own page. It looks for the SDK every `pollMs`, for at most `maxPolls` looks (30 s).
+ */
+export const EARLY_CAPTURE_ARG = {
+    key: RETICLE_EARLY_CAPTURE,
+    limit: EARLY_CAPTURE_LIMIT,
+    pollMs: 50,
+    maxPolls: 600,
+};
+/**
+ * Init script: keep the console errors and warnings a page logs before the SDK installs.
+ *
+ * An app connects the SDK from a module script or a bundle, and both run after the page's own
+ * classic scripts. An error such a script logs while the page loads was lost, so "no console
+ * errors" passed on a page that logged one on every load. Playwright's own console event is not a
+ * substitute: it also reports messages the browser writes itself (a failed WebSocket, which is how
+ * the SDK's own first dial can fail), and the SDK's console channel has never counted those.
+ *
+ * So this keeps the RAW calls and events. Once the SDK has wrapped the console, this hands them to
+ * it: each call goes through the console again and each event is dispatched again, so the SDK's own
+ * handlers report them and the meaning of "console error" stays the SDK's. The SDK needs no code for
+ * this, so a page that Reticle does not drive downloads nothing for it. Entries the bound did not
+ * keep are declared with one console warning. Must stay self-contained: Playwright serialises the
+ * function source into the page.
+ */
+export function queueEarlyConsole(arg) {
+    const win = globalThis.window;
+    if (win === undefined || win[arg.key] !== undefined) {
+        return;
+    }
+    const capture = { queue: [], dropped: 0 };
+    win[arg.key] = capture;
+    const keep = (item) => {
+        if (win[arg.key] !== capture) {
+            return;
+        }
+        if (capture.queue.length < arg.limit) {
+            capture.queue.push(item);
+        }
+        else {
+            capture.dropped += 1;
+        }
+    };
+    const mine = {};
+    for (const method of ['error', 'warn']) {
+        const original = win.console[method];
+        const wrapper = (...args) => {
+            keep({ method, args });
+            original.apply(win.console, args);
+        };
+        mine[method] = wrapper;
+        win.console[method] = wrapper;
+    }
+    win.addEventListener('error', (event) => keep({ event }), true);
+    win.addEventListener('unhandledrejection', (event) => keep({ event }), true);
+    // A copy of a kept event: an event that has been dispatched once is copied, not sent again.
+    const copy = (event) => {
+        if ('reason' in event) {
+            return new win.PromiseRejectionEvent('unhandledrejection', {
+                promise: event['promise'],
+                reason: event['reason'],
+            });
+        }
+        const init = {};
+        for (const field of ['message', 'filename', 'lineno', 'colno', 'error']) {
+            if (event[field] !== undefined) {
+                init[field] = event[field];
+            }
+        }
+        return new win.ErrorEvent('error', init);
+    };
+    // A `<script>`, `<img>` or `<link>` that failed to load dispatches a plain `Event` on its element,
+    // and only the element names the URL. A copy on `window` loses it, and the SDK reported an error
+    // with no message, no source and line 0 (#2220). So such an event is sent again from the same
+    // element, and the SDK's capture listener on `window` reads the tag and the URL. A listener added
+    // after the SDK's stops it on `window`, so the page's own handlers on the element do not run twice.
+    // An element that left the page cannot reach `window`, so it gets the copy.
+    const resend = (event) => {
+        const target = event['target'];
+        if ('message' in event || 'reason' in event || true !== target?.isConnected) {
+            return false;
+        }
+        const again = new win.Event('error');
+        const stop = (seen) => {
+            if (seen === again) {
+                again.stopPropagation();
+            }
+        };
+        win.addEventListener('error', stop, true);
+        try {
+            target.dispatchEvent?.(again);
+        }
+        finally {
+            win.removeEventListener('error', stop, true);
+        }
+        return true;
+    };
+    let polls = 0;
+    const timer = win.setInterval(() => {
+        polls += 1;
+        // The SDK has installed when the console is no longer this script's own wrapper.
+        const installed = win.console.error !== mine.error;
+        if (!installed && polls < arg.maxPolls) {
+            return;
+        }
+        win.clearInterval(timer);
+        win[arg.key] = null;
+        if (!installed) {
+            return;
+        }
+        for (const item of capture.queue) {
+            if ('method' in item) {
+                win.console[item['method']](...item['args']);
+            }
+            else {
+                const event = item['event'];
+                if (!resend(event)) {
+                    win.dispatchEvent(copy(event));
+                }
+            }
+        }
+        if (capture.dropped > 0) {
+            win.console.warn(`reticle: ${String(capture.dropped)} early console entries were not kept`);
+        }
+    }, arg.pollMs);
+}

package/dist/portal/pool/page-error-journal.d.ts

@@ -25,7 +25,7 @@
  * only the redundant second copy is cost, not wrong evidence.
  */
 import { type ReticleEvent } from '@reticlehq/core';
-import type { PooledPageError } from './pool-contract.js';
+import type { PooledDialog, PooledPageError } from './pool-contract.js';
 /** The session surface the journal needs. The real `Session` satisfies this structurally. */
 export interface JournalableSession {
     readonly id: string;
@@ -43,6 +43,12 @@ export interface PageErrorJournal {
     onLeaseClosed(leaseId: string): void;
     /** The bridge hook — register with `bridge.attachSessionEnd`. */
     onSessionEnd(sessionId: string): void;
+    /**
+     * The pool's dialog sink — hand it to `BrowserPoolOptions.onDialog`. Journals the dismissal as
+     * `dialog.opened` on the lease's session, so a verdict reads it as the SDK's own answer. A dialog
+     * before the session connects is dropped: no action window can hold it.
+     */
+    onPoolDialog(leaseId: string, dialog: Pick<PooledDialog, 'kind' | 'message'>): void;
 }
 /**
  * Fold the two spellings of one throw into one identity. Chromium prefixes a window-reported

package/dist/portal/pool/page-error-journal.js

@@ -25,6 +25,16 @@
  * only the redundant second copy is cost, not wrong evidence.
  */
 import { CONSOLE_EVENT, EventType, RETICLE_URL_PARAM } from '@reticlehq/core';
+/**
+ * What a dismissal answers, per dialog kind the wire knows. The same replies the SDK gives
+ * (`observers/dialogs.ts`): `confirm` is "no", `prompt` is no value, `alert` has no answer.
+ * A kind not in this map (`beforeunload`) is not a `dialog.opened` and is not reported.
+ */
+const DISMISSED_ANSWER = {
+    alert: {},
+    confirm: { answered: false },
+    prompt: { answered: null },
+};
 /** How many errors wait per lease for a session that may never connect. Older ones give way. */
 const MAX_BUFFERED_PER_LEASE = 8;
 /** How many recent error identities a session tracks — the dedupe memory for both sources. */
@@ -177,5 +187,22 @@ export function makePageErrorJournal(deps) {
         onSessionEnd(sessionId) {
             seen.delete(sessionId);
         },
+        onPoolDialog(leaseId, dialog) {
+            // An own key only: an inherited name such as `toString` is not a dialog kind.
+            const kind = dialog.kind;
+            const answer = kind !== undefined && Object.hasOwn(DISMISSED_ANSWER, kind)
+                ? DISMISSED_ANSWER[kind]
+                : undefined;
+            const session = deps.resolveSession(leaseId);
+            if (answer === undefined || session === undefined) {
+                return;
+            }
+            session.pushEvent({
+                t: 0, // pushEvent re-stamps with the session's own clock
+                type: EventType.DIALOG_OPENED,
+                sessionId: session.id,
+                data: { kind: dialog.kind, message: dialog.message, ...answer },
+            });
+        },
     };
 }

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

@@ -5,6 +5,7 @@
  *
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
+import { startJsCoverage, takeJsCoverage } from '../input/js-coverage.js';
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { ActionType, HIDE_RETICLE_CHROME_CSS, RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
 import { launchChromium } from '../../launch-chromium.js';
@@ -15,6 +16,8 @@ import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVe
 import { installNetworkMocks } from '../input/network-mock.js';
 import { performGesture, withChromePassThrough, } from '../input/real-input.js';
 import { widenDocumentCsp } from './csp-widen.js';
+import { contextEmulationOf } from './lease-emulation.js';
+import { determinismConfigOf, installDeterminism } from './determinism.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));
@@ -93,20 +96,48 @@ export function gotoOptions(timeoutMs) {
         ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
     };
 }
+/**
+ * Reload with the cache ignored, as Cmd+Shift+R does (#1785).
+ *
+ * Playwright's `page.reload()` is a plain reload: a module with a fresh cache entry is not fetched
+ * again. The DevTools protocol's `Page.reload { ignoreCache: true }` is the browser's own hard
+ * reload. The pool launches Chromium, so the protocol is always there.
+ */
+async function reloadIgnoringCache(page) {
+    const cdp = await page.context().newCDPSession(page);
+    try {
+        await cdp.send('Page.reload', { ignoreCache: true });
+    }
+    finally {
+        await cdp.detach();
+    }
+}
 function wrapBrowser(browser, headless) {
     return {
         isConnected: () => browser.isConnected(),
         newContext: async (opts) => {
-            // Media and viewport ride on the context, so the first paint of the first page has them.
-            const { ignoreHTTPSErrors, ...emulate } = opts ?? {};
+            // Media, viewport and pointer ride on the context, so the first paint of the first page has
+            // them. `pointer` becomes `hasTouch` here — see contextEmulationOf.
+            const { ignoreHTTPSErrors, jsCoverage, ...emulate } = opts ?? {};
+            const covering = new WeakSet();
+            // A deterministic context needs a fixed viewport: a density is not set on a window's own size.
+            const deterministic = emulate.deterministic;
             const context = await browser.newContext({
                 ...(true === ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
-                ...emulate,
-                ...pageViewportOptions(headless, emulate.viewport),
+                ...contextEmulationOf(emulate),
+                ...pageViewportOptions(headless || deterministic !== undefined, emulate.viewport),
             });
+            // On the context, so every page and frame of the lease gets it before its first script.
+            if (deterministic !== undefined) {
+                await context.addInitScript(installDeterminism, determinismConfigOf(deterministic));
+            }
             return {
                 newPage: async () => {
                     const page = await context.newPage();
+                    // Before the first navigation, so the code that runs while the page loads is counted.
+                    if (true === jsCoverage) {
+                        await startJsCoverage(page, covering);
+                    }
                     return {
                         goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
                         close: () => page.close(),
@@ -129,6 +160,7 @@ function wrapBrowser(browser, headless) {
                             await page.mouse.move(x + 1, y);
                             await page.mouse.move(x, y);
                         }),
+                        reloadIgnoringCache: () => reloadIgnoringCache(page),
                         // 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),
@@ -148,6 +180,10 @@ function wrapBrowser(browser, headless) {
                             });
                         },
                         setViewport: (size) => page.setViewportSize(size),
+                        jsCoverage: {
+                            start: () => startJsCoverage(page, covering),
+                            take: () => covering.has(page) ? takeJsCoverage(page, covering) : Promise.resolve(undefined),
+                        },
                         bringToFront: () => page.bringToFront(),
                         onCrash: (handler) => page.on('crash', handler),
                         onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
@@ -157,7 +193,11 @@ function wrapBrowser(browser, headless) {
                             message: error.message,
                             ...(error.stack === undefined ? {} : { stack: error.stack }),
                         })),
-                        onDialog: (handler) => page.on('dialog', (dialog) => handler({ message: dialog.message(), dismiss: () => dialog.dismiss() })),
+                        onDialog: (handler) => page.on('dialog', (dialog) => handler({
+                            message: dialog.message(),
+                            kind: dialog.type(),
+                            dismiss: () => dialog.dismiss(),
+                        })),
                         addInitScript: async (script, arg) => {
                             const handle = (await page.addInitScript(script, arg));
                             const dispose = handle?.dispose;
@@ -216,11 +256,13 @@ 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)
+    if (null === found) {
         return undefined;
+    }
     const captured = found[1];
-    if (undefined === captured)
+    if (undefined === captured) {
         return undefined;
+    }
     const path = captured.trim();
     return '' === path ? undefined : path;
 }
@@ -267,8 +309,9 @@ 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))
+    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 chromiumMissingHint(pathFromPlaywrightError(msg));
     }

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

@@ -7,6 +7,14 @@
  */
 import type { RealInputArgs, RealInputResult } from '../input/real-input.js';
 import type { LeaseEmulation, LeaseMedia } from './lease-emulation.js';
+import type { ScriptCoverage } from '../input/js-coverage.js';
+/** JS coverage on one page: start it, and take what ran since the previous take. */
+export interface PooledCoverage {
+    /** False when the page cannot measure coverage. */
+    start(): Promise<boolean>;
+    /** Undefined when coverage was not running; the first take does not start it. */
+    take(): Promise<ScriptCoverage[] | undefined>;
+}
 /** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
 export interface PooledPage {
     goto(url: string, opts?: {
@@ -47,6 +55,11 @@ export interface PooledPage {
      * page without it keeps the in-page dispatcher, whose synthetic Tab moves no focus.
      */
     press?(args: RealInputArgs): Promise<RealInputResult>;
+    /**
+     * Reload the page with the browser cache ignored for the document and every subresource, as
+     * Cmd+Shift+R does. OPTIONAL: without it a hard reload can only re-fetch the document (#1785).
+     */
+    reloadIgnoringCache?(): Promise<void>;
     /** 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. */
@@ -92,11 +105,18 @@ export interface PooledPage {
      * hidden, and a hidden tab throttles timers and rAF so nothing on it verifies (#1351).
      */
     bringToFront?(): Promise<void>;
+    /**
+     * JS coverage of this page. OPTIONAL, like `installMocks`: a page without it makes the
+     * coverage tool refuse rather than report that no code ran.
+     */
+    jsCoverage?: PooledCoverage;
 }
 /** A native dialog the page opened, handed to the pool so it can be dismissed instead of left blocking. */
 export interface PooledDialog {
     /** The dialog's message text — kept for diagnostics (`BrowserPool#lastDialogMessage`). */
     readonly message: string;
+    /** `alert`, `confirm`, `prompt` or `beforeunload`, as the engine names it. Absent: not known. */
+    readonly kind?: string;
     dismiss(): Promise<void>;
 }
 /**
@@ -133,6 +153,8 @@ export interface PooledMockRule {
     contentType?: string;
     delayMs?: number;
     abort?: boolean;
+    /** Send the request on to this origin; the path and query stay (see network-mock.ts). */
+    forwardTo?: string;
 }
 /** An isolated browsing context (cookies/storage). Real Playwright `BrowserContext` satisfies this. */
 export interface PooledContext {
@@ -159,9 +181,13 @@ export interface PooledContext {
 /** The launched browser. Real Playwright `Browser` satisfies this. */
 export interface PooledBrowser {
     isConnected(): boolean;
-    /** `ignoreHTTPSErrors` accepts a self-signed or local-CA certificate for this context only. */
+    /**
+     * `ignoreHTTPSErrors` accepts a self-signed or local-CA certificate for this context only.
+     * `jsCoverage` starts JS coverage on each page before its first script runs.
+     */
     newContext(opts?: {
         ignoreHTTPSErrors?: boolean;
+        jsCoverage?: boolean;
     } & LeaseEmulation): Promise<PooledContext>;
     close(): Promise<void>;
     /** Fires when the browser process dies/crashes so the pool can relaunch on the next acquire. */

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

@@ -2,7 +2,37 @@
  * 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, PooledPageError } from './pool-contract.js';
+import type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledDialog, PooledPage, PooledPageError } from './pool-contract.js';
+import type { SeedStorage } from '@reticlehq/core';
+import type { LeaseEmulation } from './lease-emulation.js';
+/** What one `BrowserPool#acquire` asks for. Every field is optional. */
+export interface AcquireOptions {
+    signal?: AbortSignal;
+    /**
+     * `'wait'` (the default) queues behind the cap. `'refuse'` is for a caller that has a person
+     * or an agent waiting on the answer and no way to see a queue: it is told the pool is full.
+     */
+    whenFull?: 'wait' | 'refuse';
+    sessionId?: string;
+    seedStorage?: SeedStorage;
+    owner?: string;
+    /** In a browser with a window the person can watch. */
+    headed?: boolean;
+    /**
+     * JavaScript installed before any page script runs, for this lease only. A view built for a
+     * desktop shell calls bindings the shell injects (`window.go`, `window.runtime`, a preload
+     * object) on mount; a stub here is what lets it reach its data path in a leased tab.
+     */
+    initScript?: string;
+    /** Granted on the lease's origin before the first navigation, so the first render sees them. */
+    permissions?: readonly string[];
+    /** Accept a self-signed or local-CA dev certificate for this lease's context only (#1255). */
+    ignoreHTTPSErrors?: boolean;
+    /** Media and viewport set on the context, so the first paint already has them. */
+    emulate?: LeaseEmulation;
+    /** Start JS coverage before the page's first script, so load-time code is counted. */
+    jsCoverage?: boolean;
+}
 /** A leased context+page for one flow. `release` frees the slot and closes the context. */
 export interface Lease {
     readonly sessionId: string;
@@ -67,6 +97,11 @@ export interface BrowserPoolOptions {
      * holding it for the life of the daemon. Optional: no sink, nothing to clean up.
      */
     onLeaseClosed?: (leaseId: string) => void;
+    /**
+     * Sink for each native dialog the pool dismissed, with the lease id. The dismissal is an answer
+     * of "no" on the app's behalf, so the wiring records it for the verdict (#1350). Optional.
+     */
+    onDialog?: (leaseId: string, dialog: Pick<PooledDialog, 'kind' | 'message'>) => void;
     /**
      * 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.

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

@@ -25,6 +25,14 @@ export declare function zeroInstallScript(bundle: string, opts: InjectedConnect)
 export declare class NotHtmlDocumentError extends Error {
     constructor();
 }
+/**
+ * Run the reader in a leased page now, and again before the page's own scripts on each later load.
+ * False when there is no reader or the page cannot run one; throws when the page is not HTML.
+ */
+export declare function injectReaderInto(page: {
+    evaluate?(script: string): Promise<unknown>;
+    addInitScript?(script: string): unknown;
+}, script: string | undefined): Promise<boolean>;
 /**
  * The single-file build, or undefined when this install has none.
  *

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

@@ -35,6 +35,14 @@ const HTML_CONTENT_TYPES = ['text/html', 'application/xhtml+xml'];
  * 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.
  */
+/*
+ * Run in the top frame only. Playwright runs an init script in every frame, and a rich-text editor's
+ * editing area is an iframe whose <body> IS the document being edited: the SDK mounted its HUD there,
+ * and saving the form stored the HUD markup in the app's data (Dolibarr product and project
+ * descriptions). The top frame's SDK already reads same-origin iframes, so a child frame needs nothing.
+ * A context with no `top` (a test sandbox) counts as the top frame.
+ */
+const TOP_FRAME_ONLY = 'if (globalThis.top !== undefined && globalThis.self !== undefined && globalThis.top !== globalThis.self) return;';
 const NOT_HTML_GUARD = `if (globalThis.document !== undefined && !${JSON.stringify(HTML_CONTENT_TYPES)}.includes(globalThis.document.contentType)) ` +
     `return ${JSON.stringify(READER_NOT_HTML)};`;
 /*
@@ -115,7 +123,7 @@ const ZOD_JITLESS = `(${ZOD_CONFIG} ??= {}).jitless ??= true;`;
  */
 export function zeroInstallScript(bundle, opts) {
     const args = JSON.stringify(injectedConnectArgs(opts));
-    return `(() => {\n${NOT_HTML_GUARD}\nif (!globalThis.__reticleInstance) {\n${EARLY_KEEP}\n${ZOD_JITLESS}\n${bundle}\n}\n${CONNECT_WHEN_DOM_READY(args)}\n})();`;
+    return `(() => {\n${TOP_FRAME_ONLY}\n${NOT_HTML_GUARD}\nif (!globalThis.__reticleInstance) {\n${EARLY_KEEP}\n${ZOD_JITLESS}\n${bundle}\n}\n${CONNECT_WHEN_DOM_READY(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 {
@@ -124,6 +132,20 @@ export class NotHtmlDocumentError extends Error {
         this.name = 'NotHtmlDocumentError';
     }
 }
+/**
+ * Run the reader in a leased page now, and again before the page's own scripts on each later load.
+ * False when there is no reader or the page cannot run one; throws when the page is not HTML.
+ */
+export async function injectReaderInto(page, script) {
+    if (script === undefined || page.evaluate === undefined) {
+        return false;
+    }
+    await page.addInitScript?.(script);
+    if (READER_NOT_HTML === (await page.evaluate(script))) {
+        throw new NotHtmlDocumentError();
+    }
+    return true;
+}
 let cached;
 /**
  * The single-file build, or undefined when this install has none.

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

@@ -20,13 +20,14 @@ export interface DevCommand {
     directory?: string;
 }
 /**
- * The direct child folders of `directory` that are apps with a dev command, sorted by name.
+ * The direct child folders of `directory` that are apps with a dev command, sorted by name: the web
+ * apps when there are any, every dev-script folder when there are none (see `preferWebApps`).
  *
  * Only for a folder with no package.json of its own. A task folder holds the app one level down, and
- * no workspace file lists it, so `workspacePackageDirs` never finds it. Folders that are not apps
- * (no package.json, or no dev script), `node_modules` and hidden folders are skipped.
+ * no workspace file lists it, so `workspacePackageDirs` never finds it. `node_modules`, hidden
+ * folders and folders with no dev script are never candidates.
  */
-export declare function childDevApps(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[]): readonly string[];
+export declare function childDevApps(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[], writable?: (path: string) => boolean): readonly string[];
 /**
  * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
  *
@@ -43,7 +44,7 @@ export declare function detectDevCommand(directory: string, read?: (path: string
  * init's own workspace listing answers which directories to consider; the root's lockfile picks the
  * package manager, because a workspace package usually has no lockfile of its own.
  */
-export declare function detectDevCommandInProject(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[]): DevCommand | undefined;
+export declare function detectDevCommandInProject(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[], writable?: (path: string) => boolean): DevCommand | undefined;
 /**
  * The command that wires THIS project for good: `init`, in the app's own folder, through the
  * one-off runner the project's package manager ships.
@@ -52,4 +53,4 @@ export declare function detectDevCommandInProject(directory: string, read?: (pat
  * time: `init` run in a folder that is not the app stops on a missing package.json, and a runner the
  * machine does not have is "command not found". npx whenever there is doubt — it ships with Node.
  */
-export declare function initCommandIn(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[]): string;
+export declare function initCommandIn(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[], writable?: (path: string) => boolean): string;