@reticlehq/server 3.8.2 → 3.10.0

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

@@ -5,14 +5,19 @@
  *
  * 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';
+import { pageViewportOptions } from '../../chromium-launch-options.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';
+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));
@@ -91,20 +96,48 @@ export function gotoOptions(timeoutMs) {
         ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
     };
 }
-function wrapBrowser(browser) {
+/**
+ * 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 ?? {};
-            const contextOpts = {
+            // 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,
-            };
-            const context = await browser.newContext(0 < Object.keys(contextOpts).length ? contextOpts : undefined);
+                ...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(),
@@ -121,11 +154,13 @@ function wrapBrowser(browser) {
                         },
                         // Three moves, same as performGesture: a single move to the center can be a no-op if
                         // the pointer was already there, and CSS :hover needs a native hit-test to apply.
-                        hover: async (x, y) => {
+                        // Through Reticle's own UI, like every other real gesture (#992).
+                        hover: (x, y) => withChromePassThrough(page, async () => {
                             await page.mouse.move(x, y);
                             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),
@@ -145,10 +180,24 @@ function wrapBrowser(browser) {
                             });
                         },
                         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())),
-                        onDialog: (handler) => page.on('dialog', (dialog) => handler({ message: dialog.message(), dismiss: () => dialog.dismiss() })),
+                        // Playwright's `pageerror` carries the full exception even when the page's own window
+                        // listener never ran — the import-time throw that lands before any SDK is injected.
+                        onPageError: (handler) => page.on('pageerror', (error) => handler({
+                            message: error.message,
+                            ...(error.stack === undefined ? {} : { stack: error.stack }),
+                        })),
+                        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;
@@ -162,6 +211,10 @@ function wrapBrowser(browser) {
                 addCookies: (cookies) => context.addCookies(cookies),
                 grantPermissions: (permissions, opts) => context.grantPermissions(permissions, opts),
                 clearPermissions: () => context.clearPermissions(),
+                // On the context, so a page route that falls back still reaches it. See csp-widen.ts.
+                widenCsp: async (origin, onWidened) => {
+                    await context.route(ANY_URL, (route) => widenDocumentCsp(route, origin, onWidened));
+                },
                 close: () => context.close(),
             };
         },
@@ -203,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;
 }
@@ -233,7 +288,7 @@ 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 launchChromium(chromium, headless));
+            const browser = wrapBrowser(await launchChromium(chromium, headless), headless);
             settle();
             return browser;
         }
@@ -254,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?: {
@@ -21,6 +29,14 @@ export interface PooledPage {
      * "the page said nothing", never as "the page dialled correctly".
      */
     onConsole?(handler: (text: string) => void): void;
+    /**
+     * Fires for each error the page threw with no handler for it — an import-time module throw
+     * included. OPTIONAL like `onConsole`: a fake without it makes the pool hear nothing, which
+     * degrades to the old behaviour instead of inventing an error nobody reported. The handler must
+     * be installed BEFORE the first navigation — an import-time throw lands during `goto`, and a
+     * listener attached after it reads a broken page as healthy (#1966).
+     */
+    onPageError?(handler: (error: PooledPageError) => void): void;
     /**
      * Capture the page as a PNG, or a JPEG at `jpegQuality` (a live picture, where size matters more). OPTIONAL, like `onConsole`: a fake that does not implement it makes
      * the pool report "no provider", which is the correct degradation — an absent screenshotter must
@@ -39,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. */
@@ -84,13 +105,28 @@ 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>;
 }
+/**
+ * One uncaught error the page threw, as the engine reported it. The message is the exception text
+ * without the console's `Uncaught ` prefix; the stack is present when the engine had one.
+ */
+export interface PooledPageError {
+    readonly message: string;
+    readonly stack?: string;
+}
 export interface InitScriptHandle {
     dispose(): Promise<void>;
 }
@@ -117,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 {
@@ -133,13 +171,23 @@ export interface PooledContext {
     }): Promise<void>;
     /** Drop every permission granted on this context. OPTIONAL, for the same reason. */
     clearPermissions?(): Promise<void>;
+    /**
+     * Add `origin` to the `connect-src` of each top document's CSP, and call `onWidened` when that
+     * changed a response (see `csp-widen.ts`). OPTIONAL: without it a deployed page with a strict CSP
+     * blocks the reader, and the lease says `sdk_never_dialled`, which is true.
+     */
+    widenCsp?(origin: string, onWidened: () => void): Promise<void>;
 }
 /** 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 } 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;
@@ -46,8 +76,32 @@ export interface BrowserPoolOptions {
     /**
      * 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.
+     * Called with the lease url, because a page off loopback gets its own nonce, not the token.
+     */
+    zeroInstallScript?: (url: string) => string | undefined;
+    /**
+     * The WebSocket origin the reader dials (`ws://localhost:<port>`). A lease on a page that is not
+     * on loopback adds it to the page's CSP `connect-src` (#2016). Absent: no page CSP is changed.
      */
-    zeroInstallScript?: () => string | undefined;
+    daemonOrigin?: string;
+    /**
+     * Sink for uncaught page errors — an import-time throw the SDK was never installed in time to
+     * see (#1966). Called with the lease id, so the wiring can reach the session that connects for
+     * this lease later. Optional: without it the pool hears errors and drops them, which is the
+     * behaviour the repo had before the sink existed.
+     */
+    onPageError?: (leaseId: string, error: PooledPageError) => void;
+    /**
+     * Sink for lease release — manual release, the reaper, and a crash reclaim all funnel through
+     * it. Lets the wiring drop state it kept FOR that lease (the page-error buffer) instead of
+     * 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.
@@ -106,6 +160,8 @@ export interface ActiveLease {
      * context for "why did the page look frozen for a moment", not a log an agent needs to replay.
      */
     lastDialogMessage?: string;
+    /** Why the last screenshot of this lease failed, if it did. Cleared by the next one that works. */
+    captureError?: 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
@@ -123,6 +179,18 @@ export interface ActiveLease {
     permissions: readonly string[];
     /** Whether its context accepts any TLS certificate (#1255). Fixed when the context is made. */
     ignoresHTTPSErrors: boolean;
+    /** `widenedFor`: the origin added to this page's CSP `connect-src`, once one was (#2016). */
+    csp: {
+        widenedFor?: string;
+    };
 }
 /** 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>;
+/**
+ * The HTTP status a navigation ended on, or undefined when the page shape reports none.
+ *
+ * Real Playwright answers `goto` with a response object exposing `status()`; the fakes hand back
+ * whatever they like. A status accessor that THROWS says nothing usable, so it reads as absent
+ * rather than breaking the lease that is otherwise fine.
+ */
+export declare function navStatusOf(navRes: unknown): number | undefined;

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

@@ -47,3 +47,26 @@ export async function pageLoading(page) {
     const state = await page.evaluate('document.readyState');
     return 'string' === typeof state && state !== 'complete';
 }
+/**
+ * The HTTP status a navigation ended on, or undefined when the page shape reports none.
+ *
+ * Real Playwright answers `goto` with a response object exposing `status()`; the fakes hand back
+ * whatever they like. A status accessor that THROWS says nothing usable, so it reads as absent
+ * rather than breaking the lease that is otherwise fine.
+ */
+export function navStatusOf(navRes) {
+    if (null === navRes || 'object' !== typeof navRes || !('status' in navRes)) {
+        return undefined;
+    }
+    const s = navRes.status;
+    if ('function' === typeof s) {
+        try {
+            const code = s.call(navRes);
+            return 'number' === typeof code ? code : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return 'number' === typeof s ? s : undefined;
+}

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,8 +35,84 @@ 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)};`;
+/*
+ * Keep what the page says before the SDK's observers exist, and hand it to them after `connect()`.
+ *
+ * The observers install in `connect()`, which waits for DOMContentLoaded (below). The app's start-up
+ * scripts run before that, so a console error or an uncaught error while the page loaded was not
+ * seen, and a page that crashed at start-up gave a clean capture. Only the reader does this: it is
+ * installed before the page's scripts, and an app's own SDK connects from inside them.
+ *
+ * Kept in the order the page said it: `console.error` calls, uncaught script errors and unhandled
+ * rejections. After `connect()`, each console error is said again through the patched console with
+ * the native print off, so the console shows it once. Each error event is dispatched again on
+ * `window`, where the SDK listens. The app's own error listeners see a replayed error a second time.
+ * A resource that failed to load is not kept: the network observer reads it from resource timing.
+ */
+const EARLY_KEEP = 'if ("function" === typeof globalThis.addEventListener && globalThis.console !== undefined) {\n' +
+    'const early = { said: [], replaying: false };\n' +
+    'globalThis.__reticleEarly = early;\n' +
+    'const nativeError = globalThis.console.error;\n' +
+    'globalThis.console.error = function (...args) {\n' +
+    '  if (early.said !== null) early.said.push(args);\n' +
+    '  if (!early.replaying) return nativeError.apply(this, args);\n' +
+    '};\n' +
+    'early.keep = (e) => { if (early.said !== null && (e.type !== "error" || e instanceof globalThis.ErrorEvent)) early.said.push(e); };\n' +
+    'globalThis.addEventListener("error", early.keep, true);\n' +
+    'globalThis.addEventListener("unhandledrejection", early.keep);\n' +
+    '}';
+const EARLY_REPLAY = 'const early = globalThis.__reticleEarly;\n' +
+    'if (early !== undefined) {\n' +
+    '  globalThis.__reticleEarly = undefined;\n' +
+    '  globalThis.removeEventListener("error", early.keep, true);\n' +
+    '  globalThis.removeEventListener("unhandledrejection", early.keep);\n' +
+    '  const said = early.said;\n' +
+    '  early.said = null;\n' +
+    '  for (const item of said) {\n' +
+    '    if (Array.isArray(item)) {\n' +
+    '      early.replaying = true;\n' +
+    '      try { globalThis.console.error(...item); } finally { early.replaying = false; }\n' +
+    '    } else if ("error" === item.type) {\n' +
+    '      globalThis.dispatchEvent(new globalThis.ErrorEvent("error", { message: item.message, filename: item.filename, lineno: item.lineno, colno: item.colno, error: item.error }));\n' +
+    '    } else {\n' +
+    '      globalThis.dispatchEvent(new globalThis.PromiseRejectionEvent("unhandledrejection", { promise: item.promise, reason: item.reason }));\n' +
+    '    }\n' +
+    '  }\n' +
+    '}';
+/*
+ * Connect once the DOM exists. The reader also runs as an init script on every later document of the
+ * lease, before the parser makes <head> and <body>. `connect()` mounts page UI before it dials the
+ * bridge, so it threw there and never dialled: every full navigation after the first page lost the
+ * lease's session (#1897). The bundle still loads at once, so the observers start early.
+ */
+const CONNECT_WHEN_DOM_READY = (args) => `const connect = () => { globalThis.__reticleInstance.connect(${args}); ${EARLY_REPLAY} };\n` +
+    `if (globalThis.document !== undefined && 'loading' === globalThis.document.readyState) ` +
+    `globalThis.document.addEventListener('DOMContentLoaded', connect, { once: true });\n` +
+    `else connect();`;
+/** Where every zod copy in a page keeps its shared settings (`z.config`). */
+const ZOD_CONFIG = 'globalThis.__zod_globalConfig';
+/*
+ * Turn zod `jitless` on for the page, unless the page set it itself.
+ *
+ * The reader is evaluated over CDP, where `new Function` works even on a page whose CSP forbids
+ * `unsafe-eval`. Zod's eval probe then answered true and cached it, and later parses compiled a fast
+ * path with `new Function` in the page: CSP threw, and the session stopped answering (#2016,
+ * nextjs.org). Zod reads `jitless` when a schema is made, and the SDK makes some schemas later, also
+ * inside a CDP evaluate. So the setting stays on.
+ * ponytail: the page's own zod then parses without its compiled fast path. Results are the same;
+ * only parse speed changes. Scope it to the bundle's own zod copy if that speed is ever seen.
+ */
+const ZOD_JITLESS = `(${ZOD_CONFIG} ??= {}).jitless ??= true;`;
 /**
  * The script for a page: install the SDK if the page has none, then connect it to this daemon.
  *
@@ -47,7 +123,7 @@ const NOT_HTML_GUARD = `if (globalThis.document !== undefined && !${JSON.stringi
  */
 export function zeroInstallScript(bundle, opts) {
     const args = JSON.stringify(injectedConnectArgs(opts));
-    return `(() => {\n${NOT_HTML_GUARD}\nif (!globalThis.__reticleInstance) {\n${bundle}\n}\nglobalThis.__reticleInstance.connect(${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 {
@@ -56,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

@@ -19,6 +19,15 @@ export interface DevCommand {
     /** The app's directory, when it is not the project root. The caller must run the command there. */
     directory?: string;
 }
+/**
+ * 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. `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[], 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.
  *
@@ -35,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.
@@ -44,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;