@reticlehq/server 2.4.0 → 2.6.0

package/dist/init/snippets.d.ts

@@ -15,19 +15,16 @@ export declare function nextConfigManual(configFile: string): string;
  * setup ended at `bridge refused the connection: authentication failed` and no session ever appeared.
  */
 export declare function nextReticleDevFile(port: number | undefined, projectId?: string, testids?: readonly string[], stores?: readonly string[]): string;
+export declare function astroManual(port: number | undefined, projectId?: string, 
 /**
- * Astro connect instructions.
+ * A layout file that actually exists, when one does.
  *
- * Astro is Vite-based but SSRs its own HTML, so the plugin's index.html injection never fires, and
- * `vite` is not a direct dependency — so this used to fall through to the generic HTML advice, which
- * tells you to add a connect to an "entry module" Astro does not have, or to bundle the SDK with
- * esbuild. Both are wrong for Astro, and following either gets you nothing.
- *
- * Astro bundles a page `<script>`, so the bare import resolves there. The token has to be inlined by
- * the config because there is no plugin in the page's path to inject it, and `build.target` has to be
- * raised or Astro down-levels the modern SDK bundle and dies on a destructuring transform.
+ * Reported from the field: on `examples/framework-react` — which has no layout at all, only
+ * `src/pages/index.astro` — init printed thirty lines telling the user to paste into "your
+ * layout". Instructions that name a file the project does not have read as a mistake by the
+ * reader, and cost them the time it takes to go and confirm it is missing.
  */
-export declare function astroManual(port: number | undefined, projectId?: string): string;
+layoutPath?: string): string;
 /**
  * The app-side dev module the Vite plugin imports by convention.
  *

package/dist/init/snippets.js

@@ -47,9 +47,9 @@ export function nextConfigManual(configFile) {
  */
 export function nextReticleDevFile(port, projectId, testids = [], stores = []) {
     const base = connectArg(port, projectId);
-    const fields = base === '' ? '' : `${base.slice(1, -1).trim()}, `;
+    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     const ids = testids.map((t) => `'${t}'`).join(', ');
-    const storeBlock = stores.length === 0
+    const storeBlock = 0 === stores.length
         ? '      // No state library detected. If you add one, register it here — see docs/usage.md.'
         : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
     return `'use client';
@@ -73,7 +73,7 @@ export function ReticleDev() {
       // form wires \`subscribe\` too, so every mutation emits a diff; the getter form is read-only.
 ${storeBlock}
       registerCapabilities({
-        testids: [${ids}],${testids.length === 0 ? ' // none found — add data-testid to your key elements' : ''}
+        testids: [${ids}],${0 === testids.length ? ' // none found — add data-testid to your key elements' : ''}
         signals: [], // names you pass to reticle.signal()
         stores: [], // the keys you registered above
       });
@@ -95,8 +95,28 @@ ${storeBlock}
  * the config because there is no plugin in the page's path to inject it, and `build.target` has to be
  * raised or Astro down-levels the modern SDK bundle and dies on a destructuring transform.
  */
-export function astroManual(port, projectId) {
-    const extra = port !== undefined && port !== RETICLE_DEFAULT_PORT ? `\n          url: '${bridgeWsUrl(port)}',` : '';
+/**
+ * Name the file the connect <script> should go in — the layout when one exists, otherwise the page,
+ * because a project with no layout has nowhere else to put it and should not be told otherwise.
+ */
+function layoutHost(layoutPath) {
+    return layoutPath === undefined
+        ? '2. This project has no layout, so put it in the page you want instrumented (e.g.\n   src/pages/index.astro) — every page you want a session from needs it — inside <body>:'
+        : `2. In ${layoutPath} (or any other page you want instrumented), inside <body>:`;
+}
+export function astroManual(port, projectId, 
+/**
+ * A layout file that actually exists, when one does.
+ *
+ * Reported from the field: on `examples/framework-react` — which has no layout at all, only
+ * `src/pages/index.astro` — init printed thirty lines telling the user to paste into "your
+ * layout". Instructions that name a file the project does not have read as a mistake by the
+ * reader, and cost them the time it takes to go and confirm it is missing.
+ */
+layoutPath) {
+    const extra = port !== undefined && port !== RETICLE_DEFAULT_PORT
+        ? `\n          url: '${bridgeWsUrl(port)}',`
+        : '';
     const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
     return `Astro renders its own HTML, so the connect goes in a page <script> and the pairing token is inlined by the config.
 
@@ -125,7 +145,7 @@ export function astroManual(port, projectId) {
     },
   });
 
-2. In your layout (or the page you want instrumented), inside <body>:
+${layoutHost(layoutPath)}
 
   <script>
     if (import.meta.env.DEV) {
@@ -153,7 +173,7 @@ Start the daemon BEFORE \`astro dev\`, so the token file exists when the config
  */
 export function viteDevModuleFile(testids, stores) {
     const ids = testids.map((t) => `'${t}'`).join(', ');
-    const storeBlock = stores.length === 0
+    const storeBlock = 0 === stores.length
         ? '  // No state library detected. If you add one, register it here — see docs/usage.md.'
         : stores.map((h) => `  // import your store, then: ${h}`).join('\n');
     return `// Dev-only. Imported automatically by @reticlehq/vite-plugin — you do not need to import it.
@@ -173,7 +193,7 @@ if (import.meta.env.DEV) {
 ${storeBlock}
 
   registerCapabilities({
-    testids: [${ids}],${testids.length === 0 ? ' // none found — add data-testid to your key elements' : ''}
+    testids: [${ids}],${0 === testids.length ? ' // none found — add data-testid to your key elements' : ''}
     signals: [], // names you pass to reticle.signal()
     stores: [], // the keys you registered above
   });
@@ -203,10 +223,11 @@ export function htmlManual(port, projectId) {
   • Bundled app (Create React App, webpack, Parcel, Vue/Svelte CLI, etc.) — add to your ENTRY module
     (e.g. src/index.js or src/main.js), where '@reticlehq/react' resolves through your bundler:
 
-      if (location.hostname === 'localhost') {
-        const { reticle, install } = await import('@reticlehq/react');
-        install();
-        reticle.connect(${arg});
+      if (window.location.hostname === 'localhost') {
+        void import('@reticlehq/react').then(({ reticle, install }) => {
+          install();
+          reticle.connect(${arg});
+        });
       }
 
   • Plain static HTML with no build step — the browser can't resolve the bare '@reticlehq/react' import, so
@@ -226,7 +247,7 @@ export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
  * here is the one thing this project exists not to do.
  */
 export function unverifiedUiLibraryNote(library) {
-    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here, but @reticlehq/react is a React adapter: component names and data-reticle-source file:line will be missing, and no CI gate covers ${library}. Gated today: Vite + React, Next.js, Remix, Astro. If something doesn't work, please open an issue.`;
+    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here, and source file:line does too — the build plugin stamps data-reticle-source regardless of UI library (measured on preact and svelte). What @reticlehq/react adds and you will NOT get is React component identity: component names and component stacks. No CI gate covers ${library}. Gated today: Vite + React, Next.js, Remix, Astro. If something doesn't work, please open an issue.`;
 }
 export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested — it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix and Astro. If the hook does not register a session, please open an issue.';
 /**
@@ -236,7 +257,7 @@ export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI
  */
 export function svelteKitHooksFile(port, projectId) {
     const base = connectArg(port, projectId);
-    const fields = base === '' ? '' : `${base.slice(1, -1).trim()}, `;
+    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     return `// Dev-only: connect Reticle on the client. SvelteKit renders via app.html, so the Vite-plugin
 // index.html injection doesn't fire — connect from this client hook instead.
 if (import.meta.env.DEV) {
@@ -246,11 +267,19 @@ if (import.meta.env.DEV) {
     // file it lives in, so @reticlehq/vite-plugin inlines it here at build time. Without it the
     // console reads "bridge refused the connection: authentication failed" and no session appears.
     const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-    reticle.connect({ ${fields}...(token.length > 0 ? { token } : {}) });
+    const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+    const sdkVersion = typeof __RETICLE_SDK_VERSION__ !== 'undefined' ? __RETICLE_SDK_VERSION__ : '';
+    reticle.connect({
+      ${fields}...(token.length > 0 ? { token } : {}),
+      ...(root.length > 0 ? { root } : {}),
+      ...(sdkVersion.length > 0 ? { sdkVersion } : {}),
+    });
   });
 }
 
 declare const __RETICLE_TOKEN__: string | undefined;
+declare const __RETICLE_ROOT__: string | undefined;
+declare const __RETICLE_SDK_VERSION__: string | undefined;
 `;
 }
 /**

package/dist/init/vite-config.js

@@ -37,7 +37,7 @@ function insertImport(source) {
 function insertPlugin(source, port) {
     return source.replace(PLUGINS_ARRAY, (match, _g, offset) => {
         const next = source[offset + match.length] ?? '';
-        const separator = next === '' || /\s/.test(next) ? '' : ' ';
+        const separator = '' === next || /\s/.test(next) ? '' : ' ';
         return `${match}${reticlePluginCall(port)},${separator}`;
     });
 }

package/dist/init/windows-quote.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Quote one argument for a Windows command line. Pure, and deliberately NOT platform-gated.
+ *
+ * The rule used to live inside a `process.platform === WINDOWS` branch in node-io.ts, which meant
+ * the Windows path could not be exercised on a mac or in CI's Linux job — so it stayed wrong. A
+ * pure function is most of the fix: it can be asserted anywhere, and it is.
+ *
+ * ## What was wrong
+ *
+ * ```ts
+ * /[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg
+ * ```
+ *
+ * Two independent holes, both reachable from an ordinary directory path:
+ *
+ * 1. **Backslashes were not escaped.** `C:\Users\ada\My Projects\` became
+ *    `"C:\Users\ada\My Projects\"`, whose trailing `\"` reads as an ESCAPED quote — the quoted
+ *    region never closes and the rest of the line is re-parsed by cmd.exe. CodeQL flagged this one
+ *    (`js/incomplete-sanitization`, high).
+ * 2. **The predicate only looked for whitespace and quotes.** An argument like `foo&whoami` has
+ *    neither, so it was handed to cmd.exe completely unquoted. Correct backslash escaping does
+ *    nothing for that; it needs the metacharacters in the trigger.
+ *
+ * ## The rule implemented here
+ *
+ * `CommandLineToArgvW`: a run of backslashes is literal unless it precedes a `"`, in which case the
+ * run is doubled and the quote escaped; a run at the very end sits before the closing quote we add,
+ * so it is doubled too. Correctly-terminated quotes also neutralise cmd.exe's metacharacters, which
+ * it does not interpret inside a quoted region.
+ *
+ * ## Known limit, stated rather than papered over
+ *
+ * `%VAR%` is expanded by cmd.exe even inside quotes, and no quoting prevents it — only avoiding
+ * `shell: true` does, which Windows needs so `pnpm.cmd`/`npx.cmd` resolve (see `shellOpt`). That is
+ * variable substitution, not command execution, and every caller here passes paths and package
+ * names rather than user prose.
+ */
+export declare function windowsShellArg(arg: string): string;

package/dist/init/windows-quote.js

@@ -0,0 +1,70 @@
+/**
+ * Quote one argument for a Windows command line. Pure, and deliberately NOT platform-gated.
+ *
+ * The rule used to live inside a `process.platform === WINDOWS` branch in node-io.ts, which meant
+ * the Windows path could not be exercised on a mac or in CI's Linux job — so it stayed wrong. A
+ * pure function is most of the fix: it can be asserted anywhere, and it is.
+ *
+ * ## What was wrong
+ *
+ * ```ts
+ * /[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg
+ * ```
+ *
+ * Two independent holes, both reachable from an ordinary directory path:
+ *
+ * 1. **Backslashes were not escaped.** `C:\Users\ada\My Projects\` became
+ *    `"C:\Users\ada\My Projects\"`, whose trailing `\"` reads as an ESCAPED quote — the quoted
+ *    region never closes and the rest of the line is re-parsed by cmd.exe. CodeQL flagged this one
+ *    (`js/incomplete-sanitization`, high).
+ * 2. **The predicate only looked for whitespace and quotes.** An argument like `foo&whoami` has
+ *    neither, so it was handed to cmd.exe completely unquoted. Correct backslash escaping does
+ *    nothing for that; it needs the metacharacters in the trigger.
+ *
+ * ## The rule implemented here
+ *
+ * `CommandLineToArgvW`: a run of backslashes is literal unless it precedes a `"`, in which case the
+ * run is doubled and the quote escaped; a run at the very end sits before the closing quote we add,
+ * so it is doubled too. Correctly-terminated quotes also neutralise cmd.exe's metacharacters, which
+ * it does not interpret inside a quoted region.
+ *
+ * ## Known limit, stated rather than papered over
+ *
+ * `%VAR%` is expanded by cmd.exe even inside quotes, and no quoting prevents it — only avoiding
+ * `shell: true` does, which Windows needs so `pnpm.cmd`/`npx.cmd` resolve (see `shellOpt`). That is
+ * variable substitution, not command execution, and every caller here passes paths and package
+ * names rather than user prose.
+ */
+/**
+ * Characters that make cmd.exe do something other than pass the text along.
+ *
+ * Whitespace and `"` split or delimit; the rest are the shell's control operators. An argument
+ * containing any of them must be quoted, not just one containing a space.
+ */
+const NEEDS_QUOTING = /[\s"&|<>^()!%,;=]/;
+export function windowsShellArg(arg) {
+    // An empty argument must still occupy a slot in argv. Unquoted it disappears entirely, silently
+    // shifting every argument after it by one.
+    if (0 === arg.length)
+        return '""';
+    if (!NEEDS_QUOTING.test(arg))
+        return arg;
+    let out = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if ('\\' === ch) {
+            backslashes += 1;
+            continue;
+        }
+        if ('"' === ch) {
+            // 2n+1 backslashes → n literal backslashes and an escaped quote.
+            out += '\\'.repeat(2 * backslashes + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        out += '\\'.repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    // A trailing run sits immediately before the closing quote, so it must be doubled or it escapes it.
+    return `${out}${'\\'.repeat(2 * backslashes)}"`;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
+ *
+ * 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.
+ */
+interface WorkspaceSources {
+    /** Raw contents of pnpm-workspace.yaml, when present. */
+    pnpmWorkspace?: string;
+    /** The `workspaces` field of package.json — array form or the yarn/npm object form. */
+    pkgWorkspaces?: unknown;
+    /** Directory names at the repo root, used when nothing is declared. */
+    topLevelDirs?: readonly string[];
+}
+export declare function workspaceParents(sources: WorkspaceSources): string[];
+export {};

package/dist/init/workspace-apps.js

@@ -0,0 +1,68 @@
+/**
+ * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
+ *
+ * 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.
+ */
+/** Directories that are never a workspace package, whatever the layout. */
+const NEVER_A_PACKAGE = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', 'target']);
+/** `packages/*` -> `packages`; `web` -> `web`. The base directory a glob searches. */
+function globBase(pattern) {
+    const base = pattern
+        .split('/')[0]
+        ?.trim()
+        .replace(/^['"]|['"]$/g, '');
+    return base === undefined || '' === base || '.' === base || base.includes('*') ? undefined : base;
+}
+function fromPnpm(yaml) {
+    // A deliberately small reader rather than a YAML dependency: this file is a list of globs, and the
+    // only shape that matters is `- 'pattern'` under `packages:`. A malformed file yields nothing,
+    // which falls through to the top-level scan rather than failing the install.
+    const out = [];
+    let inPackages = false;
+    for (const line of yaml.split('\n')) {
+        if (/^packages\s*:/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages && /^\S/.test(line))
+            break;
+        const item = /^\s*-\s*(.+)$/.exec(line);
+        if (inPackages && item?.[1] !== undefined) {
+            const base = globBase(item[1]);
+            if (base !== undefined)
+                out.push(base);
+        }
+    }
+    return out;
+}
+function fromPkg(workspaces) {
+    const list = Array.isArray(workspaces)
+        ? workspaces
+        : 'object' === typeof workspaces && workspaces !== null
+            ? workspaces.packages
+            : undefined;
+    if (!Array.isArray(list))
+        return [];
+    return list
+        .filter((p) => 'string' === typeof p)
+        .map(globBase)
+        .filter((p) => p !== undefined);
+}
+export function workspaceParents(sources) {
+    const declared = [
+        ...(sources.pnpmWorkspace === undefined ? [] : fromPnpm(sources.pnpmWorkspace)),
+        ...fromPkg(sources.pkgWorkspaces),
+    ];
+    const candidates = declared.length > 0
+        ? declared
+        : (sources.topLevelDirs ?? []).filter((d) => !d.startsWith('.') && !NEVER_A_PACKAGE.has(d));
+    return [...new Set(candidates)];
+}

package/dist/input/driven-redaction.js

@@ -35,7 +35,7 @@ function invalidate() {
 }
 /** Record what a session declared sensitive. Called when its hello lands. */
 export function declareDrivenRedactionKeys(sessionId, keys) {
-    if (keys.length === 0) {
+    if (0 === keys.length) {
         if (declaredBySession.delete(sessionId))
             invalidate();
         return;

package/dist/input/network-detail.js

@@ -21,7 +21,7 @@ const DEFAULT_POLICY = { isSensitiveKey: defaultIsSensitiveKey };
 function redactByKey(value, policy) {
     if (Array.isArray(value))
         return value.map((v) => redactByKey(v, policy));
-    if (value !== null && typeof value === 'object') {
+    if (value !== null && 'object' === typeof value) {
         const out = {};
         for (const [k, v] of Object.entries(value)) {
             out[k] = policy.isSensitiveKey(k) ? REDACTED_VALUE : redactByKey(v, policy);
@@ -82,15 +82,15 @@ export function buildNetworkDetail(raw, policy = DEFAULT_POLICY) {
         status: raw.status,
         headers: projectHeaders(raw.headers, policy),
         ...(raw.resourceType === undefined ? {} : { resourceType: raw.resourceType }),
-        ...(raw.requestBody === undefined || raw.requestBody.length === 0
+        ...(raw.requestBody === undefined || 0 === raw.requestBody.length
             ? {}
             : { requestBody: projectWireBody(raw.requestBody, policy) }),
-        ...(raw.pageUrl === undefined || raw.pageUrl.length === 0 ? {} : { pageUrl: raw.pageUrl }),
+        ...(raw.pageUrl === undefined || 0 === raw.pageUrl.length ? {} : { pageUrl: raw.pageUrl }),
     };
 }
 function keyOf(url, method) {
-    const m = typeof method === 'string' ? method.toUpperCase() : '';
-    const u = typeof url === 'string' ? url : '';
+    const m = 'string' === typeof method ? method.toUpperCase() : '';
+    const u = 'string' === typeof url ? url : '';
     return `${m} ${u}`;
 }
 /**
@@ -127,9 +127,9 @@ export function mergeNetworkDetail(events) {
             // finding — that is the whole reason for capturing it — so the authoritative one wins and the
             // divergence is flagged rather than silently resolved.
             const wireBody = e.data['requestBody'];
-            if (typeof wireBody === 'string') {
+            if ('string' === typeof wireBody) {
                 const pageBody = data['requestBody'];
-                if (typeof pageBody === 'string' && pageBody !== wireBody) {
+                if ('string' === typeof pageBody && pageBody !== wireBody) {
                     data['requestBodyDivergedFromPage'] = true;
                 }
                 data['requestBody'] = wireBody;
@@ -162,7 +162,7 @@ export function attachNetworkDetail(page, emit) {
                 status: response.status(),
                 headers,
                 ...(resourceType === undefined ? {} : { resourceType }),
-                ...(postData === null ? {} : { requestBody: postData }),
+                ...(null === postData ? {} : { requestBody: postData }),
                 pageUrl: page.url(),
             }, 
             // Resolved per response, not per attachment: a session declaring extra keys can connect

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

@@ -5,7 +5,7 @@ import { sessionIdShape } from '../tools/tool-kit.js';
 import { asString } from '../tools/tools-helpers.js';
 function mockProvider(deps) {
     const p = deps.realInput;
-    return p !== undefined && typeof p.setMocks === 'function' ? p : undefined;
+    return p !== undefined && 'function' === typeof p.setMocks ? p : undefined;
 }
 const ruleShape = z.object({
     urlContains: z
@@ -80,7 +80,7 @@ export const NETWORK_MOCK_TOOLS = [
                 };
             }
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const rules = args['clear'] === true ? [] : toRules(args['mocks']);
+            const rules = true === args['clear'] ? [] : toRules(args['mocks']);
             const applied = await provider.setMocks(session.url, rules);
             return { applied, count: applied ? rules.length : 0 };
         },

package/dist/input/network-mock.js

@@ -10,7 +10,7 @@ export function matchMock(rules, req) {
             continue;
         if (rule.method !== undefined && rule.method.toUpperCase() !== req.method.toUpperCase())
             continue;
-        if (rule.abort === true)
+        if (true === rule.abort)
             return { kind: 'abort' };
         const outcome = {
             kind: 'fulfill',
@@ -27,11 +27,11 @@ export function matchMock(rules, req) {
 }
 /** Apply a matched outcome to a Playwright Route. Exported so the route handler is testable in isolation. */
 export async function applyOutcome(route, outcome, sleep) {
-    if (outcome.kind === 'continue') {
+    if ('continue' === outcome.kind) {
         await route.continue();
         return;
     }
-    if (outcome.kind === 'abort') {
+    if ('abort' === outcome.kind) {
         await route.abort('failed');
         return;
     }
@@ -51,7 +51,7 @@ const realSleep = (ms) => new Promise((res) => setTimeout(res, ms));
  */
 export async function installNetworkMocks(page, rules, sleep = realSleep) {
     await page.unroute('**/*').catch(() => undefined);
-    if (rules.length === 0)
+    if (0 === rules.length)
         return;
     await page.route('**/*', (route) => {
         const req = route.request();

package/dist/input/real-input.js

@@ -1,3 +1,4 @@
+import { gotoOptions } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../telemetry/connect-failure.js';
@@ -93,7 +94,7 @@ const SCREENSHOT_DETERMINISM = { style: HIDE_RETICLE_CHROME_CSS, animations: 'di
 export async function capturePage(page, opts) {
     const buf = await page.screenshot(opts.clip !== undefined
         ? { ...SCREENSHOT_DETERMINISM, clip: opts.clip }
-        : opts.fullPage === true
+        : true === opts.fullPage
             ? { ...SCREENSHOT_DETERMINISM, fullPage: true }
             : { ...SCREENSHOT_DETERMINISM });
     return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
@@ -269,7 +270,11 @@ export class LaunchedRealInputProvider {
         if (this.#onNetworkDetail !== undefined)
             attachNetworkDetail(page, this.#onNetworkDetail);
         try {
-            await page.goto(this.#driveUrl);
+            // Same navigation rule as the pool, and for the same measured reason: Playwright's default
+            // waits for `load`, which an app with one never-finishing subresource never fires — 30s of
+            // nothing and then a failure that blames the app. The SDK connect is a module script, so it
+            // has already run by DOMContentLoaded. See gotoOptions.
+            await page.goto(this.#driveUrl, gotoOptions(undefined));
         }
         catch (e) {
             throw new DriveError(DriveErrorCode.NAVIGATE_FAILED, e instanceof Error ? e.message : String(e));
@@ -369,7 +374,7 @@ export function selectPage(pages, sessionUrl) {
         return exact;
     const target = stripVolatile(sessionUrl);
     const loose = pages.filter((p) => stripVolatile(p.url()) === target);
-    return loose.length === 1 ? loose[0] : undefined;
+    return 1 === loose.length ? loose[0] : undefined;
 }
 function stripVolatile(url) {
     const hash = url.indexOf('#');

package/dist/input/scroll-find.js

@@ -38,7 +38,7 @@ export async function scrollToFind(session, q, opts = {}) {
             return { found: true, element: hit, scrolls, exhausted: false };
         // Fall through to linear refinement from current position (already near the target).
         const data = asRecord(sr.result);
-        if (data['atEnd'] === true || data['scrolled'] === false) {
+        if (true === data['atEnd'] || false === data['scrolled']) {
             return { found: false, scrolls, exhausted: true };
         }
     }
@@ -50,7 +50,7 @@ export async function scrollToFind(session, q, opts = {}) {
         if (hit !== undefined)
             return { found: true, element: hit, scrolls, exhausted: false };
         // Reached the bottom or the container would not move — no more rows to reveal.
-        if (data['atEnd'] === true || data['scrolled'] === false) {
+        if (true === data['atEnd'] || false === data['scrolled']) {
             return { found: false, scrolls, exhausted: true };
         }
     }

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

@@ -1,7 +1,2 @@
 import type { ToolDef } from '../tools/tools.js';
-/**
- * reticle_scroll_to — the windowed/virtualized-list escape hatch. A plain reticle_query
- * only sees rendered nodes, so an off-screen row in a react-window/react-virtualized list returns
- * nothing. This scrolls the container until the row mounts, then returns its ref.
- */
 export declare const SCROLL_TOOLS: ToolDef[];

package/dist/input/scroll-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { QueryBy } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { scrollToFind } from './scroll-find.js';
@@ -7,14 +8,20 @@ import { scrollToFind } from './scroll-find.js';
  * only sees rendered nodes, so an off-screen row in a react-window/react-virtualized list returns
  * nothing. This scrolls the container until the row mounts, then returns its ref.
  */
+/**
+ * The query strategies, derived from QueryBy — the same vocabulary reticle_query uses, and for the
+ * same reason. A free string here produced the identical false negative: `by:'css'` scrolled the
+ * whole list and reported `{ found: false, exhausted: true }`, which reads as "the row is not in
+ * this list" rather than "that strategy does not exist".
+ */
+const QUERY_BY_LIST = Object.values(QueryBy).join(' | ');
+const queryByEnum = z.enum(Object.values(QueryBy));
 export const SCROLL_TOOLS = [
     {
         name: ReticleTool.SCROLL_TO,
-        description: 'Find an element in a VIRTUALIZED list that has not rendered yet. Pass `by` (role|text|testid|label|placeholder|alt) and `value` (query string) to identify the target row. Scrolls the container until the row mounts, the list ends, or maxScrolls (default 20) is spent. Pass targetIndex + totalCount for bisection — jumps directly to the estimated offset in one scroll (e.g. targetIndex:800 totalCount:1000 jumps to 80% of scrollHeight). Returns { found, element?, scrolls, exhausted }.',
+        description: 'Find an element in a VIRTUALIZED list that has not rendered yet. Pass `by` (see the parameter for the exact strategies) and `value` (query string) to identify the target row. Scrolls the container until the row mounts, the list ends, or maxScrolls (default 20) is spent. Pass targetIndex + totalCount for bisection — jumps directly to the estimated offset in one scroll (e.g. targetIndex:800 totalCount:1000 jumps to 80% of scrollHeight). Returns { found, element?, scrolls, exhausted }.',
         inputSchema: {
-            by: z
-                .string()
-                .describe('Query strategy for finding the target: role | text | testid | label | placeholder | alt'),
+            by: queryByEnum.describe(`Query strategy for finding the target: ${QUERY_BY_LIST}`),
             value: z
                 .string()
                 .describe('Query value for the selected strategy (the element to scroll into view).'),

package/dist/input/viewport-tools.js

@@ -8,7 +8,7 @@ const MIN_DIM = 64;
 const MAX_DIM = 10000;
 function viewportProvider(deps) {
     const p = deps.realInput;
-    return p !== undefined && typeof p.setViewport === 'function'
+    return p !== undefined && 'function' === typeof p.setViewport
         ? p
         : undefined;
 }
@@ -54,6 +54,6 @@ export const VIEWPORT_TOOLS = [
 ];
 /** Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing/NaN value falls back to MIN_DIM. */
 function clampDim(value) {
-    const n = typeof value === 'number' && Number.isFinite(value) ? Math.round(value) : MIN_DIM;
+    const n = 'number' === typeof value && Number.isFinite(value) ? Math.round(value) : MIN_DIM;
     return Math.max(MIN_DIM, Math.min(n, MAX_DIM));
 }

package/dist/journal/ambient-store.d.ts

@@ -1,7 +1,5 @@
 import type { FileSystemPort } from '../project/fs-port.js';
 import { type AmbientCounts } from './ambient.js';
-/** Bumped on any breaking change to the persisted ambient-map shape. */
-export declare const AMBIENT_FILE_VERSION = 1;
 /**
  * Persists the learned ambient-churn region map at `.reticle/ambient.json`. Local, single-project
  * memory (stays OSS — OSS-VS-SERVER). Loads never throw: missing/malformed/wrong-version degrades to

package/dist/journal/ambient-store.js

@@ -2,7 +2,7 @@ import { dirname } from 'node:path';
 import { reticleDirPaths } from '../project/reticle-dir.js';
 import { AmbientFileSchema } from './ambient.js';
 /** Bumped on any breaking change to the persisted ambient-map shape. */
-export const AMBIENT_FILE_VERSION = 1;
+const AMBIENT_FILE_VERSION = 1;
 /**
  * Persists the learned ambient-churn region map at `.reticle/ambient.json`. Local, single-project
  * memory (stays OSS — OSS-VS-SERVER). Loads never throw: missing/malformed/wrong-version degrades to

package/dist/journal/ambient.js

@@ -8,7 +8,7 @@ import { z } from 'zod';
  */
 export function ambientKeyOf(event) {
     const region = event.data?.['region'];
-    if (typeof region === 'string' && region.length > 0)
+    if ('string' === typeof region && region.length > 0)
         return region;
     return event.ref;
 }