@reticlehq/init 3.2.0 → 3.4.0

package/dist/patch/snippets.js

@@ -2,9 +2,11 @@
  * Generated file contents and copy-paste snippets for `reticle init`. Kept as named constants/builders
  * so the runner never inlines free strings.
  */
-import { RETICLE_DEFAULT_PORT, ReticleDir, bridgeWsUrl, RETICLE_CLIENT_HOST, RETICLE_WS_PATH, } from '@reticlehq/core';
-import { UiLibrary } from '../detect/detect.js';
+import { RETICLE_DEFAULT_PORT, bridgeWsUrl, RETICLE_CLIENT_HOST, RETICLE_WS_PATH, } from '@reticlehq/core';
+import { Framework, UiLibrary } from '../detect/detect.js';
 import { RETICLE_VERSION } from '../version.js';
+import { VITE_ENV_DEV_DECLARATION } from './vite-env-types.js';
+import { posix } from 'node:path';
 /**
  * The SDK as one import a plain page can actually resolve.
  *
@@ -24,7 +26,13 @@ import { RETICLE_VERSION } from '../version.js';
  * 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@${RETICLE_VERSION}/+esm`;
+/**
+ * Where a generated file sends someone to learn `registerStore`. A URL, not a path into
+ * `node_modules/@reticlehq/server`: the server is never installed into the app, so the path the
+ * generated files used to name did not exist in any project they were written into.
+ */
+export const STATE_DOCS_URL = 'https://docs.reticle.sh/state-management';
+export const CDN_SDK_URL = `https://cdn.jsdelivr.net/npm/@reticlehq/browser@${RETICLE_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.
@@ -57,6 +65,35 @@ export function connectArgWithToken(port, projectId, pairingToken) {
     const inner = base.length > 0 ? base.slice(1, -1).trim() : '';
     return `{ ${[inner, `token: '${pairingToken}'`].filter((p) => p.length > 0).join(', ')} }`;
 }
+/**
+ * Does this codebase want the React kit, or the framework-neutral sensor? The ONE answer, read by
+ * both `frameworkPackages` (what is installed) and `sdkImport` (what generated code imports).
+ *
+ * The kit is what adds component identity — component names and stacks — and it is worth having
+ * wherever React or Preact is rendering (the adapter reaches Preact through `preact/compat`).
+ * Everywhere else it is a package named `@reticlehq/react`, carrying `react` in its peer
+ * dependencies, being installed into a codebase that has no React in it.
+ *
+ * UNKNOWN keeps the kit deliberately. Absence of evidence is not evidence of Vue, and guessing
+ * "sensor" on no information silently drops component identity from apps that should have it.
+ *
+ * Except where the absence IS the evidence: on these stacks nothing renders React but a `react` the
+ * app depends on itself, so no renderer found is a vanilla, Lit, Solid or Angular app.
+ */
+const RENDERER_IS_DECLARED = new Set([
+    Framework.VITE,
+    // A package.json with no UI library and no bundler Reticle recognises. It was handed
+    // `@reticlehq/react` and `react` — a React install into a page with no React in it.
+    Framework.HTML,
+    // Forge's Vite template is vanilla TypeScript; a React renderer declares `react` like any app.
+    Framework.ELECTRON_FORGE,
+    Framework.ANGULAR,
+]);
+export function usesReactKit(uiLibrary, framework) {
+    if (UiLibrary.UNKNOWN === uiLibrary)
+        return !RENDERER_IS_DECLARED.has(framework);
+    return uiLibrary !== UiLibrary.VUE && uiLibrary !== UiLibrary.SVELTE;
+}
 /**
  * Which SDK package the GENERATED code should import, and whether `install()` applies.
  *
@@ -68,9 +105,8 @@ export function connectArgWithToken(port, projectId, pairingToken) {
  * `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
+export function sdkImport(uiLibrary, framework) {
+    return usesReactKit(uiLibrary, framework)
         ? { specifier: '@reticlehq/react', usesInstall: true }
         : { specifier: '@reticlehq/browser', usesInstall: false };
 }
@@ -95,6 +131,15 @@ function frameworkPluginExample(uiLibrary) {
             return '/* your existing plugins */';
     }
 }
+/**
+ * The `defineConfig` import each printed config needs. The snippets call `defineConfig`, and one
+ * pasted as printed into an empty file used to die with `ReferenceError: defineConfig is not
+ * defined` because the import was left out.
+ */
+const DEFINE_CONFIG_IMPORT = {
+    VITE: "import { defineConfig } from 'vite';",
+    ELECTRON_VITE: "import { defineConfig } from 'electron-vite';",
+};
 /** The Vite-config snippet printed when we can't safely auto-patch the config. */
 export function viteManual(port, uiLibrary = UiLibrary.UNKNOWN, inject = true, sourceMapping = true) {
     const options = [
@@ -110,6 +155,7 @@ lowercase JSX tag is not an element. Stamping one crashes the app at commit time
 pointers, not the app.`;
     return `Add the Reticle plugin to your Vite config:
 
+  ${DEFINE_CONFIG_IMPORT.VITE}
   import { reticle } from '@reticlehq/vite-plugin';
 
   export default defineConfig({
@@ -124,8 +170,11 @@ from \`vite build\`.${note}`;
 /**
  * The electron-vite recipe: the plugin belongs in `renderer`, never in `main` or `preload`.
  *
- * `desktop: true` is load-bearing. Without it the plugin is serve-only, so a packaged renderer
- * (a production build with no dev server) ships with no connect() at all.
+ * `desktop: true` is load-bearing: it injects connect() into the entry module and passes
+ * `allowInProduction`, because a packaged renderer has no dev server and reports
+ * `NODE_ENV=production`, so without it the SDK's production backstop refuses to start. It does not
+ * instrument a release — a production-mode `electron-vite build` is stubbed like a web bundle — so
+ * a packaged renderer that should be driven is built with `--mode development`.
  */
 export function electronViteManual(port, uiLibrary = UiLibrary.UNKNOWN) {
     const extras = port === undefined
@@ -133,6 +182,7 @@ export function electronViteManual(port, uiLibrary = UiLibrary.UNKNOWN) {
         : `desktop: true, port: ${String(port)}, captureNetworkBodies: true`;
     return `Add the Reticle plugin to the \`renderer\` block of electron.vite.config, not \`main\`:
 
+  ${DEFINE_CONFIG_IMPORT.ELECTRON_VITE}
   import { reticle } from '@reticlehq/vite-plugin';
 
   export default defineConfig({
@@ -143,8 +193,9 @@ export function electronViteManual(port, uiLibrary = UiLibrary.UNKNOWN) {
     },
   });
 
-\`desktop: true\` is required: a packaged renderer is a production build with no dev server, so the
-default serve-only plugin is dropped from \`vite build\` and the shipped app never connects.
+\`desktop: true\` is required: a packaged renderer has no dev server and reports production, and
+without it the SDK refuses to start there. A production-mode build still ships no Reticle code; to drive a
+packaged renderer with no dev server, build it with \`--mode development\`.
 
 Also add \`import '@reticlehq/electron/preload'\` as the first line of your preload, and
 \`installReticleCapture(win)\` in main after you construct the BrowserWindow.`;
@@ -182,7 +233,7 @@ export function nextReticleDevFile(port, projectId, testids = [], stores = [], f
     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.'
+            ? `        // No state library detected. If you add one, register it here — see ${STATE_DOCS_URL}`
             : stores.map((h) => `        // import your store, then: ${h}`).join('\n');
     const registerNames = found.length > 0 ? ', registerStore' : '';
     // Multiline connect + single blank after imports (#684): the one-line connect and the double blank
@@ -204,10 +255,13 @@ export function ReticleDev() {
         // withReticle() finds the daemon serving this project on every dev-server start. It wins over
         // any port written into this file at install time, so moving the daemon needs no edit here.
         const url = process.env.NEXT_PUBLIC_RETICLE_URL;
+        // So a version-skewed pair names the SDK's version instead of "an unknown older wire".
+        const sdkVersion = process.env.NEXT_PUBLIC_RETICLE_SDK_VERSION;
         reticle.connect({
           ${fields}...(url ? { url } : {}),
           ...(token ? { token } : {}),
           ...(root ? { root } : {}),
+          ...(sdkVersion ? { sdkVersion } : {}),
         });
 
         // ── Start with ONE flow. ────────────────────────────────────────────────────────────────
@@ -263,10 +317,9 @@ layoutPath) {
         ? `\n          url: '${bridgeWsUrl(port)}',`
         : '';
     const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
-    // Astro owns its Vite instance, so it has a build-time channel of its own: the same `define` that
-    // already inlines the token can inline the daemon URL, resolved every time the config is read —
-    // that is, on every `astro dev`. The port above is written once at install time and goes stale the
-    // moment the daemon moves; this does not.
+    // Astro owns its Vite instance, so the layout can resolve the daemon URL in frontmatter on every
+    // `astro dev` and put it on a <meta> the client script reads. The port above is written once at
+    // install time and goes stale the moment the daemon moves; this does not.
     //
     // Needs the projectId to know WHICH daemon is ours. Without one there is nothing to match on, and
     // adopting a daemon serving another project would report its state as this app's, so the whole
@@ -276,10 +329,8 @@ layoutPath) {
     // `bridgeWsUrl` builds, and a generator that spells it out by hand is exactly how the four call
     // sites that constant exists to unify drifted apart in the first place.
     const RETICLE_CLIENT_HOST_LITERAL = `ws://${RETICLE_CLIENT_HOST}:`;
-    const urlHelper = canDiscover
+    const urlFrontmatter = canDiscover
         ? `
-  // The live daemon serving THIS project, re-read on every \`astro dev\`. Same rule as the Vite and
-  // Next plugins: skip dead daemons, match on projectId, lowest port wins, '' when none matches.
   function reticleUrl() {
     const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
     let best;
@@ -295,63 +346,77 @@ layoutPath) {
     } catch { return ''; }
     return best === undefined ? '' : '${RETICLE_CLIENT_HOST_LITERAL}' + best + '${RETICLE_WS_PATH}';
   }
+  const pairingUrl = import.meta.env.DEV ? reticleUrl() : '';
 `
         : '';
-    const urlDefine = canDiscover ? `\n        __RETICLE_URL__: JSON.stringify(reticleUrl()),` : '';
+    const urlMeta = canDiscover ? `\n  <meta name="reticle-pairing-url" content={pairingUrl} />` : '';
     const urlRead = canDiscover
-        ? `\n      const url = typeof __RETICLE_URL__ !== 'undefined' ? __RETICLE_URL__ : '';`
+        ? `\n  const url = document.querySelector('meta[name="reticle-pairing-url"]')?.getAttribute('content') ?? '';`
         : '';
-    // After the baked port, so the discovered one wins: later key in an object literal.
-    const urlSpread = canDiscover ? `\n          ...(url.length > 0 ? { url } : {}),` : '';
-    return `Astro renders its own HTML, so the connect goes in a page <script> and the pairing token is inlined by the config.
+    const urlSpread = canDiscover ? `\n    ...(url.length > 0 ? { url } : {}),` : '';
+    return `Astro renders its own HTML, so the connect goes in a local module the page statically imports. Do not put the pairing token through \`vite.define\`: on Astro 7.2+ that substitution never reaches the client, the identifier stays literal, and the bridge refuses the dial. Read the token in frontmatter and put it on a <meta> the module can query. Reading it per request also means a token written after the dev server started is picked up on the next load instead of needing a restart.
 
-1. In astro.config.mjs — inline the daemon's token and raise the build target:
+1. In astro.config.mjs, raise the build target. The token does NOT belong here:
 
-  import { readFileSync, readdirSync } from 'node:fs';
-  import { homedir } from 'node:os';
-  import { join } from 'node:path';
-
-  function reticleToken() {
-    const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
-    try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
-  }
-${urlHelper}
   export default defineConfig({
     vite: {
       // Astro's default target down-levels the modern SDK bundle and fails on a destructuring transform.
       build: { target: 'es2022' },
-      optimizeDeps: { esbuildOptions: { target: 'es2022' } },
-      define: {
-        __RETICLE_TOKEN__: JSON.stringify(reticleToken()),${urlDefine}
-        // Without this, source pointers come back as absolute paths from YOUR machine — useless in a
-        // report. Every other framework gets it from its build plugin; Astro owns its Vite instance.
-        __RETICLE_ROOT__: JSON.stringify(process.cwd()),
-      },
+      optimizeDeps: { include: ['@reticlehq/react'] },
     },
   });
 
 ${layoutHost(layoutPath)}
 
+  ---
+  import { readFileSync${canDiscover ? ', readdirSync' : ''} } from 'node:fs';
+  import { homedir } from 'node:os';
+  import { join } from 'node:path';
+  const pairingToken = (() => {
+    if (!import.meta.env.DEV) return '';
+    const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+    try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+  })();
+  const pairingRoot = import.meta.env.DEV ? process.cwd() : '';${urlFrontmatter}  ---
+  <meta name="reticle-pairing-token" content={pairingToken} />
+  <meta name="reticle-pairing-root" content={pairingRoot} />${urlMeta}
   <script>
+    import connectReticle from '../components/ReticleDev';
     if (import.meta.env.DEV) {
-      const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-      const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';${urlRead}
-      const { reticle, install } = await import('@reticlehq/react');
-      install();
-      reticle.connect({${id}${extra}${urlSpread}
-          ...(token.length > 0 ? { token } : {}),
-          ...(root.length > 0 ? { root } : {}),
-      });
+      connectReticle();
     }
   </script>
 
-3. In src/env.d.ts — declare the Vite define names so \`astro check\` can see them (create-astro's
-   default build runs check first, and without this it fails with Cannot find name '__RETICLE_TOKEN__'):
+  The <script> tag must not sit inside a conditional. Astro hoists them statically, so
+  \`{isDev && (<script />)}\` is never hoisted and the module 404s.
+  The dev gate belongs in the imported module.
+
+3. Create src/components/ReticleDev.ts — Vite owns this file, so the SDK is a static import:
+
+  import { reticle, install } from '@reticlehq/react';
+  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') ?? '';${urlRead}
+    if (token.length === 0) {
+      console.warn('[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 and reload this page.');
+    }
+    install();
+    reticle.connect({${id}${extra}${urlSpread}
+      ...(token.length > 0 ? { token } : {}),
+      ...(root.length > 0 ? { root } : {}),
+    });
+  }
+
+4. In src/env.d.ts — declare the window names so \`astro check\` can see them (create-astro's
+   default build runs check first):
 
-  declare const __RETICLE_TOKEN__: string | undefined;
-  declare const __RETICLE_ROOT__: string | undefined;
+  interface Window {
+    __RETICLE_TOKEN__?: string;
+    __RETICLE_ROOT__?: string;
+  }
 
-Start the daemon BEFORE \`astro dev\`, so the token file exists when the config is read. Until it does the token is empty and the page reloads once the daemon is up.`;
+Start the daemon, then load the page. The token is read when the page renders, so a reload is enough
+once the token file exists — you do not have to restart \`astro dev\`.`;
 }
 /**
  * The `registerCapabilities` call every generated connect carries.
@@ -383,7 +448,7 @@ ${indent}});`;
  * 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, found = [], uiLibrary = UiLibrary.REACT) {
+export function viteDevModuleFile(testids, stores, found = [], uiLibrary = UiLibrary.REACT, framework) {
     // 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
@@ -391,7 +456,7 @@ export function viteDevModuleFile(testids, stores, found = [], uiLibrary = UiLib
     //
     // 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 sdk = sdkImport(uiLibrary, framework);
     const ids = testids.map((t) => `'${t}'`).join(', ');
     // 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).
@@ -399,10 +464,11 @@ export function viteDevModuleFile(testids, stores, found = [], uiLibrary = UiLib
     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.'
+            ? `  // No state library detected. If you add one, register it here — see ${STATE_DOCS_URL}`
             : 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.
+    return `// Dev-only. Loaded for you after connect() — by @reticlehq/vite-plugin's injected connect, or by
+// the connect file init wrote for a framework that connects itself — so you do not import it.
 // Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
 import { ${registerImport} } from '${sdk.specifier}';
 ${storeImports.length > 0 ? `${storeImports}\n` : ''}
@@ -424,10 +490,19 @@ ${storeBlock}
     stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
   });
 }
-`;
+
+${VITE_ENV_DEV_DECLARATION}`;
 }
 /** Where that module goes. Matches @reticlehq/vite-plugin's convention list. */
 export const VITE_DEV_MODULE_PATH = 'src/reticle-dev.ts';
+/**
+ * The dev module as a relative import from `fromFile` — for the frameworks that connect themselves
+ * and so have to load it themselves (see svelteKitHooksFile, tanstackStartConnectFile).
+ */
+export function devModuleSpecifier(fromFile) {
+    const rel = posix.relative(posix.dirname(fromFile), VITE_DEV_MODULE_PATH.replace(/\.ts$/, ''));
+    return rel.startsWith('.') ? rel : `./${rel}`;
+}
 /**
  * electron-vite's renderer Vite root is `src/renderer`, so the plugin looks for
  * `src/renderer/src/reticle-dev.ts` — not the package-root path a plain Vite app uses.
@@ -504,7 +579,7 @@ st.html(
  * `<head>`, so the SDK sees a parsed document.
  */
 export function djangoMiddlewareSnippet(connectArgLiteral) {
-    return `# reticle_dev.py — add to MIDDLEWARE while DEBUG is on:
+    return `# reticle_dev.py: add to MIDDLEWARE while DEBUG is on:
 #   MIDDLEWARE = [..., "reticle_dev.ReticleDevMiddleware"]
 from django.conf import settings
 
@@ -540,8 +615,21 @@ class ReticleDevMiddleware:
         return response
 `;
 }
-export function htmlManual(port, projectId, pairingToken) {
+export function htmlManual(port, projectId, pairingToken, 
+// Which SDK the bundled form imports must be the one init INSTALLED. A page with no UI library
+// now gets the sensor, and a snippet still naming `@reticlehq/react` would import a package that
+// is not there.
+uiLibrary = UiLibrary.UNKNOWN) {
     const withToken = connectArgWithToken(port, projectId, pairingToken);
+    const sdk = sdkImport(uiLibrary, Framework.HTML);
+    const bundledImport = sdk.usesInstall
+        ? `void import('${sdk.specifier}').then(({ reticle, install }) => {
+          install();
+          reticle.connect(${withToken});
+        });`
+        : `void import('${sdk.specifier}').then(({ reticle }) => {
+          reticle.connect(${withToken});
+        });`;
     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
@@ -550,13 +638,10 @@ export function htmlManual(port, projectId, pairingToken) {
     return `No Vite/Next plugin detected — wire the dev-only connect by hand. Pick the form for your setup:
 
   • 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:
+    (e.g. src/index.js or src/main.js), where '${sdk.specifier}' resolves through your bundler:
 
       if (process.env.NODE_ENV !== 'production') {
-        void import('@reticlehq/react').then(({ reticle, install }) => {
-          install();
-          reticle.connect(${withToken});
-        });
+        ${bundledImport}
       }${tokenNote}
 
   • Plain HTML with NO build step (FastAPI, Flask, Django, Rails, Streamlit, a hand-written page) —
@@ -581,7 +666,7 @@ export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
  * component names and source mapping do not, and no CI gate covers this stack. Saying so beats
  * reporting all-green.
  */
-export function unverifiedUiLibraryNote(library) {
+export function unverifiedUiLibraryNote(library, installGated = false) {
     // 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
@@ -590,10 +675,10 @@ export function unverifiedUiLibraryNote(library) {
     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.`;
+    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} ${installGated ? `The install gate scaffolds this ${library} stack from scratch on every change, so this SETUP is proven; no gate drives it to a verdict, so the drive is not.` : `No CI gate covers ${library}.`} Driven on every change: Vite + React, Next.js, 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.';
-export const UNVERIFIED_TANSTACK_START_NOTE = 'Reticle has no TanStack Start 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 client effect does not register a session, please open an issue.';
+export const SVELTEKIT_SETUP_GATED_NOTE = 'The install gate scaffolds a SvelteKit app on every release and requires this hook to connect a session, so the wiring is proven; driving flows on SvelteKit to a verdict is not. If the hook does not register a session, please open an issue.';
+export const UNVERIFIED_TANSTACK_START_NOTE = 'Reticle has no TanStack Start 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. Gated today: Vite (React, Vue), Next.js, Nuxt, React Router, Remix, Astro, SvelteKit, Create React App and Angular. If the client effect does not register a session, please open an issue.';
 /**
  * Printed when init detects react-three-fiber. Reticle's model is DOM + store + network; a WebGL
  * canvas is none of those. Without this line, init succeeds, sessions connect, and surrounding UI
@@ -632,6 +717,9 @@ if (import.meta.env.DEV) {
       ...(sdkVersion.length > 0 ? { sdkVersion } : {}),
     });
 ${registerCapabilitiesCall(testids, '    ')}
+    // Your stores and capabilities live in ${VITE_DEV_MODULE_PATH}. Only the plugin's injected
+    // connect imports that file, and SvelteKit never runs it, so this hook loads it instead.
+    void import('${devModuleSpecifier(SVELTEKIT_HOOKS_PATH)}');
   });
 }
 
@@ -681,10 +769,26 @@ export function webpack4TranspileNote(reactScriptsMajor) {
 }
 /** React Router's client-entry override point, in framework mode. */
 export const REACT_ROUTER_ENTRY_PATH = 'app/entry.client.tsx';
-/** The dev-only module @reticlehq/vite-plugin serves: connect() with the token already in it. */
-const RETICLE_CONNECT_MODULE = '/@reticle-connect';
-/** The one line that puts Reticle in a React Router client entry. */
-export const REACT_ROUTER_CONNECT_LINE = `if (import.meta.env.DEV) void import('/@reticle-connect');`;
+/**
+ * The dev-only module @reticlehq/vite-plugin serves: connect() with the token already in it. Named
+ * without its leading slash, because that is the part both the current line and the old one carry.
+ */
+const RETICLE_CONNECT_MODULE = '@reticle-connect';
+/**
+ * The one line that puts Reticle in a React Router client entry — and in a Remix one.
+ *
+ * The specifier is BUILT, not written as a literal. `import('/@reticle-connect')` is a module only
+ * the Vite dev server can answer, so `tsc` cannot resolve it: a fresh framework-mode scaffold went
+ * red on `npm run typecheck` (`TS2307: Cannot find module '/@reticle-connect'`) the moment `init`
+ * wrote it. A computed specifier is typed `Promise<any>` and never resolved, so no declaration, no
+ * suppression comment and no tsconfig edit is needed. The browser still asks the dev server for the
+ * same URL, which the plugin serves; `BASE_URL` keeps it right under a non-root `base`. `@vite-ignore`
+ * is Vite's own marker for a dynamic import it should not try to analyse, not a lint suppression. In
+ * a production build `import.meta.env.DEV` is false and the whole line is dropped.
+ */
+export const REACT_ROUTER_CONNECT_LINE = 'if (import.meta.env.DEV) void import(/* @vite-ignore */ `${import.meta.env.BASE_URL}@reticle-connect`);';
+/** The line `init` used to write, which fails `tsc`; replaced in place on a re-run. */
+const REACT_ROUTER_CONNECT_LINE_UNTYPED = "if (import.meta.env.DEV) void import('/@reticle-connect');";
 /**
  * The client entry `init` writes when React Router framework mode has none.
  *
@@ -726,6 +830,9 @@ startTransition(() => {
  * still be evaluated first, and this is a side-effect import.
  */
 export function reactRouterEntryPatch(source) {
+    if (source.includes(REACT_ROUTER_CONNECT_LINE_UNTYPED)) {
+        return source.replace(REACT_ROUTER_CONNECT_LINE_UNTYPED, REACT_ROUTER_CONNECT_LINE);
+    }
     if (source.includes(RETICLE_CONNECT_MODULE))
         return null;
     const lines = source.split('\n');
@@ -737,135 +844,7 @@ export function reactRouterEntryPatch(source) {
     lines.splice(lastImport + 1, 0, REACT_ROUTER_CONNECT_LINE);
     return lines.join('\n');
 }
-/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
-export 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 — 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.
-${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. There is no Nuxt app in this project's CI, so this path is UNVERIFIED:
-if something does not work, please open an issue.`;
-}
+export { nuxtPluginPath, nuxtPluginFile, NUXT_PLUGIN_NOTICE, nuxtManual } from './nuxt-snippets.js';
 /**
  * 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).