@reticlehq/server 2.7.0 → 2.9.0

package/dist/init/snippets.js

@@ -2,7 +2,29 @@
  * 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, bridgeWsUrl } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, ReticleDir, bridgeWsUrl } from '@reticlehq/core';
+import { UiLibrary } from './detect.js';
+import { SERVER_VERSION } from '../version/server-version.js';
+/**
+ * The SDK as one import a plain page can actually resolve.
+ *
+ * `init` used to tell static-HTML users that a page with no build step could not load the SDK, and
+ * to go and stand up a bundler. That is true of a BARE specifier and false of a URL, and the
+ * difference was the whole road for every server-rendered app we hear from: FastAPI, Flask, Django,
+ * Streamlit, Rails. Proven end to end before this shipped, on a page served by `python3 -m
+ * http.server`: a session connected, a snapshot returned, and two act_and_wait calls came back
+ * `verified: "yes"`.
+ *
+ * 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.
+ *
+ * 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.
+ */
+const CDN_SDK_URL = `https://cdn.jsdelivr.net/npm/@reticlehq/browser@${SERVER_VERSION}/+esm`;
 /**
  * The connect argument literal: a non-default port adds a `url`, and a projectId is always passed
  * (so the app is identifiable across port changes). Empty string only when neither applies.
@@ -16,18 +38,76 @@ function connectArg(port, projectId) {
         parts.push(`projectId: '${projectId}'`);
     return parts.length > 0 ? `{ ${parts.join(', ')} }` : '';
 }
+/**
+ * The same literal, with the pairing token folded in.
+ *
+ * The token belongs INSIDE the call the user pastes. Every other stack has a build step to inline
+ * it (the Vite plugin's `define`, Next's NEXT_PUBLIC_*, Astro's config, CRA's .env); the hand-wired
+ * paths have none, so `init` inlines the literal it already read. Without it the bridge closes the
+ * socket with AUTH_FAILED and no session ever appears: see Bridge's hello handler.
+ *
+ * An empty token is omitted rather than emitted as `token: ''`. A daemon that could not write to
+ * $HOME runs without auth and trusts loopback, and an empty string would fail the comparison against
+ * one that does hold a token.
+ */
+export function connectArgWithToken(port, projectId, pairingToken) {
+    const base = connectArg(port, projectId);
+    if (pairingToken === undefined || 0 === pairingToken.length)
+        return base;
+    const inner = base.length > 0 ? base.slice(1, -1).trim() : '';
+    return `{ ${[inner, `token: '${pairingToken}'`].filter((p) => p.length > 0).join(', ')} }`;
+}
+/**
+ * Which SDK package the GENERATED code should import, and whether `install()` applies.
+ *
+ * This has to agree with `frameworkPackages`, and it did not. That function was changed so a Vue or
+ * Svelte app installs `@reticlehq/browser` instead of the React adapter — correctly — while every
+ * generated connect snippet still said `import('@reticlehq/react')`. A SvelteKit app would have
+ * installed the sensor and then run a hook importing a package that is not there.
+ *
+ * `install()` is the React adapter's, not the sensor's: `@reticlehq/browser` exports `reticle` and no
+ * `install`, so swapping the specifier alone would trade a missing module for a missing export.
+ */
+export function sdkImport(uiLibrary) {
+    const react = uiLibrary !== UiLibrary.VUE && uiLibrary !== UiLibrary.SVELTE;
+    return react
+        ? { specifier: '@reticlehq/react', usesInstall: true }
+        : { specifier: '@reticlehq/browser', usesInstall: false };
+}
+/**
+ * The framework plugin to show ALONGSIDE reticle() in the example, so the ordering is clear.
+ *
+ * It used to be `react()` unconditionally, which is what a Vue app was shown — a plugin it does not
+ * have, four lines after `init` had correctly detected Vue and said so. The example exists to show
+ * that `reticle()` goes last, not to tell anyone which UI framework they are using.
+ */
+function frameworkPluginExample(uiLibrary) {
+    switch (uiLibrary) {
+        case UiLibrary.VUE:
+            return 'vue()';
+        case UiLibrary.SVELTE:
+            return 'svelte()';
+        case UiLibrary.REACT:
+        case UiLibrary.PREACT:
+            return 'react()';
+        default:
+            // Nothing detected: name no plugin rather than invent one. The reader keeps whatever they have.
+            return '/* your existing plugins */';
+    }
+}
 /** The Vite-config snippet printed when we can't safely auto-patch the config. */
-export function viteManual(port) {
+export function viteManual(port, uiLibrary = UiLibrary.UNKNOWN) {
     const call = port === undefined ? 'reticle()' : `reticle({ port: ${String(port)} })`;
     return `Add the Reticle plugin to your Vite config:
 
   import { reticle } from '@reticlehq/vite-plugin';
 
   export default defineConfig({
-    plugins: [react(), ${call}],
+    plugins: [${frameworkPluginExample(uiLibrary)}, ${call}],
   });
 
-The plugin only applies during \`vite\` (dev) — it is dropped from \`vite build\`.`;
+Keep \`reticle()\` LAST so it sees the output of your other plugins. It only applies during \`vite\`
+(dev) — it is dropped from \`vite build\`.`;
 }
 /** Next.js config wrap — always printed (we never auto-rewrite next.config). */
 export function nextConfigManual(configFile) {
@@ -45,21 +125,27 @@ export function nextConfigManual(configFile) {
  * as `NEXT_PUBLIC_RETICLE_TOKEN`. This file used to connect with only a projectId, so every Next
  * setup ended at `bridge refused the connection: authentication failed` and no session ever appeared.
  */
-export function nextReticleDevFile(port, projectId, testids = [], stores = []) {
+export function nextReticleDevFile(port, projectId, testids = [], stores = [], found = []) {
     const base = connectArg(port, projectId);
     const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     const ids = testids.map((t) => `'${t}'`).join(', ');
-    const storeBlock = 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');
+    // 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');
+    const storeBlock = found.length > 0
+        ? 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');
     return `'use client';
 import { useEffect } from 'react';
+${storeImports.length > 0 ? storeImports : ''}
 
 /** 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 }) => {
+    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.
@@ -73,9 +159,9 @@ export function ReticleDev() {
       // 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' : ''}
+        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
+        stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
       });
     });
   }, []);
@@ -171,15 +257,29 @@ Start the daemon BEFORE \`astro dev\`, so the token file exists when the config
  * breaks the module everything else hangs off. So the store lines are generated COMMENTED, naming
  * the libraries actually found in package.json, with the exact call to uncomment.
  */
-export function viteDevModuleFile(testids, stores) {
+export function viteDevModuleFile(testids, stores, found = [], uiLibrary = UiLibrary.REACT) {
+    // The specifier has to be the package `frameworkPackages` installed. This file is the Vite path —
+    // the commonest install there is — and it was hardcoded to `@reticlehq/react` while a Vue or
+    // Svelte app was being given `@reticlehq/browser`, so the generated file imported something that
+    // was not there. Caught by running `init` against a pristine Vue app, not by any gate.
+    //
+    // The sensor exports `registerCapabilities` and `registerStore` (and the store adapters) just as
+    // the React kit does; the only thing it lacks is `install()`, which this file never called.
+    const sdk = sdkImport(uiLibrary);
     const ids = testids.map((t) => `'${t}'`).join(', ');
-    const storeBlock = 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');
-    return `// Dev-only. Imported automatically by @reticlehq/vite-plugin — you do not need to import it.
+    // A store we FOUND is imported and registered outright — the whole point of the file. The hints
+    // stay only for the libraries we can name but not wire (they need an argument we cannot infer).
+    const storeImports = found.map((s) => `import { ${s.ident} } from '${s.importPath}';`).join('\n');
+    const storeBlock = found.length > 0
+        ? 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');
+    const registerImport = found.length > 0 ? 'registerCapabilities, registerStore' : 'registerCapabilities';
+    return `// Dev-only. Imported automatically by @reticlehq/vite-plugin, so you do not need to import it.
 // Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
-import { registerCapabilities } from '@reticlehq/react';
-
+import { ${registerImport} } from '${sdk.specifier}';
+${storeImports.length > 0 ? `${storeImports}\n` : ''}
 if (import.meta.env.DEV) {
   // ── Start with ONE flow. ─────────────────────────────────────────────────────────────────────
   // You do not need to describe the whole app to get value, and trying to is the slow path. Register
@@ -193,9 +293,9 @@ if (import.meta.env.DEV) {
 ${storeBlock}
 
   registerCapabilities({
-    testids: [${ids}],${0 === testids.length ? ' // 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
+    stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
   });
 }
 `;
@@ -216,17 +316,23 @@ export const NEXT_LAYOUT_MANUAL = `Mount <ReticleDev /> in your root layout (app
  * where a bare `@reticlehq/react` import resolves. A bare import in a plain index.html does NOT resolve in
  * the browser, so we never tell a bundled app to do that (the old advice silently failed for CRA).
  */
+/**
+ * The whole install, for a page with no build step, as one block a person can paste.
+ *
+ * Extracted so the `no package.json` exit can print the SAME snippet `htmlManual` offers. That exit
+ * is the one every server-rendered app reaches (FastAPI, Flask, Django, Rails, Streamlit), it is
+ * where `init` stops, and until now it stopped with an explanation instead of an answer. A message
+ * that says "add the snippet below" and then prints no snippet is the same defect wearing the
+ * opposite sign, so the two share a builder rather than a copy.
+ */
+export function staticPageSnippet(connectArgLiteral) {
+    return `      <script type="module">
+        import { reticle } from '${CDN_SDK_URL}';
+        reticle.connect(${connectArgLiteral});
+      </script>`;
+}
 export function htmlManual(port, projectId, pairingToken) {
-    const base = connectArg(port, projectId);
-    // The token belongs INSIDE the call the user pastes. Every other stack has a build step to inline
-    // it (the Vite plugin's `define`, Next's NEXT_PUBLIC_*, Astro's config, CRA's .env); this path has
-    // none, so `init` inlines the literal it already read. Without it the bridge closes the socket
-    // with AUTH_FAILED and no session ever appears — see Bridge's hello handler.
-    const withToken = pairingToken === undefined || 0 === pairingToken.length
-        ? base
-        : `{ ${[base.length > 0 ? base.slice(1, -1).trim() : '', `token: '${pairingToken}'`]
-            .filter((p) => p.length > 0)
-            .join(', ')} }`;
+    const withToken = connectArgWithToken(port, projectId, pairingToken);
     const tokenNote = pairingToken === undefined || 0 === pairingToken.length
         ? ''
         : `\n\n  The \`token\` is this machine's pairing token, read from ~/.reticle/pairing-token. Keep it: the
@@ -237,16 +343,26 @@ export function htmlManual(port, projectId, pairingToken) {
   • 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 (window.location.hostname === 'localhost') {
+      if (process.env.NODE_ENV !== 'production') {
         void import('@reticlehq/react').then(({ reticle, install }) => {
           install();
           reticle.connect(${withToken});
         });
       }${tokenNote}
 
-  • Plain static HTML with no build step — the browser can't resolve the bare '@reticlehq/react' import, so
-    bundle the SDK once (e.g. \`npx esbuild\`) and point a dev-only <script type="module"> at the output,
-    or serve the page through a dev server (Vite) that resolves bare imports.`;
+  • Plain HTML with NO build step (FastAPI, Flask, Django, Rails, Streamlit, a hand-written page) —
+    paste this into the page, in a template you only serve in development. There is nothing to
+    install: no npm, no bundler, no package.json.
+
+${staticPageSnippet(withToken)}
+
+  Serving the app on something other than localhost (a hosts-file alias, a LAN IP, a container, a
+  tunnel)? You need TWO things, not one: \`allowNonLocalhost: true\` AND a pairing token, passed as
+  \`token\` on the same connect. The flag alone is NOT sufficient — off localhost the SDK refuses
+  without a token as well, and that refusal is page-side, so the daemon sees only silence and every
+  \`reticle doctor\` check still passes. The token is the one in \`~/.reticle/pairing-token\` (the
+  build plugins read the same file). Without both, the SDK says so in the browser console only, so
+  from here it looks exactly like nothing happened.`;
 }
 export const NEXT_RETICLE_DEV_PATH = 'app/reticle-dev.tsx';
 export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
@@ -261,7 +377,15 @@ 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, 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.`;
+    // Preact is not in the same position as Vue or Svelte and must not be told it is. The React
+    // adapter reaches Preact through `preact/compat`, which is what `docs/frameworks.mdx` has always
+    // said, so telling a Preact reader they get no component identity contradicts our own docs and
+    // talks them out of a package that is the right one for them. It is still ungated, which is the
+    // honest caveat, and #129 is the issue for closing that.
+    const identity = 'preact' === library
+        ? 'React component identity — component names and stacks — comes from `@reticlehq/react`, which reaches Preact through `preact/compat`. That path is not covered by a CI gate here, so treat it as expected-to-work rather than proven.'
+        : 'What `@reticlehq/react` adds and you will NOT get is React component identity: component names and component stacks.';
+    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here. ${'vue' === library ? 'Source `file:line` does NOT come through: the build plugin stamps JSX and, separately, Svelte components, and a Vue single-file component is neither — measured, a Svelte counter reports `src/lib/Counter.svelte:5` and the same drive on Vue reports no source at all.' : 'Source `file:line` does too — the build plugin stamps it for this library (measured on preact and svelte).'} ${identity} ${'vue' === library ? 'The install gate scaffolds a Vue app from scratch on every change, so this SETUP is proven; no gate drives a Vue app to a verdict, so the drive is not.' : `No CI gate covers ${library}.`} Driven on every change: 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.';
 /**
@@ -269,14 +393,18 @@ export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI
  * never triggers Vite's index.html injection (verified), so the standard plugin can't auto-connect —
  * a client hook is the reliable path. SvelteKit runs src/hooks.client.ts on the client at startup.
  */
-export function svelteKitHooksFile(port, projectId) {
+export function svelteKitHooksFile(port, projectId, uiLibrary = UiLibrary.SVELTE) {
+    // SvelteKit is Svelte, so this defaults to the sensor rather than the React adapter — and the
+    // import here MUST match what `frameworkPackages` installed, or the hook loads a package that is
+    // not in node_modules. See sdkImport.
+    const sdk = sdkImport(uiLibrary);
     const base = connectArg(port, projectId);
     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) {
-  void import('@reticlehq/react').then(({ reticle, install }) => {
-    install();
+  void import('${sdk.specifier}').then(({ reticle${sdk.usesInstall ? ', install' : ''} }) => {
+    ${sdk.usesInstall ? 'install();' : '// No React adapter here: the sensor has no install() to call.'}
     // The bridge requires the pairing token even on localhost. Nothing in a browser can read the
     // 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.
@@ -338,9 +466,23 @@ and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which i
 2. Restart the dev server. A dev server that is already running does not pick up a new plugin —
    it will not appear in .nuxt/plugins/client.mjs, and the app will come up with no SDK at all.
 
-3. If your dev host is anything other than localhost (a hosts-file alias, a LAN IP, a tunnel), add
-   allowNonLocalhost: true to that connect call. Without it the SDK loads and then refuses, and the
-   only sign is one line in the browser console.
+3. If your dev host is anything other than localhost (a hosts-file alias, a LAN IP, a tunnel), that
+   connect call needs TWO additions, not one: allowNonLocalhost: true AND a pairing token passed as
+   token. The flag alone is NOT sufficient off localhost. The token is the one in
+   ~/.reticle/pairing-token. Without both, the SDK loads and then refuses, and the only sign is one
+   line in the browser console.
+
+4. Add this to nuxt.config, so the dev server does not watch Reticle's own journal:
+
+     vite: { server: { watch: { ignored: [/(^|[\\\\/])\\.${ReticleDir.ROOT.slice(1)}([\\\\/]|$)/] } } }
+
+   Reticle journals every session into ${ReticleDir.ROOT}/ in your project root, rewriting one file
+   in it continuously while a session is live. Nuxt's dev server watches that root, so without this
+   it sees each write as a project file changing and full-reloads the page — which reconnects the
+   SDK, which produces the next write. The loop runs several times a second and looks like anything
+   except what it is: refs go stale, actions die mid-flight, and the session appears to flap.
+   It is a RegExp rather than a glob on purpose — chokidar dropped glob support in v4, so a
+   double-star pattern here is accepted and matches nothing.
 
 The package is @reticlehq/browser — the framework-neutral sensor. DOM, network, console, routing and
 source file:line all work in Vue. What you do not get is React component identity, which is the only
@@ -351,11 +493,21 @@ if something does not work, please open an issue.`;
  * Root-level project config for Reticle. Written by `reticle init`; read by `reticle mcp` for the port
  * and by tooling for the stable projectId (the app's identity across port changes).
  */
-export function reticleConfigContent(framework, port, projectId) {
+export function reticleConfigContent(framework, port, projectId, installSource) {
     const fields = { framework };
     if (projectId !== undefined && projectId.length > 0)
         fields['projectId'] = projectId;
     if (port !== undefined && port !== RETICLE_DEFAULT_PORT)
         fields['port'] = port;
+    // How this install arrived, recorded HERE because it is a property of the install and the only
+    // moment anything knows it is the moment it happens. It reaches us as an environment variable set
+    // by whichever channel ran the install, and an environment variable is gone by the next command,
+    // so every event after this one reported `unknown` and the question "which channel actually
+    // converts" could not be asked at all. Written once, read for the life of the project.
+    //
+    // A closed vocabulary, narrowed before it gets here, so this can never carry a path or a URL.
+    if (installSource !== undefined && installSource.length > 0) {
+        fields['installSource'] = installSource;
+    }
     return `${JSON.stringify(fields, null, 2)}\n`;
 }

package/dist/init/vite-config.js

@@ -7,14 +7,46 @@
 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 — carries the bridge port so the injected connect targets it. */
+/**
+ * The `reticle(...)` call — the bridge port so the injected connect targets it, and body capture.
+ *
+ * `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.
+ *
+ * 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.
+ */
 function reticlePluginCall(port) {
-    return port === undefined ? 'reticle()' : `reticle({ port: ${String(port)} })`;
+    const options = [
+        ...(port === undefined ? [] : [`port: ${String(port)}`]),
+        'captureNetworkBodies: true',
+    ];
+    return `reticle({ ${options.join(', ')} })`;
 }
 /** Matches the start of a `plugins: [` array literal. */
 const PLUGINS_ARRAY = /plugins\s*:\s*\[/;
 /** Matches an ES import statement (used to place our import after the last one). */
 const IMPORT_LINE = /^import\s.+from\s+['"][^'"]+['"];?\s*$/gm;
+/**
+ * The opening `{` of the exported config object — `defineConfig({`, or a bare `export default {`.
+ * Used only when there is no `plugins` array to extend: the object is right there, so adding the
+ * key is the same edit as extending the array, and bailing sent a user whose config merely set
+ * `server.port` to a manual paste for a change we can make correctly.
+ *
+ * A config built by a call (`defineConfig(buildOptions())`) has no literal to extend and still
+ * bails — the rule stays "only edit a shape we can see whole".
+ */
+const CONFIG_OBJECT = /(export\s+default\s+(?:defineConfig\s*\(\s*)?)\{/;
 /** Alias kept so existing call sites read in Vite terms; the vocabulary is shared (see patch-kind). */
 export const VitePatchKind = PatchKind;
 const NO_PLUGINS_REASON = "couldn't find a `plugins: [...]` array to extend";
@@ -41,12 +73,28 @@ function insertPlugin(source, port) {
         return `${match}${reticlePluginCall(port)},${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) {
+    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)}],`;
+        return multiline ? `${prefix}{\n${indent}${key}` : `${prefix}{ ${key}`;
+    });
+}
 export function patchViteConfig(source, port) {
     if (source.includes(RETICLE_MARKER)) {
         return { kind: VitePatchKind.ALREADY };
     }
-    if (!PLUGINS_ARRAY.test(source)) {
-        return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
+    if (PLUGINS_ARRAY.test(source)) {
+        return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
+    }
+    if (CONFIG_OBJECT.test(source)) {
+        return { kind: VitePatchKind.APPLY, code: insertImport(insertPluginsKey(source, port)) };
     }
-    return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
+    return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
 }

package/dist/input/network-mock-tools.d.ts

@@ -1,2 +1,21 @@
+import type { MockRule } from './network-mock.js';
 import type { ToolDef } from '../tools/tools.js';
+/**
+ * Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes).
+ *
+ * THROWS on a malformed rule rather than falling back to `[]`, because `[]` is not a neutral value
+ * here — it is the documented way to clear every active mock. A rule with a wrong field name used to
+ * produce exactly the call that turns mocking OFF, and the handler then reported `applied: true`
+ * with `count: 0`. For a tool whose entire job is forcing an error state, that means the agent
+ * checks the app's failure handling against the real backend, sees the happy path, and reports that
+ * the error state works.
+ *
+ * Same rule as the action arguments: an argument that could not be understood is refused by name,
+ * never reinterpreted into a destructive default. A valueless `fill` used to wipe the field and
+ * report ok; it throws now, for this reason.
+ *
+ * `undefined` and `[]` still mean "clear" — those are deliberate, documented requests, not failures
+ * to parse.
+ */
+export declare function toRules(value: unknown): MockRule[];
 export declare const NETWORK_MOCK_TOOLS: ToolDef[];

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

@@ -26,11 +26,36 @@ const ruleShape = z.object({
         .optional()
         .describe('Simulate a network failure (offline) instead of a response.'),
 });
-/** Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes). */
-function toRules(value) {
-    const parsed = z.array(ruleShape).safeParse(value);
-    if (!parsed.success)
+/**
+ * Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes).
+ *
+ * THROWS on a malformed rule rather than falling back to `[]`, because `[]` is not a neutral value
+ * here — it is the documented way to clear every active mock. A rule with a wrong field name used to
+ * produce exactly the call that turns mocking OFF, and the handler then reported `applied: true`
+ * with `count: 0`. For a tool whose entire job is forcing an error state, that means the agent
+ * checks the app's failure handling against the real backend, sees the happy path, and reports that
+ * the error state works.
+ *
+ * Same rule as the action arguments: an argument that could not be understood is refused by name,
+ * never reinterpreted into a destructive default. A valueless `fill` used to wipe the field and
+ * report ok; it throws now, for this reason.
+ *
+ * `undefined` and `[]` still mean "clear" — those are deliberate, documented requests, not failures
+ * to parse.
+ */
+export function toRules(value) {
+    if (value === undefined)
         return [];
+    const parsed = z.array(ruleShape).safeParse(value);
+    if (!parsed.success) {
+        const problem = parsed.error.issues
+            .map((i) => `${0 === i.path.length ? 'mocks' : `mocks.${i.path.join('.')}`}: ${i.message}`)
+            .join('; ');
+        throw new Error(`reticle_network_mock could not read \`mocks\` (${problem}). Nothing was applied and mocking ` +
+            'was left unchanged — an unreadable rule is NOT treated as a request to clear. A rule is ' +
+            '{ urlContains, method?, status?, body?, contentType?, delayMs?, abort? }; pass `clear: true` ' +
+            'or an empty array if you meant to turn mocking off.');
+    }
     return parsed.data.map((r) => {
         const rule = { urlContains: r.urlContains };
         if (r.method !== undefined)
@@ -56,7 +81,14 @@ export const NETWORK_MOCK_TOOLS = [
             'states without touching the backend ("verify the app handles a failed payment"). Pass `mocks` ' +
             '(first matching rule wins); pass an empty array or `clear: true` to turn mocking off.',
         inputSchema: {
-            mocks: z.array(ruleShape).optional().describe('Interception rules; omit/empty to clear.'),
+            // The rule fields each carry their own `.describe()` on `ruleShape`, but the params
+            // view reads only the top-level description of each entry, so those are flattened
+            // away before an agent sees them. Naming the shape here is what keeps the tool
+            // callable from its own description instead of by guessing and failing first.
+            mocks: z
+                .array(ruleShape)
+                .optional()
+                .describe('Interception rules, first match wins: { urlContains, method?, status?, body?, contentType?, delayMs?, abort? }. Omit or pass [] to clear.'),
             clear: z.boolean().optional().describe('Clear all active mocks (same as mocks: []).'),
             ...sessionIdShape,
         },

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

@@ -28,6 +28,12 @@ export interface ScrollFindResult {
      * help). false ⇒ stopped at the maxScrolls budget (more rows may exist further down).
      */
     exhausted: boolean;
+    /**
+     * Present only when informative: the document itself did not scroll (nothing scrollable), so the
+     * target is likely inside a list with its own scroll container. A genuine exhaustion — reaching
+     * the real end of a scrolled container — stays quiet.
+     */
+    note?: string;
 }
 /**
  * Reveal an element that a windowed/virtualized list has not mounted yet. Queries

package/dist/input/scroll-find.js

@@ -12,6 +12,21 @@ async function queryFirst(session, q) {
         return asRecord(elements[0]);
     return undefined;
 }
+/**
+ * A note attached to `{ found: false, exhausted: true }` only when the failure is
+ * actually informative: the document itself had nothing to scroll (scrolled:false with
+ * no explicit container), so the target is likely inside a list with its own scroll
+ * container. Reaching the genuine end of a scrolled container stays quiet.
+ */
+function exhaustNote(q, data) {
+    if (q.container !== undefined)
+        return {};
+    if (false !== data['scrolled'])
+        return {};
+    return {
+        note: "The document did not scroll — the target may be inside a list with its own scroll container. Pass that container's ref as `container`.",
+    };
+}
 /**
  * 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
@@ -39,7 +54,7 @@ export async function scrollToFind(session, q, opts = {}) {
         // Fall through to linear refinement from current position (already near the target).
         const data = asRecord(sr.result);
         if (true === data['atEnd'] || false === data['scrolled']) {
-            return { found: false, scrolls, exhausted: true };
+            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data) };
         }
     }
     for (let i = 0; i < max; i += 1) {
@@ -51,7 +66,7 @@ export async function scrollToFind(session, q, opts = {}) {
             return { found: true, element: hit, scrolls, exhausted: false };
         // Reached the bottom or the container would not move — no more rows to reveal.
         if (true === data['atEnd'] || false === data['scrolled']) {
-            return { found: false, scrolls, exhausted: true };
+            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data) };
         }
     }
     return { found: false, scrolls, exhausted: false }; // spent the budget; more may lie further down

package/dist/input/scroll-tools.js

@@ -52,6 +52,10 @@ export const SCROLL_TOOLS = [
             element: z.object({ ref: z.string(), role: z.string(), name: z.string() }).optional(),
             scrolls: z.number(),
             exhausted: z.boolean(),
+            note: z
+                .string()
+                .optional()
+                .describe('Present only when informative: the document itself did not scroll, so the target may be inside a list with its own scroll container — pass its ref as `container`.'),
         },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));

package/dist/journal/attach-journal.d.ts

@@ -15,8 +15,16 @@ interface JournalAttachDeps {
 }
 /**
  * Build the per-session journal attachment the bridge fires on session creation. Off when disabled;
- * silently skips a session whose id is not a safe path segment (never crashes the live session over a
+ * skips a session whose id is not a safe path segment (never crashes the live session over a
  * journaling concern). The recorder's clock is the session's own elapsed time.
+ *
+ * That skip used to be SILENT, which is the part that mattered. The id becomes a directory name, so
+ * one that is not a safe path segment cannot be journalled — but the session itself connects and
+ * drives perfectly well, so the only observable difference is that the durable causal record for it
+ * does not exist. Every query that reads back through the journal then returns nothing, and nothing
+ * anywhere says why. An app self-assigning an unusual id gets a quietly degraded session; a hostile
+ * one gets the same, which is why this is worth a line either way. Nothing escapes the directory —
+ * the guard holds, and that is exactly why the failure is invisible rather than loud.
  */
 export declare function makeJournalAttach(deps: JournalAttachDeps): (session: JournalTarget) => void;
 export {};