@reticlehq/init 3.3.0 → 3.5.0

package/dist/patch/angular.js

@@ -0,0 +1,216 @@
+/**
+ * Angular CLI: a dev-only connect in the browser entry, and a way for the pairing token to reach it.
+ *
+ * The connect is the part proven by hand on Angular 22, with and without SSR: a dynamic
+ * `import('@reticlehq/browser')` guarded on `ngDevMode` (see DEV_GUARD for why not `isDevMode()`),
+ * which the production build folds to `false` and drops together with the chunk it would load.
+ *
+ * The token is the hard part, and why this is not one line. The bridge refuses a hello without the
+ * machine's pairing token even on localhost, and every other stack inlines it from Node at build
+ * time — the Vite plugin's `define`, Next's `NEXT_PUBLIC_*`, CRA's gitignored `.env.development.local`.
+ * The Angular CLI has no config file that runs code, so each of those has a failure here, all
+ * measured on a scaffolded Angular 21 app before this was written:
+ *
+ * - A literal in `angular.json` (`define`, `fileReplacements`) commits a per-machine secret.
+ * - A gitignored module imported from `main.ts` is bundled by `ng build` too: with the file present
+ *   the production output held a lazy chunk carrying the token behind `isDevMode()`, which the
+ *   build cannot fold — and a token must not depend on a guard being written exactly right.
+ * - Making that module a dev-only `fileReplacements` target breaks `ng serve` for every teammate
+ *   who has not run `init` ("path in file replacements does not exist").
+ *
+ * What is left is the serve target, which `ng build` never reads. Its `proxyConfig` is a JavaScript
+ * module that `ng serve` loads in Node, so `reticle.proxy.mjs` reads `~/.reticle/pairing-token` at
+ * request time — the same file the Vite and Next plugins read — and answers one same-origin route
+ * with it. The token is never written into the project, and a production build has no route to it.
+ */
+import { connectArg } from './snippets.js';
+import { PatchKind } from './patch-kind.js';
+/** The generated dev-server module, beside `angular.json`. */
+export const ANGULAR_PROXY_PATH = 'reticle.proxy.mjs';
+/** The one route that module answers, fetched by the entry's dev-only connect. */
+export const ANGULAR_TOKEN_PATH = '/__reticle/pairing-token';
+/** What an Angular CLI app's browser entry is when `angular.json` does not say. */
+export const ANGULAR_DEFAULT_ENTRY = 'src/main.ts';
+const SENSOR = '@reticlehq/browser';
+const DEV_SERVER_BUILDER = /:dev-server$/;
+const UNPARSEABLE_REASON = 'angular.json is not plain JSON, so it is not safe to rewrite by hand';
+const NO_SERVE_TARGET_REASON = 'no project in angular.json has a `serve` target on a dev-server builder, so there is nowhere ' +
+    'for `ng serve` to pick up the token route';
+const SEVERAL_APPS_REASON = 'angular.json has several projects with a `serve` target, and which one is the app is not ours ' +
+    'to guess';
+function parseWorkspace(source) {
+    try {
+        const parsed = JSON.parse(source);
+        if ('object' !== typeof parsed || null === parsed)
+            return undefined;
+        const root = parsed;
+        const projects = root['projects'];
+        if ('object' !== typeof projects || null === projects)
+            return undefined;
+        return { root, projects: projects };
+    }
+    catch {
+        return undefined;
+    }
+}
+function targetsOf(project) {
+    return project.architect ?? project.targets ?? {};
+}
+/** The projects `ng serve` can serve — the only ones with a page to connect. */
+function servedProjects(projects) {
+    return Object.values(projects).filter((p) => DEV_SERVER_BUILDER.test(targetsOf(p)['serve']?.builder ?? ''));
+}
+/**
+ * The browser entry `angular.json` names — `browser` on the application builder (v17+), `main` on
+ * the webpack one — or the CLI's default when it cannot be read.
+ */
+export function angularEntry(source) {
+    const workspace = null === source ? undefined : parseWorkspace(source);
+    const [only, ...rest] = workspace === undefined ? [] : servedProjects(workspace.projects);
+    if (only === undefined || rest.length > 0)
+        return ANGULAR_DEFAULT_ENTRY;
+    const options = targetsOf(only)['build']?.options ?? {};
+    const named = options['browser'] ?? options['main'];
+    return 'string' === typeof named && named.length > 0 ? named : ANGULAR_DEFAULT_ENTRY;
+}
+/**
+ * Point the one app's serve target at `reticle.proxy.mjs`.
+ *
+ * An existing `proxyConfig` is the app's, and is never replaced: the step goes MANUAL naming the
+ * entry to add to it. The file is rewritten through `JSON.stringify` with the CLI's own two-space
+ * indent, which is how `ng new` writes it, so the diff is the one key.
+ */
+export function patchAngularJson(source) {
+    const workspace = parseWorkspace(source);
+    if (workspace === undefined)
+        return { kind: PatchKind.MANUAL, reason: UNPARSEABLE_REASON };
+    const served = servedProjects(workspace.projects);
+    const [only, ...rest] = served;
+    if (only === undefined)
+        return { kind: PatchKind.MANUAL, reason: NO_SERVE_TARGET_REASON };
+    if (rest.length > 0)
+        return { kind: PatchKind.MANUAL, reason: SEVERAL_APPS_REASON };
+    const serve = targetsOf(only)['serve'];
+    if (serve === undefined)
+        return { kind: PatchKind.MANUAL, reason: NO_SERVE_TARGET_REASON };
+    const existing = serve.options?.['proxyConfig'];
+    if (ANGULAR_PROXY_PATH === existing)
+        return { kind: PatchKind.ALREADY };
+    if (existing !== undefined) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: `the serve target already uses ${JSON.stringify(existing)} as its proxyConfig, and it is yours — ` +
+                `add the \`${ANGULAR_TOKEN_PATH}\` entry from ${ANGULAR_PROXY_PATH} to it`,
+        };
+    }
+    serve.options = { ...serve.options, proxyConfig: ANGULAR_PROXY_PATH };
+    return { kind: PatchKind.APPLY, code: `${JSON.stringify(workspace.root, null, 2)}\n` };
+}
+/**
+ * The dev-server module. Plain ESM, no dependencies, because it runs in the app's `ng serve`.
+ *
+ * Two refusals, both about who may read a token: a request that did not come over loopback (an
+ * `ng serve --host 0.0.0.0` on a shared network), and a browser request from another origin — a
+ * different localhost app — which `Sec-Fetch-Site` names on every current browser.
+ *
+ * `bypass` answers the request itself and returns `false`, so the dummy `target` is never dialled.
+ * ponytail: relies on the Vite-based dev server (Angular 17+) ignoring the 404 it sets after the
+ * response has already ended; the older webpack dev server calls `next()` instead, and if it ever
+ * matters there the upgrade is a `configure` hook instead of `bypass`.
+ */
+export function angularProxyFile() {
+    return `// Written by \`reticle init\`. Read by \`ng serve\` only — \`ng build\` never loads a proxy config.
+//
+// Hands the page this machine's Reticle pairing token, read at request time from the file the
+// Reticle daemon keeps (~/.reticle/pairing-token). The token is per-machine and never written into
+// this project, so nothing here needs to be kept out of version control.
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+function pairingToken() {
+  const dir = process.env.RETICLE_PAIRING_TOKEN_DIR || join(homedir(), '.reticle');
+  try {
+    return readFileSync(join(dir, 'pairing-token'), 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+export default {
+  '${ANGULAR_TOKEN_PATH}': {
+    target: 'http://127.0.0.1:9',
+    bypass(req, res) {
+      const site = req.headers['sec-fetch-site'];
+      const allowed =
+        LOOPBACK.has(req.socket.remoteAddress ?? '') && (site === undefined || site === 'same-origin');
+      res.writeHead(allowed ? 200 : 403, { 'content-type': 'text/plain', 'cache-control': 'no-store' });
+      res.end(allowed ? pairingToken() : '');
+      return false;
+    },
+  },
+};
+`;
+}
+/** Everything `connect()` is called with, as the literal's inner fields — `url` only off 4400. */
+function connectFields(port, projectId) {
+    const literal = connectArg(port, projectId);
+    return literal.length > 0 ? `${literal.slice(1, -1).trim()}, ` : '';
+}
+/**
+ * The guard the connect sits under: Angular's own `ngDevMode` global, not `isDevMode()`.
+ *
+ * `isDevMode()` is a runtime call, so `ng build` cannot fold it: the production bundle shipped the
+ * whole connect — the bridge URL included — plus ~300KB of lazy Reticle chunks that nothing
+ * would ever load. The Angular CLI defines `ngDevMode` to `false` in a production build, which lets
+ * esbuild drop the branch and, with it, the dynamic import; in dev it is undefined or an object, so
+ * this reads exactly as `isDevMode()` did there. It is the check Angular's own sources use.
+ */
+const DEV_GUARD = "if (typeof ngDevMode === 'undefined' || ngDevMode) {";
+/** Declared locally so strict TypeScript accepts the global without the app importing anything. */
+const NG_DEV_MODE_DECLARATION = 'declare const ngDevMode: unknown;';
+/** The guard the previous version wrote, which is rewritten in place on a re-run. */
+const LEGACY_GUARD = /^if \(isDevMode\(\)\) \{(?=\s*void Promise\.all\(\[\s*import\('@reticlehq\/browser'\))/m;
+/** The comment the previous version wrote above it, which named the guard it no longer uses. */
+const LEGACY_COMMENT = /^\/\/ Reticle, dev only — written by `reticle init`\. `isDevMode\(\)` is false in a production build,\n\/\/ so this never runs there\./m;
+const HEADER = '// Reticle, dev only — written by `reticle init`. `ngDevMode` is false in a production build,\n' +
+    '// so the build drops this block.';
+/**
+ * Add the dev-only connect to the browser entry, or ALREADY when it is there.
+ *
+ * Appended after the bootstrap rather than before it: the app must never wait on Reticle, and a
+ * connect that fails (no daemon yet) must not be able to stop Angular from starting.
+ *
+ * An entry wired by the previous version (`if (isDevMode())`) is rewritten in place, so a re-run is
+ * what takes the connect out of an existing app's production bundle.
+ */
+export function patchAngularMain(source, port, projectId) {
+    if (LEGACY_GUARD.test(source)) {
+        const guarded = source
+            .replace(LEGACY_COMMENT, HEADER)
+            .replace(LEGACY_GUARD, `${NG_DEV_MODE_DECLARATION}\n${DEV_GUARD}`);
+        return { kind: PatchKind.APPLY, code: guarded };
+    }
+    if (source.includes(SENSOR))
+        return { kind: PatchKind.ALREADY };
+    const declaration = source.includes(NG_DEV_MODE_DECLARATION)
+        ? ''
+        : `${NG_DEV_MODE_DECLARATION}\n`;
+    const block = `
+${HEADER} The pairing token comes from \`ng serve\` (${ANGULAR_PROXY_PATH}), so it
+// is never in a source file or a bundle.
+${declaration}${DEV_GUARD}
+  void Promise.all([
+    import('${SENSOR}'),
+    fetch('${ANGULAR_TOKEN_PATH}')
+      .then((res) => (res.ok ? res.text() : ''))
+      .catch(() => ''),
+  ]).then(([{ reticle }, token]) => {
+    reticle.connect({ ${connectFields(port, projectId)}...(token ? { token } : {}) });
+  });
+}
+`;
+    return { kind: PatchKind.APPLY, code: `${source.trimEnd()}\n${block}` };
+}

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

@@ -45,7 +45,7 @@ export declare const ASTRO_VITE_OWNING_MARKER = "reticle-vite-owning";
  * have to restart the dev server.
  */
 export declare const ASTRO_MISSING_TOKEN_WARNING: string;
-export declare function patchAstroConfig(source: string): SourcePatch;
+export declare function patchAstroConfig(source: string, viteMajor?: number | null): SourcePatch;
 /**
  * Import path from a layout/page to the generated connect module, always relative and posix.
  *

package/dist/patch/astro-patch.js

@@ -99,8 +99,8 @@ const ASTRO_VITE_CONFIG = {
     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 });
 }
 /**
  * Aliased imports so a layout that already pulled `readFileSync` from `node:fs` does not get a

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.js

@@ -3,7 +3,7 @@
  * 1000-line cap): its path, the plugin file itself, the notice, and the manual fallback.
  */
 import { ReticleDir } from '@reticlehq/core';
-import { connectArg, registerCapabilitiesCall } from './snippets.js';
+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';
 /**
@@ -53,9 +53,9 @@ export default defineNuxtPlugin(() => {
       ...(root.length > 0 ? { root } : {}),
     });
 
-    // What the agent can drive without guessing. Add a store here too — registerStore('cart',
-    // piniaStore(useCartStore())) — and the agent can check what the app BELIEVES, not just what it
-    // rendered. See node_modules/@reticlehq/server/docs/usage.md.
+    // 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, '    ')}
   });
 });
@@ -130,6 +130,6 @@ and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which i
 
 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. There is no Nuxt app in this project's CI, so this path is UNVERIFIED:
-if something does not work, please open an issue.`;
+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.`;
 }

package/dist/patch/remix.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Remix v2's client entry, and the one honest answer for the classic compiler.
+ *
+ * Remix on Vite is React Router framework mode under its old name: it SSRs its own HTML, so the
+ * Vite plugin's `index.html` injection never reaches the page, and the connect has to come from
+ * `app/entry.client.tsx` — the same line, the same file, verified by hand to connect.
+ */
+/**
+ * The client entry `init` writes when a Remix app has none.
+ *
+ * Like React Router's, `app/entry.client.tsx` is an OVERRIDE of a default Remix supplies — it only
+ * exists once somebody runs `remix reveal`. So the written file has to hydrate as well as connect:
+ * one holding only our import would replace the default with an app that renders nothing. This is
+ * Remix v2's own default entry with one line added.
+ */
+export declare function remixEntryFile(): string;
+/**
+ * The classic compiler has no Vite, so nothing serves `/@reticle-connect` and nothing stamps source.
+ *
+ * Said plainly and left as a ⚠ rather than papered over: writing the entry line here would import a
+ * module no dev server serves, and the app would log a failed import on every page load instead of
+ * connecting.
+ */
+export declare const REMIX_CLASSIC_MANUAL = "This is Remix on the classic compiler (remix.config.js, no Vite), and Reticle cannot wire it:\nthe connect module and the source stamping both come from @reticlehq/vite-plugin, and this build\nnever runs Vite.\n\n  \u2022 Recommended: move to Remix's Vite plugin (https://remix.run/docs/en/main/guides/vite), or on to\n    React Router v7+ framework mode, then re-run `reticle init` \u2014 both are wired automatically.\n  \u2022 Or connect by hand from app/entry.client.tsx, dev-only, through the React kit init installed:\n\n      if (process.env.NODE_ENV === 'development') {\n        void import('@reticlehq/react').then(({ reticle, install }) => {\n          install();\n          reticle.connect({ token: '<the contents of ~/.reticle/pairing-token>' });\n        });\n      }\n\n    The token is per-machine: keep it out of version control.";

package/dist/patch/remix.js

@@ -0,0 +1,59 @@
+/**
+ * Remix v2's client entry, and the one honest answer for the classic compiler.
+ *
+ * Remix on Vite is React Router framework mode under its old name: it SSRs its own HTML, so the
+ * Vite plugin's `index.html` injection never reaches the page, and the connect has to come from
+ * `app/entry.client.tsx` — the same line, the same file, verified by hand to connect.
+ */
+import { REACT_ROUTER_CONNECT_LINE } from './snippets.js';
+/**
+ * The client entry `init` writes when a Remix app has none.
+ *
+ * Like React Router's, `app/entry.client.tsx` is an OVERRIDE of a default Remix supplies — it only
+ * exists once somebody runs `remix reveal`. So the written file has to hydrate as well as connect:
+ * one holding only our import would replace the default with an app that renders nothing. This is
+ * Remix v2's own default entry with one line added.
+ */
+export function remixEntryFile() {
+    return `import { RemixBrowser } from '@remix-run/react';
+import { startTransition, StrictMode } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+
+// Dev-only: Remix renders HTML through its own request handler, so the Vite plugin's index.html
+// injection never fires and the connect script never reaches the page. The plugin is still doing
+// the other half of the job — it stamps data-reticle-source, which puts file:line on every verdict.
+${REACT_ROUTER_CONNECT_LINE}
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <RemixBrowser />
+    </StrictMode>,
+  );
+});
+`;
+}
+/**
+ * The classic compiler has no Vite, so nothing serves `/@reticle-connect` and nothing stamps source.
+ *
+ * Said plainly and left as a ⚠ rather than papered over: writing the entry line here would import a
+ * module no dev server serves, and the app would log a failed import on every page load instead of
+ * connecting.
+ */
+export const REMIX_CLASSIC_MANUAL = `This is Remix on the classic compiler (remix.config.js, no Vite), and Reticle cannot wire it:
+the connect module and the source stamping both come from @reticlehq/vite-plugin, and this build
+never runs Vite.
+
+  • Recommended: move to Remix's Vite plugin (https://remix.run/docs/en/main/guides/vite), or on to
+    React Router v7+ framework mode, then re-run \`reticle init\` — both are wired automatically.
+  • Or connect by hand from app/entry.client.tsx, dev-only, through the React kit init installed:
+
+      if (process.env.NODE_ENV === 'development') {
+        void import('@reticlehq/react').then(({ reticle, install }) => {
+          install();
+          reticle.connect({ token: '<the contents of ~/.reticle/pairing-token>' });
+        });
+      }
+
+    The token is per-machine: keep it out of version control.`;