@reticlehq/init 3.2.0 → 3.4.0

package/dist/patch/astro-patch.js

@@ -1,66 +1,170 @@
 /**
- * Pure, conservative patchers for an Astro app: the config gets the token/root `define` and the
- * raised build target, one layout gets the dev-only connect `<script>`.
+ * Pure, conservative patchers for an Astro app: the config gets the raised build target and the
+ * watcher ignore, one layout gets the pairing token via frontmatter `<meta>` tags and a processed
+ * `<script>` that statically imports a local connect module.
  *
  * Astro was the last gated framework where `init` printed a correct recipe and applied none of it —
  * the only ⚠ left on a supported stack, and the user's first session was two hand-copied snippets
  * away. Astro is Vite-based but renders its own HTML, so the Vite plugin's injection never fires and
- * there is no entry module to wire: the connect has to live in a page or layout `<script>`, and the
- * token has to be inlined by the config because nothing else is in the page's path to inject it.
+ * there is no entry module to wire: the connect has to live in a page or layout.
+ *
+ * The token used to be inlined by `vite.define`. On Astro 7.2+ that substitution no longer reaches
+ * the client pipeline (#1008), so the identifier stays literal, `connect()` omits `token`, and the
+ * bridge refuses with "no pairing token on the page". The channel that does work is a `<meta>`: read
+ * the file in frontmatter and let a local module query `meta[name="reticle-pairing-token"]`. Reading
+ * per request also means a token written after the dev server started needs no restart. The SDK import
+ * lives in `src/components/ReticleDev.ts` so the page only ever statically imports a project module.
  *
  * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
  * Half-editing a build config is worse than a documented manual step.
  */
+import { posix } from 'node:path';
 import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
 import { PatchKind } from './patch-kind.js';
 import { UiLibrary } from '../detect/detect.js';
 import { registerCapabilitiesCall, sdkImport } from './snippets.js';
 import { patchViteOwningConfig } from './vite-owning-config.js';
-/** Present in a patched layout and in the printed recipe's script. */
+/**
+ * Local module `init` writes for Astro. A processed page `<script>` statically imports this file
+ * so Vite owns the SDK the same way it owns any other project module.
+ *
+ * `.ts`, not `.tsx`: the install-gate scaffold is `create-astro --template minimal`, which has no
+ * React integration. The example app uses the same static import in a processed page `<script>`.
+ */
+export const ASTRO_RETICLE_DEV_PATH = 'src/components/ReticleDev.ts';
+/**
+ * Dev-only Astro connect module. Static SDK import, token from frontmatter `<meta>` tags.
+ */
+export function astroReticleDevFile(port, projectId, uiLibrary = UiLibrary.REACT, testids = []) {
+    const sdk = sdkImport(uiLibrary);
+    const extra = port !== undefined && port !== RETICLE_DEFAULT_PORT ? `\n    url: '${bridgeWsUrl(port)}',` : '';
+    const id = projectId !== undefined && projectId.length > 0 ? `\n    projectId: '${projectId}',` : '';
+    return `import { reticle${sdk.usesInstall ? ', install' : ''}, registerCapabilities } from '${sdk.specifier}';
+
+/** Dev-only: connect Reticle. Imported from a processed page script so Vite owns the SDK graph. */
+export default function connectReticle() {
+  const token =
+    document.querySelector('meta[name="reticle-pairing-token"]')?.getAttribute('content') ?? '';
+  const root =
+    document.querySelector('meta[name="reticle-pairing-root"]')?.getAttribute('content') ?? '';
+  const url =
+    document.querySelector('meta[name="reticle-pairing-url"]')?.getAttribute('content') ?? '';
+  if (0 === token.length) {
+    console.warn(${JSON.stringify(ASTRO_MISSING_TOKEN_WARNING)});
+  }
+  ${sdk.usesInstall ? 'install();' : '// The sensor has no install(); that is the React adapter.'}
+  reticle.connect({${id}${extra}
+    ...(0 < token.length ? { token } : {}),
+    ...(0 < root.length ? { root } : {}),
+    ...(0 < url.length ? { url } : {}),
+  });
+${registerCapabilitiesCall(testids, '  ')}
+}
+`;
+}
+/** Present in a patched layout (and in an already-wired one that still has the old script). */
 const LAYOUT_MARKER = 'reticle.connect';
+const LAYOUT_MODULE_MARKER = 'connectReticle';
 const BODY_CLOSE = '</body>';
+const FRONTMATTER_FENCE = '---';
+/**
+ * Written into the Astro `vite:` block so a second init reports ALREADY. The Nuxt path uses
+ * `__RETICLE_TOKEN__` in `define` as its marker; Astro no longer writes that name into the config.
+ */
+export const ASTRO_VITE_OWNING_MARKER = 'reticle-vite-owning';
+/**
+ * The one runtime condition that guarantees a refused connect, said out loud on the page.
+ *
+ * Matching the Vite plugin's missing-token wording, because Astro never loads that plugin. The
+ * token is read at render time now, not at config load, so a reload is enough — the user does not
+ * have to restart the dev server.
+ */
+export const ASTRO_MISSING_TOKEN_WARNING = '[reticle] no pairing token was available when this page rendered, so the app will connect ' +
+    'and be refused — you will see NO SESSION even though the SDK loads and the socket opens. ' +
+    'The token is written by the Reticle daemon: start it (`reticle serve`, or let your agent start ' +
+    'it) and reload this page.';
 /**
  * Astro's half of the Vite-owning config patch: the call to extend, and the SDK to pre-bundle.
  *
  * `@reticlehq/react` and not the detected UI library: Astro hosts islands from any framework, but
  * `frameworkPackages` gives every Astro app the React kit (see FRAMEWORK_ADAPTERS), so that is the
  * package the connect script imports and the one Vite must pre-bundle.
+ *
+ * `defineToken: false` is the #1008 fix. `build.target`, `optimizeDeps.include` and the `.reticle/`
+ * watcher ignore stay — each has a measured reason and none of them is the defect.
  */
 const ASTRO_VITE_CONFIG = {
     defineCall: /defineConfig\s*\(\s*\{/,
     sdkSpecifier: sdkImport(UiLibrary.REACT).specifier,
+    defineToken: false,
+    alreadyMarker: ASTRO_VITE_OWNING_MARKER,
 };
-export function patchAstroConfig(source) {
-    return patchViteOwningConfig(source, ASTRO_VITE_CONFIG);
+export function patchAstroConfig(source, viteMajor = null) {
+    return patchViteOwningConfig(source, { ...ASTRO_VITE_CONFIG, viteMajor });
 }
-/** The dev-only connect that goes inside the layout's `<body>`. */
-function astroConnectScript(port, projectId, uiLibrary, testids) {
-    // Must match what `frameworkPackages` installed. Astro hosts islands from any framework, so an
-    // Astro app whose islands are Vue or Svelte gets the sensor, and a script importing the React
-    // adapter would load a package that is not in node_modules. See sdkImport.
-    const sdk = sdkImport(uiLibrary);
-    const url = port !== undefined && port !== RETICLE_DEFAULT_PORT
-        ? `\n          url: '${bridgeWsUrl(port)}',`
-        : '';
-    const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
-    return `    <script>
+/**
+ * Aliased imports so a layout that already pulled `readFileSync` from `node:fs` does not get a
+ * duplicate binding. The names are the already-marker for the frontmatter half.
+ */
+const FRONTMATTER_ADDITIONS = `import { readFileSync as reticleReadFileSync } from 'node:fs';
+import { homedir as reticleHomedir } from 'node:os';
+import { join as reticleJoin } from 'node:path';
+const pairingToken = (() => {
+  if (!import.meta.env.DEV) return '';
+  const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || reticleJoin(reticleHomedir(), '.reticle');
+  try { return reticleReadFileSync(reticleJoin(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+})();
+const pairingRoot = import.meta.env.DEV ? process.cwd() : '';
+`;
+/**
+ * Import path from a layout/page to the generated connect module, always relative and posix.
+ *
+ * `src/layouts/Layout.astro` and `src/pages/index.astro` both resolve to `../components/ReticleDev`.
+ */
+export function astroReticleDevImport(layoutPath) {
+    const fromDir = posix.dirname(layoutPath.replaceAll('\\', '/'));
+    const to = ASTRO_RETICLE_DEV_PATH.replace(/\.ts$/, '');
+    let rel = posix.relative(fromDir, to);
+    if (!rel.startsWith('.'))
+        rel = `./${rel}`;
+    return rel;
+}
+/** Meta tags plus a processed script that statically imports the local connect module. */
+function astroConnectMarkup(moduleSpecifier) {
+    return `    <meta name="reticle-pairing-token" content={pairingToken} />
+    <meta name="reticle-pairing-root" content={pairingRoot} />
+    <script>
+      import connectReticle from '${moduleSpecifier}';
       if (import.meta.env.DEV) {
-        const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-        const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
-        const { reticle${sdk.usesInstall ? ', install' : ''}, registerCapabilities } = await import('${sdk.specifier}');
-        ${sdk.usesInstall ? 'install();' : '// The sensor has no install(); that is the React adapter.'}
-        reticle.connect({${id}${url}
-          ...(token.length > 0 ? { token } : {}),
-          ...(root.length > 0 ? { root } : {}),
-        });
-${registerCapabilitiesCall(testids, '        ')}
+        connectReticle();
       }
     </script>
 `;
 }
-export function patchAstroLayout(source, port, projectId, uiLibrary = UiLibrary.REACT, testids = []) {
-    if (source.includes(LAYOUT_MARKER))
+/**
+ * Marker for the frontmatter half. It must be a name ONLY the frontmatter writes: this ran against
+ * `pairingToken`, which the meta markup inserted one step earlier already contains, so the guard
+ * always tripped and the token read was never added — leaving every scaffolded page throwing
+ * `ReferenceError: pairingToken is not defined`.
+ */
+const FRONTMATTER_MARKER = 'reticleReadFileSync';
+function withFrontmatter(source) {
+    if (source.includes(FRONTMATTER_MARKER))
+        return source;
+    if (source.startsWith(FRONTMATTER_FENCE)) {
+        const closeAt = source.indexOf(`\n${FRONTMATTER_FENCE}`, FRONTMATTER_FENCE.length);
+        if (closeAt < 0)
+            return null;
+        const inner = source.slice(FRONTMATTER_FENCE.length + 1, closeAt);
+        const padded = inner.endsWith('\n') ? inner : `${inner}\n`;
+        return `${FRONTMATTER_FENCE}\n${padded}${FRONTMATTER_ADDITIONS}${source.slice(closeAt + 1)}`;
+    }
+    return `${FRONTMATTER_FENCE}\n${FRONTMATTER_ADDITIONS}${FRONTMATTER_FENCE}\n${source}`;
+}
+export function patchAstroLayout(source, layoutPath = 'src/layouts/Layout.astro') {
+    if (source.includes(LAYOUT_MARKER) || source.includes(LAYOUT_MODULE_MARKER)) {
         return { kind: PatchKind.ALREADY };
+    }
     const at = source.lastIndexOf(BODY_CLOSE);
     if (at < 0) {
         return {
@@ -68,28 +172,32 @@ export function patchAstroLayout(source, port, projectId, uiLibrary = UiLibrary.
             reason: "couldn't find a `</body>` to place the connect script before",
         };
     }
-    return {
-        kind: PatchKind.APPLY,
-        code: `${source.slice(0, at)}${astroConnectScript(port, projectId, uiLibrary, testids)}${source.slice(at)}`,
-    };
+    const withScripts = `${source.slice(0, at)}${astroConnectMarkup(astroReticleDevImport(layoutPath))}${source.slice(at)}`;
+    const withFence = withFrontmatter(withScripts);
+    if (null === withFence) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: "couldn't find a closing frontmatter fence to place the pairing-token read in",
+        };
+    }
+    return { kind: PatchKind.APPLY, code: withFence };
 }
 /** Where Astro keeps ambient types — `create-astro` ships this file. */
 export const ASTRO_ENV_DTS_PATH = 'src/env.d.ts';
 /**
- * The declarations `astro check` needs for the Vite `define` names (#677).
- *
- * Matching SvelteKit's `hooks.client.ts` typing: `string | undefined`, because the define can be
- * absent when the pairing token file is missing.
+ * The declarations `astro check` needs for the window names the inline script writes (#677, #1008).
  */
-export const ASTRO_ENV_DTS_DECLARES = 'declare const __RETICLE_TOKEN__: string | undefined;\n' +
-    'declare const __RETICLE_ROOT__: string | undefined;\n';
-/** Present once either declare is in the file — both are written together. */
+export const ASTRO_ENV_DTS_DECLARES = 'interface Window {\n' +
+    '  __RETICLE_TOKEN__?: string;\n' +
+    '  __RETICLE_ROOT__?: string;\n' +
+    '}\n';
+/** Present once either name is in the file — both are written together. */
 const ENV_DTS_MARKER = '__RETICLE_TOKEN__';
 /**
- * Append the Vite-define ambient declarations to `src/env.d.ts`, or create the file.
+ * Append the window ambient declarations to `src/env.d.ts`, or create the file.
  *
- * Without this, `create-astro`'s default `"astro check && astro build"` fails with four
- * `ts(2304) Cannot find name '__RETICLE_TOKEN__'` errors after a clean init (#677).
+ * Without this, `create-astro`'s default `"astro check && astro build"` fails with
+ * `ts(2339) Property '__RETICLE_TOKEN__' does not exist on type 'Window'` after a clean init.
  */
 export function patchAstroEnvDts(existing) {
     if (null !== existing && existing.includes(ENV_DTS_MARKER)) {

package/dist/patch/cra.d.ts

@@ -21,8 +21,6 @@ export declare const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
  * makes the first compile after init fail while the plan still reports `[✓]`.
  */
 export declare function craDevModulePath(typescript: boolean): string;
-/** TypeScript default path — prefer `craDevModulePath` when the project's language is known. */
-export declare const CRA_DEV_MODULE_PATH: string;
 export declare const CRA_ENV_PATH = ".env.development.local";
 export declare const TOKEN_VAR = "REACT_APP_RETICLE_TOKEN";
 /**

package/dist/patch/cra.js

@@ -26,8 +26,6 @@ export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
 export function craDevModulePath(typescript) {
     return typescript ? 'src/reticle-dev.ts' : 'src/reticle-dev.js';
 }
-/** TypeScript default path — prefer `craDevModulePath` when the project's language is known. */
-export const CRA_DEV_MODULE_PATH = craDevModulePath(true);
 export const CRA_ENV_PATH = '.env.development.local';
 export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
 /**

package/dist/patch/electron-patch.d.ts

@@ -5,7 +5,16 @@
  * Preload is mechanical — prepend one line — so it is APPLY. Main is only APPLY when the file
  * constructs exactly one BrowserWindow as `const <name> = new BrowserWindow(`; anything else
  * (zero, several, a factory) is MANUAL carrying the doctor's existing fix text, not a guess.
+ *
+ * BOTH ARE DEV-ONLY, as the adapter's README says they must be. They used to be written unguarded
+ * — a static import in preload, a static import and call in main — so `electron-vite build` and
+ * `electron-forge package` bundled the IPC shim (which patches `ipcRenderer.invoke` and exposes
+ * `__reticleIpc`) and the screenshot IPC handler into the shipped app. Each is now behind a guard
+ * the bundler replaces at build time, so a production build folds the branch away and carries
+ * neither. Measured on electron-vite: absent from a production build, present in
+ * `--mode development`, which is the build the renderer's `desktop: true` also instruments.
+ * A line an older `init` wrote is rewritten in place on a re-run.
  */
 import { type SourcePatch } from './patch-kind.js';
-export declare function patchElectronPreload(source: string, path: string): SourcePatch;
+export declare function patchElectronPreload(source: string, path: string, viteTypes?: boolean): SourcePatch;
 export declare function patchElectronMain(source: string, path?: string): SourcePatch;

package/dist/patch/electron-patch.js

@@ -5,48 +5,97 @@
  * Preload is mechanical — prepend one line — so it is APPLY. Main is only APPLY when the file
  * constructs exactly one BrowserWindow as `const <name> = new BrowserWindow(`; anything else
  * (zero, several, a factory) is MANUAL carrying the doctor's existing fix text, not a guess.
+ *
+ * BOTH ARE DEV-ONLY, as the adapter's README says they must be. They used to be written unguarded
+ * — a static import in preload, a static import and call in main — so `electron-vite build` and
+ * `electron-forge package` bundled the IPC shim (which patches `ipcRenderer.invoke` and exposes
+ * `__reticleIpc`) and the screenshot IPC handler into the shipped app. Each is now behind a guard
+ * the bundler replaces at build time, so a production build folds the branch away and carries
+ * neither. Measured on electron-vite: absent from a production build, present in
+ * `--mode development`, which is the build the renderer's `desktop: true` also instruments.
+ * A line an older `init` wrote is rewritten in place on a re-run.
  */
 import { matchingParenEnd } from './brace-scan.js';
 import { CAPTURE_REQUIRE, ELECTRON_CAPTURE_FIX, PRELOAD_REQUIRE, } from '../diagnose/desktop-doctor.js';
 import { PatchKind } from './patch-kind.js';
 const ESM_PRELOAD_EXT = /\.(?:ts|mts|mjs)$/i;
 const WINDOW_DECL = /const\s+(\w+)\s*=\s*new\s+BrowserWindow\s*\(/g;
-const IMPORT_LINE = /^import\s.+from\s+['"][^'"]+['"];?\s*$/gm;
-const REQUIRE_LINE = /^(?:const|let|var)\s+.+=\s+require\s*\(/gm;
+/** Replaced by Vite in every bundled main and preload, so a production build folds it to false. */
+const BUILD_MODE_GUARD = "import.meta.env.MODE !== 'production'";
+/**
+ * Forge's own dev-server define (`MAIN_WINDOW_VITE_DEV_SERVER_URL` in its template): a URL under
+ * `electron-forge start`, undefined in a package, and declared by the template — so it folds AND
+ * typechecks, where Forge's `tsconfig` has no types for `import.meta.env`.
+ */
+const FORGE_DEV_SERVER_DEFINE = /\b([A-Z][A-Z0-9_]*_VITE_DEV_SERVER_URL)\b/;
+/** An unbundled CommonJS main has nothing to fold, so it asks at runtime. */
+const PACKAGED_GUARD = "!require('electron').app.isPackaged";
+/** The unguarded lines an older `init` wrote, rewritten in place on a re-run. */
+const LEGACY_PRELOAD_IMPORT = new RegExp(`^import '${PRELOAD_REQUIRE}'\\n`, 'm');
+const LEGACY_MAIN_IMPORT = new RegExp(`^(?:import \\{ installReticleCapture \\} from '${CAPTURE_REQUIRE}'|const \\{ installReticleCapture \\} = require\\('${CAPTURE_REQUIRE}'\\);)\\n`, 'm');
+const LEGACY_MAIN_CALL = /^([ \t]*)installReticleCapture\((\w+)\)[ \t]*;?[ \t]*$/m;
 function isEsmPath(path) {
     return ESM_PRELOAD_EXT.test(path);
 }
-function preloadLine(path) {
-    return isEsmPath(path) ? `import '${PRELOAD_REQUIRE}'\n` : `require('${PRELOAD_REQUIRE}');\n`;
+/**
+ * The shim line, first in the file.
+ *
+ * A DYNAMIC import behind the build mode, for a bundled preload. Not a `require`: the electron-vite
+ * template lints with `no-require-imports`, and a clean install must not fail the project's own lint.
+ * Not the static import either, which no guard can remove. The cost is that the shim installs a
+ * microtask after the preload body runs rather than before it — still before the page's own
+ * scripts, and every exposed API that calls `ipcRenderer.invoke` at call time (electron-toolkit's
+ * included) is observed; one that captured the function itself (`invoke: ipcRenderer.invoke`) is
+ * not. Verified end to end on electron-vite: IPC observed and screenshots saved in dev, and no
+ * Reticle code in a production build.
+ *
+ * `viteTypes` is for Electron Forge, whose preload is SANDBOXED by Electron's default and whose
+ * tsconfig has no `import.meta.env` types. The same guarded line works there because Forge builds its
+ * preload with `codeSplitting: false` and the real build mode: the dynamic import is inlined into the
+ * one file a sandbox can load under `electron-forge start`, and folds away under `package`. Measured
+ * on a scaffolded Forge 8 app — Forge used to get the static import instead, which no guard removes,
+ * so the packaged app shipped the shim. The reference line supplies the types, so `tsc` stays green.
+ */
+const VITE_CLIENT_TYPES = '/// <reference types="vite/client" />\n';
+function preloadLine(path, viteTypes) {
+    if (!isEsmPath(path))
+        return `require('${PRELOAD_REQUIRE}');\n`;
+    return ((viteTypes ? VITE_CLIENT_TYPES : '') +
+        `if (${BUILD_MODE_GUARD}) {\n` +
+        `  // Reticle IPC observation, dev only — written by \`reticle init\`. A production build drops it.\n` +
+        `  void import('${PRELOAD_REQUIRE}').catch(() => undefined)\n` +
+        `}\n`);
 }
-export function patchElectronPreload(source, path) {
+export function patchElectronPreload(source, path, viteTypes = false) {
+    if (isEsmPath(path) && LEGACY_PRELOAD_IMPORT.test(source)) {
+        return {
+            kind: PatchKind.APPLY,
+            code: `${preloadLine(path, viteTypes)}${source.replace(LEGACY_PRELOAD_IMPORT, '')}`,
+        };
+    }
     if (source.includes(PRELOAD_REQUIRE)) {
         return { kind: PatchKind.ALREADY };
     }
-    return { kind: PatchKind.APPLY, code: `${preloadLine(path)}${source}` };
+    return { kind: PatchKind.APPLY, code: `${preloadLine(path, viteTypes)}${source}` };
 }
-function insertMainImport(source, path) {
-    if (source.includes(CAPTURE_REQUIRE))
-        return source;
-    if (isEsmPath(path)) {
-        const line = `import { installReticleCapture } from '${CAPTURE_REQUIRE}'`;
-        const matches = [...source.matchAll(IMPORT_LINE)];
-        const last = matches[matches.length - 1];
-        if (last?.index === undefined)
-            return `${line}\n${source}`;
-        const end = last.index + last[0].length;
-        return `${source.slice(0, end)}\n${line}${source.slice(end)}`;
+/** The guarded capture call for this main file. Nothing to import at the top: it loads itself. */
+function captureCall(source, path, windowName) {
+    if (!isEsmPath(path)) {
+        return `if (${PACKAGED_GUARD}) require('${CAPTURE_REQUIRE}').installReticleCapture(${windowName})`;
     }
-    const line = `const { installReticleCapture } = require('${CAPTURE_REQUIRE}');`;
-    const matches = [...source.matchAll(REQUIRE_LINE)];
-    const last = matches[matches.length - 1];
-    if (last?.index === undefined)
-        return `${line}\n${source}`;
-    const endOfLine = source.indexOf('\n', last.index);
-    const end = endOfLine < 0 ? source.length : endOfLine;
-    return `${source.slice(0, end)}\n${line}${source.slice(end)}`;
+    const guard = FORGE_DEV_SERVER_DEFINE.exec(source)?.[1] ?? BUILD_MODE_GUARD;
+    return `if (${guard}) void import('${CAPTURE_REQUIRE}').then(({ installReticleCapture }) => installReticleCapture(${windowName}))`;
 }
 export function patchElectronMain(source, path = 'electron/main.cjs') {
+    const legacyCall = LEGACY_MAIN_CALL.exec(source);
+    if (LEGACY_MAIN_IMPORT.test(source) && legacyCall?.[2] !== undefined) {
+        const withoutImport = source.replace(LEGACY_MAIN_IMPORT, '');
+        const indent = legacyCall[1] ?? '';
+        return {
+            kind: PatchKind.APPLY,
+            code: withoutImport.replace(LEGACY_MAIN_CALL, `${indent}${captureCall(withoutImport, path, legacyCall[2])}`),
+        };
+    }
     if (source.includes(CAPTURE_REQUIRE)) {
         return { kind: PatchKind.ALREADY };
     }
@@ -65,6 +114,9 @@ export function patchElectronMain(source, path = 'electron/main.cjs') {
         insertAt += 1;
     const indentMatch = /^[ \t]*/.exec(source.slice(source.lastIndexOf('\n', matches[0].index) + 1));
     const indent = indentMatch?.[0] ?? '  ';
-    const withCall = `${source.slice(0, insertAt)}\n${indent}installReticleCapture(${name})${source.slice(insertAt)}`;
-    return { kind: PatchKind.APPLY, code: insertMainImport(withCall, path) };
+    const call = captureCall(source, path, name);
+    return {
+        kind: PatchKind.APPLY,
+        code: `${source.slice(0, insertAt)}\n${indent}${call}${source.slice(insertAt)}`,
+    };
 }

package/dist/patch/electron-vite-patch.js

@@ -19,7 +19,7 @@ const RENDERER_KEY = /renderer\s*:\s*/;
 const NO_RENDERER_REASON = "couldn't find a `renderer` key to extend";
 const RENDERER_NOT_LITERAL_REASON = 'this config sets `renderer:` to something other than an object literal — merging into it is your call, not a text edit Reticle should make';
 const WRONG_BLOCK_REASON = 'reticle() is in this file but not in the `renderer` block — the plugin belongs where there is a document, and leaving it in `main` or `preload` would report success for an app that cannot connect';
-const MISSING_DESKTOP_REASON = 'reticle() is already in the `renderer` block but without `desktop: true` — a packaged renderer is a production build with no dev server, so the plugin is dropped from `vite build` and the shipped app has no connect()';
+const MISSING_DESKTOP_REASON = 'reticle() is already in the `renderer` block but without `desktop: true` — a packaged renderer has no dev server and reports production, so without it the SDK refuses to start there and the packaged app never connects';
 function reticlePluginCall(port) {
     const options = [
         'desktop: true',

package/dist/patch/nuxt-patch.d.ts

@@ -15,4 +15,4 @@
 import type { SourcePatch } from './patch-kind.js';
 /** The config filenames Nuxt itself accepts, in the order `init` should prefer them. */
 export declare const NUXT_CONFIG_CANDIDATES: string[];
-export declare function patchNuxtConfig(source: string): SourcePatch;
+export declare function patchNuxtConfig(source: string, viteMajor?: number | null): SourcePatch;

package/dist/patch/nuxt-patch.js

@@ -28,6 +28,6 @@ const NUXT_VITE_CONFIG = {
     defineCall: /defineNuxtConfig\s*\(\s*\{/,
     sdkSpecifier: sdkImport(UiLibrary.VUE).specifier,
 };
-export function patchNuxtConfig(source) {
-    return patchViteOwningConfig(source, NUXT_VITE_CONFIG);
+export function patchNuxtConfig(source, viteMajor = null) {
+    return patchViteOwningConfig(source, { ...NUXT_VITE_CONFIG, viteMajor });
 }

package/dist/patch/nuxt-snippets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The plugin directory Nuxt actually scans, which is not the same on 3 and 4.
+ *
+ * Nuxt 4's default `srcDir` is `app/`, so plugins live in `app/plugins/`. Nuxt 3's is the project
+ * root, so they live in `plugins/`. Writing to the wrong one is the silent failure this whole change
+ * exists to remove: the file is on disk, `init` reports it green, Nuxt never scans that directory,
+ * and no plugin is ever registered. Keyed on whether the app HAS an `app/` directory, which is the
+ * same signal Nuxt itself uses to pick its srcDir.
+ */
+export declare function nuxtPluginPath(hasAppDir: boolean): string;
+/**
+ * The dev-only Nuxt client plugin `init` writes.
+ *
+ * Every trap in it is one somebody actually hit. `import.meta.dev` rather than a hostname check: the
+ * reported failure was a snippet guarded on `window.location.hostname === 'localhost'`, which is
+ * false on any hosts-file alias or LAN address and throws during SSR, so the connect never ran with
+ * no error and no log line. `.client.ts` rather than an SSR guard, because that suffix is what keeps
+ * this out of the server bundle. `@reticlehq/browser` rather than the React kit, because installing
+ * a package named `@reticlehq/react` into a Vue codebase is the single thing most likely to make
+ * somebody abandon the setup.
+ *
+ * The token is inlined by `nuxt.config`'s `vite.define` (see nuxt-patch.ts). The bridge requires it
+ * even on localhost, and nothing in a browser can read the file it lives in.
+ */
+export declare function nuxtPluginFile(port: number | undefined, projectId?: string, testids?: readonly string[]): string;
+/**
+ * Said as its own NOTICE beside the write, not inside it: a running dev server does not pick up a
+ * new plugin, and off localhost the connect needs two more arguments.
+ *
+ * A ✓ line is one SKILL.md tells the reader to skip, so a caveat carried on the ✓ is a caveat nobody
+ * reads — and both of these end with an app that boots, looks correct and never pairs.
+ */
+export declare const NUXT_PLUGIN_NOTICE: string;
+/**
+ * The Nuxt recipe, written out in full because each trap in it is one a Nuxt 4 app actually hit:
+ * a Vue codebase classified as `html` and handed `@reticlehq/react`, a connect guarded on
+ * `window.location.hostname === 'localhost'` (false on any hosts-file alias, and `window` does not
+ * exist during SSR), and a running dev server that never picked up the new plugin.
+ *
+ * So: `import.meta.dev` instead of a hostname check, `.client.ts` instead of an SSR guard, the
+ * framework-neutral sensor instead of the React kit, the non-localhost flag named up front, and the
+ * restart said out loud.
+ */
+export declare function nuxtManual(port: number | undefined, projectId?: string): string;

package/dist/patch/nuxt-snippets.js

@@ -0,0 +1,135 @@
+/**
+ * The Nuxt connect plugin `reticle init` writes, split out of snippets.ts (which crossed the
+ * 1000-line cap): its path, the plugin file itself, the notice, and the manual fallback.
+ */
+import { ReticleDir } from '@reticlehq/core';
+import { connectArg, registerCapabilitiesCall, STATE_DOCS_URL } from './snippets.js';
+/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
+const NUXT_PLUGIN_PATH = 'app/plugins/reticle.client.ts';
+/**
+ * The plugin directory Nuxt actually scans, which is not the same on 3 and 4.
+ *
+ * Nuxt 4's default `srcDir` is `app/`, so plugins live in `app/plugins/`. Nuxt 3's is the project
+ * root, so they live in `plugins/`. Writing to the wrong one is the silent failure this whole change
+ * exists to remove: the file is on disk, `init` reports it green, Nuxt never scans that directory,
+ * and no plugin is ever registered. Keyed on whether the app HAS an `app/` directory, which is the
+ * same signal Nuxt itself uses to pick its srcDir.
+ */
+export function nuxtPluginPath(hasAppDir) {
+    return hasAppDir ? NUXT_PLUGIN_PATH : 'plugins/reticle.client.ts';
+}
+/**
+ * The dev-only Nuxt client plugin `init` writes.
+ *
+ * Every trap in it is one somebody actually hit. `import.meta.dev` rather than a hostname check: the
+ * reported failure was a snippet guarded on `window.location.hostname === 'localhost'`, which is
+ * false on any hosts-file alias or LAN address and throws during SSR, so the connect never ran with
+ * no error and no log line. `.client.ts` rather than an SSR guard, because that suffix is what keeps
+ * this out of the server bundle. `@reticlehq/browser` rather than the React kit, because installing
+ * a package named `@reticlehq/react` into a Vue codebase is the single thing most likely to make
+ * somebody abandon the setup.
+ *
+ * The token is inlined by `nuxt.config`'s `vite.define` (see nuxt-patch.ts). The bridge requires it
+ * even on localhost, and nothing in a browser can read the file it lives in.
+ */
+export function nuxtPluginFile(port, projectId, testids = []) {
+    const base = connectArg(port, projectId);
+    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
+    return `// Dev-only: connect Reticle from a Nuxt client plugin. Nuxt owns its own Vite instance and
+// renders its own HTML, so the Vite plugin's index.html injection never fires — a .client plugin is
+// the path that can register a session at all.
+export default defineNuxtPlugin(() => {
+  // import.meta.dev is resolved at BUILD time, so it does not care what hostname you develop on.
+  // Do NOT guard on window.location.hostname === 'localhost': that is false on any hosts-file alias
+  // or LAN address, and window does not exist during SSR.
+  if (!import.meta.dev) return;
+  void import('@reticlehq/browser').then(({ reticle, registerCapabilities }) => {
+    // Both inlined by nuxt.config's vite.define, which \`reticle init\` wrote. The bridge refuses a
+    // connect with no token even on localhost; the root makes source paths repo-relative.
+    const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+    const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+    reticle.connect({
+      ${fields}...(token.length > 0 ? { token } : {}),
+      ...(root.length > 0 ? { root } : {}),
+    });
+
+    // What the agent can drive without guessing. Add a store here too — for Pinia,
+    // registerStore('<key>', piniaStore(<useYourStore>())) — and the agent can check what the app
+    // BELIEVES, not just what it rendered. See ${STATE_DOCS_URL}
+${registerCapabilitiesCall(testids, '    ')}
+  });
+});
+
+declare const __RETICLE_TOKEN__: string | undefined;
+declare const __RETICLE_ROOT__: string | undefined;
+`;
+}
+/**
+ * Said as its own NOTICE beside the write, not inside it: a running dev server does not pick up a
+ * new plugin, and off localhost the connect needs two more arguments.
+ *
+ * A ✓ line is one SKILL.md tells the reader to skip, so a caveat carried on the ✓ is a caveat nobody
+ * reads — and both of these end with an app that boots, looks correct and never pairs.
+ */
+export const NUXT_PLUGIN_NOTICE = 'Restart the dev server: one that is already running does not pick up a new plugin — it will not ' +
+    'appear in .nuxt/plugins/client.mjs and the app comes up with no SDK at all. And 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 the token from ~/.reticle/pairing-token. ' +
+    'The flag alone is NOT sufficient off localhost.';
+/**
+ * The Nuxt recipe, written out in full because each trap in it is one a Nuxt 4 app actually hit:
+ * a Vue codebase classified as `html` and handed `@reticlehq/react`, a connect guarded on
+ * `window.location.hostname === 'localhost'` (false on any hosts-file alias, and `window` does not
+ * exist during SSR), and a running dev server that never picked up the new plugin.
+ *
+ * So: `import.meta.dev` instead of a hostname check, `.client.ts` instead of an SSR guard, the
+ * framework-neutral sensor instead of the React kit, the non-localhost flag named up front, and the
+ * restart said out loud.
+ */
+export function nuxtManual(port, projectId) {
+    const base = connectArg(port, projectId);
+    const fields = '' === base ? '' : base.slice(1, -1).trim();
+    const connect = '' === fields ? 'reticle.connect()' : `reticle.connect({ ${fields} })`;
+    return `Nuxt owns its own Vite instance and renders its own HTML, so there is no vite.config to patch
+and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which is Nuxt's own idiom:
+
+1. Create ${NUXT_PLUGIN_PATH}:
+
+     export default defineNuxtPlugin(() => {
+       // import.meta.dev is the correct guard: it is resolved at build time, so it does not care
+       // what hostname you develop on. Do NOT guard on window.location.hostname === 'localhost' —
+       // that is false on any hosts-file alias or LAN address, and window does not exist in SSR.
+       if (!import.meta.dev) return
+       void import('@reticlehq/browser').then(({ reticle }) => {
+         ${connect}
+       })
+     })
+
+   The .client.ts suffix is load-bearing: it is what keeps this out of the server bundle.
+
+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), 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
+thing the React adapter adds. The install gate scaffolds a Nuxt app on every release and requires a session, so this wiring
+is proven; if something does not work, please open an issue.`;
+}