@reticlehq/server 2.11.0 → 2.13.0

package/dist/init/snippets.js

@@ -2,7 +2,7 @@
  * Generated file contents and copy-paste snippets for `reticle init`. Kept as named constants/builders
  * so the runner never inlines free strings.
  */
-import { RETICLE_DEFAULT_PORT, ReticleDir, bridgeWsUrl } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, ReticleDir, bridgeWsUrl, RETICLE_CLIENT_HOST, RETICLE_WS_PATH, } from '@reticlehq/core';
 import { UiLibrary } from './detect.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 /**
@@ -17,9 +17,9 @@ import { SERVER_VERSION } from '../version/server-version.js';
  *
  * jsDelivr rather than esm.sh, measured: a third of the requests and a third of the bytes for the
  * same result. `/+esm` is what makes it work, and the bare package URL does NOT: every file in
- * `dist` carries bare specifiers for `@reticlehq/core` and `@testing-library/dom`, so an unbundled
- * entry point dies on the first import. That is also why adding `unpkg`/`jsdelivr` fields to
- * package.json would not help.
+ * `dist` still carries bare workspace specifiers such as `@reticlehq/core`, so an unbundled entry
+ * point dies on the first import. That is also why adding `unpkg`/`jsdelivr` fields to package.json
+ * would not help.
  *
  * PINNED to this server's version on purpose. A floating import upgrades the page SDK underneath a
  * daemon that did not move, which is `version_skew` arriving by a route nothing checks.
@@ -132,38 +132,51 @@ export function nextReticleDevFile(port, projectId, testids = [], stores = [], f
     // Same rule as the Vite module: a store we found is registered outright, and the commented hint
     // survives only for the libraries we can name but not wire.
     const storeImports = found.map((s) => `import { ${s.ident} } from '${s.importPath}';`).join('\n');
+    // Eight spaces: nested inside useEffect → .then callback (see multiline shape below for #684).
     const storeBlock = found.length > 0
-        ? found.map((s) => `      registerStore('${s.key}', ${s.ident});`).join('\n')
+        ? found.map((s) => `        registerStore('${s.key}', ${s.ident});`).join('\n')
         : 0 === stores.length
-            ? '      // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
-            : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
+            ? '        // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
+            : stores.map((h) => `        // import your store, then: ${h}`).join('\n');
+    const registerNames = found.length > 0 ? ', registerStore' : '';
+    // Multiline connect + single blank after imports (#684): the one-line connect and the double blank
+    // both fail Prettier on a clean Next install.
     return `'use client';
 import { useEffect } from 'react';
-${storeImports.length > 0 ? storeImports : ''}
-
+${storeImports.length > 0 ? `${storeImports}\n` : ''}
 /** Dev-only: connect Reticle + install the React adapter, after hydration. */
 export function ReticleDev() {
   useEffect(() => {
     if (process.env.NODE_ENV !== 'development') return;
-    void import('@reticlehq/react').then(({ reticle, install, registerCapabilities${found.length > 0 ? ', registerStore' : ''} }) => {
-      install();
-      // Both provided by withReticle() in next.config. The bridge rejects a connect with no token;
-      // the root makes source paths repo-relative instead of absolute.
-      const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
-      const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
-      reticle.connect({ ${fields}...(token ? { token } : {}), ...(root ? { root } : {}) });
+    void import('@reticlehq/react').then(
+      ({ reticle, install, registerCapabilities${registerNames} }) => {
+        install();
+        // Both provided by withReticle() in next.config. The bridge rejects a connect with no token;
+        // the root makes source paths repo-relative instead of absolute.
+        const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
+        const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
+        // withReticle() finds the daemon serving this project on every dev-server start. It wins over
+        // any port written into this file at install time, so moving the daemon needs no edit here.
+        const url = process.env.NEXT_PUBLIC_RETICLE_URL;
+        reticle.connect({
+          ${fields}...(url ? { url } : {}),
+          ...(token ? { token } : {}),
+          ...(root ? { root } : {}),
+        });
 
-      // ── Start with ONE flow. ──────────────────────────────────────────────────────────────────
-      // Registering a store is the highest-value line here: it lets the agent check what the app
-      // BELIEVES, not just what it rendered. Pass the STORE, not \`() => store.getState()\` — the store
-      // form wires \`subscribe\` too, so every mutation emits a diff; the getter form is read-only.
+        // ── Start with ONE flow. ────────────────────────────────────────────────────────────────
+        // Registering a store is the highest-value line here: it lets the agent check what the app
+        // BELIEVES, not just what it rendered. Pass the STORE, not \`() => store.getState()\` — the
+        // store form wires \`subscribe\` too, so every mutation emits a diff; the getter form is
+        // read-only.
 ${storeBlock}
-      registerCapabilities({
-        testids: [${ids}],${0 === testids.length ? ' // none found; add data-testid to your key elements' : ''}
-        signals: [], // names you pass to reticle.signal()
-        stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
-      });
-    });
+        registerCapabilities({
+          testids: [${ids}],${0 === testids.length ? ' // none found; add data-testid to your key elements' : ''}
+          signals: [], // names you pass to reticle.signal()
+          stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
+        });
+      },
+    );
   }, []);
   return null;
 }
@@ -204,11 +217,51 @@ layoutPath) {
         ? `\n          url: '${bridgeWsUrl(port)}',`
         : '';
     const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
+    // Astro owns its Vite instance, so it has a build-time channel of its own: the same `define` that
+    // already inlines the token can inline the daemon URL, resolved every time the config is read —
+    // that is, on every `astro dev`. The port above is written once at install time and goes stale the
+    // moment the daemon moves; this does not.
+    //
+    // Needs the projectId to know WHICH daemon is ours. Without one there is nothing to match on, and
+    // adopting a daemon serving another project would report its state as this app's, so the whole
+    // block is omitted rather than made to guess.
+    const canDiscover = projectId !== undefined && projectId.length > 0;
+    // Interpolated from core rather than typed into the template: this is the same wire string
+    // `bridgeWsUrl` builds, and a generator that spells it out by hand is exactly how the four call
+    // sites that constant exists to unify drifted apart in the first place.
+    const RETICLE_CLIENT_HOST_LITERAL = `ws://${RETICLE_CLIENT_HOST}:`;
+    const urlHelper = canDiscover
+        ? `
+  // The live daemon serving THIS project, re-read on every \`astro dev\`. Same rule as the Vite and
+  // Next plugins: skip dead daemons, match on projectId, lowest port wins, '' when none matches.
+  function reticleUrl() {
+    const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+    let best;
+    try {
+      for (const file of readdirSync(dir)) {
+        if (!file.startsWith('daemon-') || !file.endsWith('.json')) continue;
+        let entry;
+        try { entry = JSON.parse(readFileSync(join(dir, file), 'utf8')); } catch { continue; }
+        if (entry.projectId !== '${projectId}') continue;
+        try { process.kill(entry.pid, 0); } catch { continue; }
+        if (best === undefined || entry.port < best) best = entry.port;
+      }
+    } catch { return ''; }
+    return best === undefined ? '' : '${RETICLE_CLIENT_HOST_LITERAL}' + best + '${RETICLE_WS_PATH}';
+  }
+`
+        : '';
+    const urlDefine = canDiscover ? `\n        __RETICLE_URL__: JSON.stringify(reticleUrl()),` : '';
+    const urlRead = canDiscover
+        ? `\n      const url = typeof __RETICLE_URL__ !== 'undefined' ? __RETICLE_URL__ : '';`
+        : '';
+    // After the baked port, so the discovered one wins: later key in an object literal.
+    const urlSpread = canDiscover ? `\n          ...(url.length > 0 ? { url } : {}),` : '';
     return `Astro renders its own HTML, so the connect goes in a page <script> and the pairing token is inlined by the config.
 
 1. In astro.config.mjs — inline the daemon's token and raise the build target:
 
-  import { readFileSync } from 'node:fs';
+  import { readFileSync, readdirSync } from 'node:fs';
   import { homedir } from 'node:os';
   import { join } from 'node:path';
 
@@ -216,14 +269,14 @@ layoutPath) {
     const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
     try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
   }
-
+${urlHelper}
   export default defineConfig({
     vite: {
       // Astro's default target down-levels the modern SDK bundle and fails on a destructuring transform.
       build: { target: 'es2022' },
       optimizeDeps: { esbuildOptions: { target: 'es2022' } },
       define: {
-        __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
+        __RETICLE_TOKEN__: JSON.stringify(reticleToken()),${urlDefine}
         // Without this, source pointers come back as absolute paths from YOUR machine — useless in a
         // report. Every other framework gets it from its build plugin; Astro owns its Vite instance.
         __RETICLE_ROOT__: JSON.stringify(process.cwd()),
@@ -236,16 +289,22 @@ ${layoutHost(layoutPath)}
   <script>
     if (import.meta.env.DEV) {
       const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-      const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+      const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';${urlRead}
       const { reticle, install } = await import('@reticlehq/react');
       install();
-      reticle.connect({${id}${extra}
+      reticle.connect({${id}${extra}${urlSpread}
           ...(token.length > 0 ? { token } : {}),
           ...(root.length > 0 ? { root } : {}),
       });
     }
   </script>
 
+3. In src/env.d.ts — declare the Vite define names so \`astro check\` can see them (create-astro's
+   default build runs check first, and without this it fails with Cannot find name '__RETICLE_TOKEN__'):
+
+  declare const __RETICLE_TOKEN__: string | undefined;
+  declare const __RETICLE_ROOT__: string | undefined;
+
 Start the daemon BEFORE \`astro dev\`, so the token file exists when the config is read. Until it does the token is empty and the page reloads once the daemon is up.`;
 }
 /**

package/dist/init/vite-config.d.ts

@@ -14,5 +14,5 @@ export declare const VitePatchKind: {
 };
 export type VitePatchKind = PatchKind;
 type VitePatch = SourcePatch;
-export declare function patchViteConfig(source: string, port?: number): VitePatch;
+export declare function patchViteConfig(source: string, port?: number, captureBodies?: boolean): VitePatch;
 export {};

package/dist/init/vite-config.js

@@ -8,30 +8,38 @@ import { PatchKind } from './patch-kind.js';
 export const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
 const RETICLE_MARKER = '@reticlehq/vite-plugin';
 /**
- * The `reticle(...)` call — the bridge port so the injected connect targets it, and body capture.
+ * The `reticle(...)` call — the bridge port so the injected connect targets it.
  *
- * `captureNetworkBodies` is here rather than in the SDK's defaults, deliberately. Without it a write
- * that answers 2xx with a body nobody recorded grades `unknown / outcome_unread`, because a 200
- * describes the transport and not the result — so the single bug class this product exists to catch is
- * unreachable on a default install. Measured on a real payments UI: a refund posted rupees into a
- * paise field, the server answered 200 having refunded a hundredth of it, the page rendered the amount
- * the user had typed rather than the amount that came back, and every DOM-level check passed. An agent
- * asked to verify that flow had to edit the app's own vite config mid-task to see the payload, and
- * then tell its human to undo the edit.
+ * **`captureNetworkBodies` is OPT-IN.** It was written in by default, and the argument for that was
+ * a good one: without a body, a write that answers 2xx grades `unknown / outcome_unread`, because a
+ * 200 describes the transport and not the result. Measured on a real payments UI — a refund posted
+ * rupees into a paise field, the server answered 200 having refunded a hundredth of it, the page
+ * rendered the amount the user had typed, and every DOM-level check passed.
  *
- * Written into the USER'S config, not switched on inside the SDK, and the difference is the point. A
- * body is the one part of a request that routinely carries personal data: the credential classes are
- * redacted before anything is journalled — tokens, cookies, card numbers, cvv, ssn — but an address or
- * an email is not, and nothing here should decide that for someone silently. In the config it is one
- * visible line they can read, keep, or delete, and an SDK that updates underneath them never starts
- * recording more than it did yesterday.
+ * That argument justifies the CAPABILITY. It does not justify the default, and the distinction is
+ * what #705 is about. A healthcare workspace proxying authenticated API traffic through Vite ran
+ * `init`, and on the first drive their login tokens and patient payloads were in the daemon's
+ * buffer. The old comment here conceded the exact gap — "the credential classes are redacted ... but
+ * an address or an email is not, and nothing here should decide that for someone silently" — and
+ * then decided it for them, because writing the line into their config IS deciding. `init` is run
+ * unattended by an agent; the person who knows the data is sensitive is not in the room.
+ *
+ * So the default is off and the ways in are all deliberate:
+ *   - `reticle init --capture-bodies` writes the line, for someone who has decided
+ *   - `VITE_RETICLE_CAPTURE_BODIES=1` turns it on for ONE dev-server run, no config edit
+ *   - adding the option by hand, which is what the tools tell you to do
+ *
+ * Nothing goes quiet in exchange. Every tool that needs a body already says so when it is missing
+ * and names the option — see honesty/uncaptured-bodies.ts, honesty/verified.ts, predicate-eval.ts
+ * and reconcile-tools.ts — so the capability is discovered at the moment it is wanted, by the person
+ * who wanted it, instead of being switched on before anyone has asked.
  */
-function reticlePluginCall(port) {
+function reticlePluginCall(port, captureBodies) {
     const options = [
         ...(port === undefined ? [] : [`port: ${String(port)}`]),
-        'captureNetworkBodies: true',
+        ...(captureBodies ? ['captureNetworkBodies: true'] : []),
     ];
-    return `reticle({ ${options.join(', ')} })`;
+    return 0 === options.length ? 'reticle()' : `reticle({ ${options.join(', ')} })`;
 }
 /** Matches the start of a `plugins: [` array literal. */
 const PLUGINS_ARRAY = /plugins\s*:\s*\[/;
@@ -66,35 +74,41 @@ function insertImport(source) {
  * what a formatter rewrites, turning a one-line install into a diff against the user's own style. A
  * single-line array needs the space, or the result reads `[reticle(),react()]`.
  */
-function insertPlugin(source, port) {
+function insertPlugin(source, port, captureBodies) {
     return source.replace(PLUGINS_ARRAY, (match, _g, offset) => {
         const next = source[offset + match.length] ?? '';
         const separator = '' === next || /\s/.test(next) ? '' : ' ';
-        return `${match}${reticlePluginCall(port)},${separator}`;
+        return `${match}${reticlePluginCall(port, captureBodies)},${separator}`;
     });
 }
 /**
  * Add a whole `plugins: [reticle()]` key to a config object that has none, matching the layout of
  * the object it lands in: a multi-line object gets its own indented line, a one-liner stays inline.
  */
-function insertPluginsKey(source, port) {
+function insertPluginsKey(source, port, captureBodies) {
     return source.replace(CONFIG_OBJECT, (_match, prefix, offset) => {
         const rest = source.slice(offset + _match.length);
         const multiline = /^\s*\n/.test(rest);
         const indent = /^\s*\n(\s*)\S/.exec(rest)?.[1] ?? '  ';
-        const key = `plugins: [${reticlePluginCall(port)}],`;
+        const key = `plugins: [${reticlePluginCall(port, captureBodies)}],`;
         return multiline ? `${prefix}{\n${indent}${key}` : `${prefix}{ ${key}`;
     });
 }
-export function patchViteConfig(source, port) {
+export function patchViteConfig(source, port, captureBodies = false) {
     if (source.includes(RETICLE_MARKER)) {
         return { kind: VitePatchKind.ALREADY };
     }
     if (PLUGINS_ARRAY.test(source)) {
-        return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
+        return {
+            kind: VitePatchKind.APPLY,
+            code: insertImport(insertPlugin(source, port, captureBodies)),
+        };
     }
     if (CONFIG_OBJECT.test(source)) {
-        return { kind: VitePatchKind.APPLY, code: insertImport(insertPluginsKey(source, port)) };
+        return {
+            kind: VitePatchKind.APPLY,
+            code: insertImport(insertPluginsKey(source, port, captureBodies)),
+        };
     }
     return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
 }

package/dist/init/workspace-apps.d.ts

@@ -1,16 +1,14 @@
+import type { InitIo } from './run.js';
 /**
- * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
+ * The file names that say what a directory IS, shared by everything that has to ask.
  *
- * This used to be the literal list `['apps', 'packages']`. Measured on a real repo with three Next
- * apps at `web/`, `admin/` and `space/`, it found none — so the redirect never fired, init ran
- * against the root, and it reported ✓ for writing `app/reticle-dev.tsx` into a directory Next never
- * compiles. A ⚠ tells a human to act; a ✓ tells them it is handled.
- *
- * A workspace DECLARES its packages, so that declaration is used first and directory names are not
- * guessed at all. Where nothing is declared, every top-level directory is a better candidate than two
- * hardcoded ones — filtered by the usual non-source suspects, and still subject to the `looksLikeApp`
- * check that follows, so a wrong guess here costs a `package.json` read.
+ * They lived in run.ts and are read from here now because `findWorkspaceApps` moved and needs them —
+ * one definition, imported in both directions of the question ("is this an app?" and "which app?").
  */
+export declare const PACKAGE_JSON = "package.json";
+export declare const PNPM_WORKSPACE = "pnpm-workspace.yaml";
+export declare const VITE_CONFIG_CANDIDATES: string[];
+export declare const NEXT_CONFIG_CANDIDATES: string[];
 interface WorkspaceSources {
     /** Raw contents of pnpm-workspace.yaml, when present. */
     pnpmWorkspace?: string;
@@ -20,4 +18,13 @@ interface WorkspaceSources {
     topLevelDirs?: readonly string[];
 }
 export declare function workspaceParents(sources: WorkspaceSources): string[];
+/**
+ * App directories under a workspace root.
+ *
+ * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
+ * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
+ * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
+ * it knows it is in a workspace; this is the matching walk DOWN.
+ */
+export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
 export {};

package/dist/init/workspace-apps.js

@@ -1,3 +1,24 @@
+import { DEV_SCRIPT_NAMES } from './dev-script.js';
+/**
+ * The file names that say what a directory IS, shared by everything that has to ask.
+ *
+ * They lived in run.ts and are read from here now because `findWorkspaceApps` moved and needs them —
+ * one definition, imported in both directions of the question ("is this an app?" and "which app?").
+ */
+export const PACKAGE_JSON = 'package.json';
+export const PNPM_WORKSPACE = 'pnpm-workspace.yaml';
+export const VITE_CONFIG_CANDIDATES = [
+    'vite.config.ts',
+    'vite.config.js',
+    'vite.config.mjs',
+    'vite.config.mts',
+];
+export const NEXT_CONFIG_CANDIDATES = [
+    'next.config.mjs',
+    'next.config.js',
+    'next.config.ts',
+    'next.config.cjs',
+];
 /**
  * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
  *
@@ -66,3 +87,92 @@ export function workspaceParents(sources) {
         : (sources.topLevelDirs ?? []).filter((d) => !d.startsWith('.') && !NEVER_A_PACKAGE.has(d));
     return [...new Set(candidates)];
 }
+/**
+ * Which directories under this workspace are runnable apps.
+ *
+ * Moved here from run.ts, which was over the 1000-line cap and had carried a note saying it was at
+ * its cohesion limit. `library-path-boundary.test.ts` had already written down that this function
+ * "squats in init/ for historical reasons" — it is a general-purpose question about a repository's
+ * shape, next to `workspaceParents`, which answers the other half of it.
+ */
+/** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
+const APP_DEPS = ['next', 'vite'];
+function hasDevScript(pkgRaw) {
+    try {
+        const parsed = JSON.parse(pkgRaw);
+        const scripts = 'object' === typeof parsed && parsed !== null
+            ? parsed.scripts
+            : undefined;
+        if ('object' !== typeof scripts || null === scripts)
+            return false;
+        const named = scripts;
+        return DEV_SCRIPT_NAMES.some((n) => 'string' === typeof named[n] && '' !== named[n]);
+    }
+    catch {
+        // A manifest that will not parse says nothing either way, and this is a filter, not a verdict.
+        return false;
+    }
+}
+function looksLikeApp(dir, io) {
+    const pkgRaw = io.readFile(`${dir}/${PACKAGE_JSON}`);
+    if (null === pkgRaw)
+        return false;
+    const configs = [...VITE_CONFIG_CANDIDATES, ...NEXT_CONFIG_CANDIDATES];
+    if (configs.some((c) => io.exists(`${dir}/${c}`)))
+        return true;
+    // `next.config` is optional in Next, so the dependency list is the other half of the signal.
+    if (APP_DEPS.some((d) => pkgRaw.includes(`"${d}"`)))
+        return true;
+    // And the honest third: an app somebody can SERVE. Asking only for a bundler missed every app
+    // built on anything else — Remix, Astro, a plain node server — and in a monorepo missing it means
+    // init never redirects, wires the ROOT, and reports ✓ for files nothing compiles.
+    //
+    // A monorepo root has no dev script by design, and a package that can only be BUILT is not the app
+    // somebody is working in, so this stays a filter rather than matching every directory.
+    return hasDevScript(pkgRaw);
+}
+/**
+ * App directories under a workspace root.
+ *
+ * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
+ * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
+ * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
+ * it knows it is in a workspace; this is the matching walk DOWN.
+ */
+export function findWorkspaceApps(io) {
+    const found = [];
+    // A workspace DECLARES its packages; `['apps','packages']` was a guess that missed a real repo
+    // with three Next apps at web/, admin/ and space/ — and missing them meant init ran against the
+    // root and reported ✓ for a file Next never compiles. See workspace-apps.
+    const pkgRaw = io.readFile(PACKAGE_JSON);
+    let pkgWorkspaces;
+    try {
+        const parsed = null === pkgRaw ? undefined : JSON.parse(pkgRaw);
+        pkgWorkspaces =
+            'object' === typeof parsed && parsed !== null
+                ? parsed.workspaces
+                : undefined;
+    }
+    catch {
+        pkgWorkspaces = undefined;
+    }
+    const parents = workspaceParents({
+        ...(null === io.readFile(PNPM_WORKSPACE)
+            ? {}
+            : { pnpmWorkspace: io.readFile(PNPM_WORKSPACE) ?? '' }),
+        ...(pkgWorkspaces === undefined ? {} : { pkgWorkspaces }),
+        topLevelDirs: io.listDirs('.'),
+    });
+    // A declared parent can itself BE the app (`workspaces: ["web"]`), so check both the directory and
+    // its children rather than assuming one level of nesting.
+    for (const parent of parents) {
+        if (looksLikeApp(parent, io))
+            found.push(parent);
+        for (const name of io.listDirs(parent)) {
+            const dir = `${parent}/${name}`;
+            if (looksLikeApp(dir, io))
+                found.push(dir);
+        }
+    }
+    return [...new Set(found)];
+}

package/dist/input/network-mock-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
+import { delayMsSchema, httpStatusSchema } from '../tools/numeric-bounds.js';
 import { asString } from '../tools/tools-helpers.js';
 function mockProvider(deps) {
     const p = deps.realInput;
@@ -13,14 +14,10 @@ const ruleShape = z.object({
         .min(1)
         .describe('Substring the request URL must contain, e.g. "/api/pay".'),
     method: z.string().optional().describe('Optional method filter (GET/POST/…), case-insensitive.'),
-    status: z.number().int().optional().describe('Fulfill with this HTTP status (default 200).'),
+    status: httpStatusSchema.optional().describe('Fulfill with this HTTP status (default 200).'),
     body: z.string().optional().describe('Response body to fulfill with.'),
     contentType: z.string().optional().describe('Response content type (default application/json).'),
-    delayMs: z
-        .number()
-        .int()
-        .optional()
-        .describe('Delay (ms) before fulfilling — simulate a slow API.'),
+    delayMs: delayMsSchema.optional().describe('Delay (ms) before fulfilling — simulate a slow API.'),
     abort: z
         .boolean()
         .optional()

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

@@ -171,6 +171,8 @@ export interface LaunchedProviderOptions {
      */
     onNetworkDetail?: (detail: NetworkDetail) => void;
 }
+/** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
+export declare const launchedChromium: LaunchFn;
 /**
  * Launches and OWNS a Playwright Chromium, navigates it to `driveUrl`, then drives native
  * input on that page. Headless-capable so @reticlehq/test / CI can run hover/drag unattended.

package/dist/input/real-input.js

@@ -1,3 +1,4 @@
+import { chromiumLaunchOptions } from '../chromium-launch-options.js';
 import { gotoOptions } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
@@ -220,7 +221,7 @@ export class CdpRealInputProvider {
 }
 const INJECT_CONNECT_WAIT_MS = 8_000;
 /** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
-const launchedChromium = async (headless) => {
+export const launchedChromium = async (headless) => {
     let mod;
     try {
         mod = await import('playwright');
@@ -230,7 +231,7 @@ const launchedChromium = async (headless) => {
     }
     const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.LAUNCHED);
     try {
-        const browser = await mod.chromium.launch({ headless });
+        const browser = await mod.chromium.launch(chromiumLaunchOptions(headless));
         settle();
         return browser;
     }
@@ -301,8 +302,28 @@ export class LaunchedRealInputProvider {
             // No SDK on the page (or it connected already) — the no-session guard in verify reports it.
         }
     }
-    isAvailableFor(sessionUrl) {
+    /**
+     * The page we own, or undefined once it is gone.
+     *
+     * The handle is cached for the life of the provider and Playwright keeps answering `url()` after
+     * the page has closed, so a closed window read as AVAILABLE and every method below threw
+     * "Target page, context or browser has been closed" — the raw Playwright message, surfaced to the
+     * agent as a tool error, on every call for the rest of the run. A dead page is the same fact as no
+     * page, and every caller already handles that. Only an EXPLICIT `true` drops it, matching
+     * `CdpRealInputProvider`'s `isConnected` check: a test fake without the method is assumed live.
+     */
+    #livePage() {
         const page = this.#page;
+        if (page === undefined)
+            return undefined;
+        if (true === page.isClosed?.()) {
+            this.#page = undefined; // never ask a corpse twice
+            return undefined;
+        }
+        return page;
+    }
+    isAvailableFor(sessionUrl) {
+        const page = this.#livePage();
         if (page === undefined)
             return Promise.resolve(false);
         if (page.url() === sessionUrl)
@@ -310,14 +331,14 @@ export class LaunchedRealInputProvider {
         return Promise.resolve(stripVolatile(page.url()) === stripVolatile(sessionUrl));
     }
     perform(_sessionUrl, action, box, args) {
-        const page = this.#page;
+        const page = this.#livePage();
         if (page === undefined)
             return Promise.resolve({ performed: false, center: boxCenter(box) });
         return performGesture(page, action, box, args, this.#sleep);
     }
     /** PNG of the owned page, or undefined before navigate / after dispose. */
     screenshot(_sessionUrl, opts) {
-        const page = this.#page;
+        const page = this.#livePage();
         if (page === undefined)
             return Promise.resolve(undefined);
         return capturePage(page, opts);
@@ -331,7 +352,7 @@ export class LaunchedRealInputProvider {
      * screenshots the whole time; only these two methods were missing.
      */
     async setViewport(_sessionUrl, size) {
-        const page = this.#page;
+        const page = this.#livePage();
         if (page === undefined)
             return false;
         await page.setViewportSize({ width: size.width, height: size.height });
@@ -339,7 +360,7 @@ export class LaunchedRealInputProvider {
     }
     /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
     async setMocks(_sessionUrl, rules) {
-        const page = this.#page;
+        const page = this.#livePage();
         if (page === undefined)
             return false;
         await installNetworkMocks(page, rules);

package/dist/input/scroll-find.d.ts

@@ -36,10 +36,13 @@ export interface ScrollFindResult {
     note?: string;
 }
 /**
- * Reveal an element that a windowed/virtualized list has not mounted yet. Queries
- * once (it may already be visible), then scrolls the container ~one viewport at a time, re-querying
- * after each, until the element appears, the list ends, or the maxScrolls budget is spent. Pure
- * orchestration over the session command seam — fully unit-testable with a fake.
+ * Reveal an element that a windowed/virtualized list has not mounted yet. Queries once (it may
+ * already be visible), optionally jumps straight to a bisection estimate, then walks the container
+ * a viewport at a time re-querying after each step. Downward first; when the bottom is reached the
+ * walk TURNS AROUND and continues upward, because a list that is already scrolled to its end keeps
+ * its earlier rows mounted above the viewport and a downward-only search answered "exhausted" on
+ * its first step (#505). `exhausted` therefore means BOTH directions are spent, not "the bottom is
+ * here". Pure orchestration over the session command seam — fully unit-testable with a fake.
  */
 export declare function scrollToFind(session: ScrollFindSession, q: ScrollFindQuery, opts?: {
     maxScrolls?: number;