@reticlehq/init 3.3.0 → 3.5.0

package/dist/patch/snippets.d.ts

@@ -2,8 +2,34 @@
  * Generated file contents and copy-paste snippets for `reticle init`. Kept as named constants/builders
  * so the runner never inlines free strings.
  */
-import { UiLibrary } from '../detect/detect.js';
+import { Framework, UiLibrary } from '../detect/detect.js';
 import type { FoundStore } from '../detect/capabilities.js';
+/**
+ * The SDK as one import a plain page can actually resolve.
+ *
+ * `init` used to tell static-HTML users that a page with no build step could not load the SDK, and
+ * to go and stand up a bundler. That is true of a BARE specifier and false of a URL, and the
+ * difference was the whole road for every server-rendered app we hear from: FastAPI, Flask, Django,
+ * Streamlit, Rails. Proven end to end before this shipped, on a page served by `python3 -m
+ * http.server`: a session connected, a snapshot returned, and two act_and_wait calls came back
+ * `verified: "yes"`.
+ *
+ * jsDelivr rather than esm.sh, measured: a third of the requests and a third of the bytes for the
+ * same result. `/+esm` is what makes it work, and the bare package URL does NOT: every file in
+ * `dist` still carries bare workspace specifiers such as `@reticlehq/core`, so an unbundled entry
+ * point dies on the first import. That is also why adding `unpkg`/`jsdelivr` fields to package.json
+ * would not help.
+ *
+ * PINNED to this server's version on purpose. A floating import upgrades the page SDK underneath a
+ * daemon that did not move, which is `version_skew` arriving by a route nothing checks.
+ */
+/**
+ * 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 declare const STATE_DOCS_URL = "https://docs.reticle.sh/state-management";
+export declare const CDN_SDK_URL: string;
 /**
  * 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.
@@ -22,6 +48,7 @@ export declare function connectArg(port: number | undefined, projectId?: string)
  * one that does hold a token.
  */
 export declare function connectArgWithToken(port: number | undefined, projectId: string | undefined, pairingToken: string | undefined): string;
+export declare function usesReactKit(uiLibrary: UiLibrary, framework?: Framework): boolean;
 /**
  * Which SDK package the GENERATED code should import, and whether `install()` applies.
  *
@@ -33,7 +60,7 @@ export declare function connectArgWithToken(port: number | undefined, projectId:
  * `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 declare function sdkImport(uiLibrary: UiLibrary): {
+export declare function sdkImport(uiLibrary: UiLibrary, framework?: Framework): {
     specifier: string;
     usesInstall: boolean;
 };
@@ -42,8 +69,11 @@ export declare function viteManual(port: number | undefined, uiLibrary?: UiLibra
 /**
  * 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 declare function electronViteManual(port: number | undefined, uiLibrary?: UiLibrary): string;
 /** Next.js config wrap — always printed (we never auto-rewrite next.config). */
@@ -89,9 +119,14 @@ export declare function registerCapabilitiesCall(testids: readonly string[], ind
  * 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 declare function viteDevModuleFile(testids: readonly string[], stores: readonly string[], found?: readonly FoundStore[], uiLibrary?: UiLibrary): string;
+export declare function viteDevModuleFile(testids: readonly string[], stores: readonly string[], found?: readonly FoundStore[], uiLibrary?: UiLibrary, framework?: Framework): string;
 /** Where that module goes. Matches @reticlehq/vite-plugin's convention list. */
 export declare 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 declare function devModuleSpecifier(fromFile: string): string;
 /**
  * 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.
@@ -137,7 +172,7 @@ export declare function streamlitPageSnippet(connectArgLiteral: string): string;
  * `<head>`, so the SDK sees a parsed document.
  */
 export declare function djangoMiddlewareSnippet(connectArgLiteral: string): string;
-export declare function htmlManual(port: number | undefined, projectId?: string, pairingToken?: string): string;
+export declare function htmlManual(port: number | undefined, projectId?: string, pairingToken?: string, uiLibrary?: UiLibrary): string;
 export declare const NEXT_RETICLE_DEV_PATH = "app/reticle-dev.tsx";
 export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
 /**
@@ -146,9 +181,9 @@ export declare 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 declare function unverifiedUiLibraryNote(library: string): string;
-export declare const UNVERIFIED_FRAMEWORK_NOTE = "Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested \u2014 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 declare const UNVERIFIED_TANSTACK_START_NOTE = "Reticle has no TanStack Start app and no CI gate for one, so this wiring is untested \u2014 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 declare function unverifiedUiLibraryNote(library: string, installGated?: boolean): string;
+export declare 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 declare const UNVERIFIED_TANSTACK_START_NOTE = "Reticle has no TanStack Start app and no CI gate for one, so this wiring is untested \u2014 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
@@ -181,6 +216,19 @@ export declare const WEBPACK4_REACT_SCRIPTS_MAJOR = 5;
 export declare function webpack4TranspileNote(reactScriptsMajor: number): string;
 /** React Router's client-entry override point, in framework mode. */
 export declare const REACT_ROUTER_ENTRY_PATH = "app/entry.client.tsx";
+/**
+ * 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 declare const REACT_ROUTER_CONNECT_LINE = "if (import.meta.env.DEV) void import(/* @vite-ignore */ `${import.meta.env.BASE_URL}@reticle-connect`);";
 /**
  * The client entry `init` writes when React Router framework mode has none.
  *

package/dist/patch/snippets.js

@@ -3,9 +3,10 @@
  * so the runner never inlines free strings.
  */
 import { RETICLE_DEFAULT_PORT, bridgeWsUrl, RETICLE_CLIENT_HOST, RETICLE_WS_PATH, } from '@reticlehq/core';
-import { UiLibrary } from '../detect/detect.js';
+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.
  *
@@ -25,7 +26,13 @@ import { VITE_ENV_DEV_DECLARATION } from './vite-env-types.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.
@@ -58,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.
  *
@@ -69,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 };
 }
@@ -96,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 = [
@@ -111,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({
@@ -125,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
@@ -134,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({
@@ -144,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.`;
@@ -183,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
@@ -398,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
@@ -406,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).
@@ -414,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` : ''}
@@ -444,6 +495,14 @@ ${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.
@@ -556,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
@@ -566,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) —
@@ -597,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
@@ -606,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
@@ -648,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)}');
   });
 }
 
@@ -697,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. */
-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.
  *
@@ -742,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');

package/dist/patch/static-page.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The connect snippet, written INTO a static page rather than printed beside it.
+ *
+ * A page with no package.json has no build, so the pasted `<script type="module">` is the whole
+ * install — proven end to end on a page served by `python3 -m http.server`. `init` used to print it
+ * and exit 1 with `no_package_json`, which made the one path that works read as a failure, and left
+ * the step to a human who then had to be told where to put it.
+ *
+ * Two things differ from the printed recipe, both because the file is the deployable artifact:
+ *
+ * - It runs only on a loopback host. A static file has no development build to strip it, so the
+ *   host is the only line between this snippet and a published page; guarded, a published copy
+ *   does not even fetch the SDK. The printed bundled-app recipe deliberately does NOT do this
+ *   (a hosts-file dev alias defeats it, see html-no-build.test.ts) — that recipe has NODE_ENV.
+ * - It is marked, so a re-run recognises its own block and never writes a second one.
+ * - It carries no pairing token. The token used to be a literal in the page, so committing or
+ *   publishing index.html published it; it now sits in a module beside the page that `init`
+ *   gitignores, which the block imports and any static server serves. Absent — a teammate's
+ *   checkout, a published copy — the connect goes without one, and the bridge says why it refused.
+ */
+/** The page a static site serves at its root, and the one file `init` will write the snippet into. */
+export declare const HTML_INDEX_PATH = "index.html";
+/** The gitignored module beside the page that holds this machine's pairing token. */
+export declare const STATIC_TOKEN_MODULE = "reticle.local.js";
+/** Opens the block `init` writes; a re-run looks for it. */
+export declare const STATIC_SNIPPET_MARKER = "<!-- reticle:connect (dev only, written by reticle init) -->";
+/** Whether this page already carries a Reticle connect. */
+export declare function hasStaticSnippet(html: string): boolean;
+/** The token module's content. Rewritten on every run, so a re-minted token is picked up. */
+export declare function staticTokenModule(pairingToken: string): string;
+/** The files to write so the token module exists and git ignores it; only what actually changes. */
+export declare function staticTokenFiles(pairingToken: string | undefined, readFile: (path: string) => string | null): Record<string, string>;
+/**
+ * The page with the snippet added, or null when it already connects.
+ *
+ * Before `</body>` so the SDK starts on a parsed document; before `</head>` for a page with no body
+ * tag, and at the end for a fragment with neither.
+ */
+export declare function withStaticSnippet(html: string, connectArgLiteral: string): string | null;

package/dist/patch/static-page.js

@@ -0,0 +1,102 @@
+/**
+ * The connect snippet, written INTO a static page rather than printed beside it.
+ *
+ * A page with no package.json has no build, so the pasted `<script type="module">` is the whole
+ * install — proven end to end on a page served by `python3 -m http.server`. `init` used to print it
+ * and exit 1 with `no_package_json`, which made the one path that works read as a failure, and left
+ * the step to a human who then had to be told where to put it.
+ *
+ * Two things differ from the printed recipe, both because the file is the deployable artifact:
+ *
+ * - It runs only on a loopback host. A static file has no development build to strip it, so the
+ *   host is the only line between this snippet and a published page; guarded, a published copy
+ *   does not even fetch the SDK. The printed bundled-app recipe deliberately does NOT do this
+ *   (a hosts-file dev alias defeats it, see html-no-build.test.ts) — that recipe has NODE_ENV.
+ * - It is marked, so a re-run recognises its own block and never writes a second one.
+ * - It carries no pairing token. The token used to be a literal in the page, so committing or
+ *   publishing index.html published it; it now sits in a module beside the page that `init`
+ *   gitignores, which the block imports and any static server serves. Absent — a teammate's
+ *   checkout, a published copy — the connect goes without one, and the bridge says why it refused.
+ */
+import { CDN_SDK_URL } from './snippets.js';
+/** The page a static site serves at its root, and the one file `init` will write the snippet into. */
+export const HTML_INDEX_PATH = 'index.html';
+/** The gitignored module beside the page that holds this machine's pairing token. */
+export const STATIC_TOKEN_MODULE = 'reticle.local.js';
+const GITIGNORE_PATH = '.gitignore';
+/** Opens the block `init` writes; a re-run looks for it. */
+export const STATIC_SNIPPET_MARKER = '<!-- reticle:connect (dev only, written by reticle init) -->';
+const STATIC_SNIPPET_END = '<!-- /reticle:connect -->';
+/** Hostnames a developer's own machine serves a page on. */
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+/**
+ * Signs that the page already connects, whoever put the snippet there — the printed recipe pasted
+ * by hand counts as much as our own block.
+ */
+const ALREADY_CONNECTS = [STATIC_SNIPPET_MARKER, '@reticlehq/browser'];
+const BODY_CLOSE = /<\/body>/i;
+const HEAD_CLOSE = /<\/head>/i;
+/** Whether this page already carries a Reticle connect. */
+export function hasStaticSnippet(html) {
+    return ALREADY_CONNECTS.some((sign) => html.includes(sign));
+}
+function block(connectArgLiteral) {
+    const hosts = LOOPBACK_HOSTS.map((h) => `'${h}'`).join(', ');
+    const arg = '' === connectArgLiteral
+        ? '{ token: local.token }'
+        : `{ ...${connectArgLiteral}, token: local.token }`;
+    return `    ${STATIC_SNIPPET_MARKER}
+    <script type="module">
+      if ([${hosts}].includes(location.hostname)) {
+        Promise.all([
+          import('${CDN_SDK_URL}'),
+          import('./${STATIC_TOKEN_MODULE}').catch(() => ({})),
+        ]).then(([{ reticle }, local]) => reticle.connect(${arg}));
+      }
+    </script>
+    ${STATIC_SNIPPET_END}
+`;
+}
+/** The token module's content. Rewritten on every run, so a re-minted token is picked up. */
+export function staticTokenModule(pairingToken) {
+    return (`// This machine's Reticle pairing token, written by \`reticle init\`. Gitignored: never commit\n` +
+        `// or publish it — each machine runs \`reticle init\` for its own.\n` +
+        `export const token = '${pairingToken}';\n`);
+}
+/** The files to write so the token module exists and git ignores it; only what actually changes. */
+export function staticTokenFiles(pairingToken, readFile) {
+    if (pairingToken === undefined || 0 === pairingToken.length)
+        return {};
+    const files = {};
+    const module = staticTokenModule(pairingToken);
+    if (readFile(STATIC_TOKEN_MODULE) !== module)
+        files[STATIC_TOKEN_MODULE] = module;
+    const ignore = readFile(GITIGNORE_PATH) ?? '';
+    const covered = ignore
+        .split('\n')
+        .some((l) => [STATIC_TOKEN_MODULE, `/${STATIC_TOKEN_MODULE}`].includes(l.trim()));
+    if (!covered) {
+        files[GITIGNORE_PATH] =
+            `${'' === ignore ? '' : ignore.replace(/\n*$/, '\n')}${STATIC_TOKEN_MODULE}\n`;
+    }
+    return files;
+}
+/**
+ * The page with the snippet added, or null when it already connects.
+ *
+ * Before `</body>` so the SDK starts on a parsed document; before `</head>` for a page with no body
+ * tag, and at the end for a fragment with neither.
+ */
+export function withStaticSnippet(html, connectArgLiteral) {
+    if (hasStaticSnippet(html))
+        return null;
+    const snippet = block(connectArgLiteral);
+    const anchor = BODY_CLOSE.exec(html) ?? HEAD_CLOSE.exec(html);
+    if (null === anchor)
+        return `${html.trimEnd()}\n${snippet}`;
+    // At the start of the closing tag's own line when it sits alone on one, so its indentation stays
+    // with it rather than moving onto the first line of the snippet.
+    const lineStart = html.lastIndexOf('\n', anchor.index - 1) + 1;
+    const at = '' === html.slice(lineStart, anchor.index).trim() ? lineStart : anchor.index;
+    return `${html.slice(0, at)}${snippet}${html.slice(at)}`;
+}

package/dist/patch/tanstack-start.d.ts

@@ -1,17 +1,45 @@
 /**
- * The TanStack Start connect recipe.
+ * The TanStack Start connect: a client-only component, rendered in the document the root route SSRs.
  *
- * Its own module because Start is the one framework whose document module `init` deliberately
- * refuses to write, so the recipe and the reasoning behind that refusal are a unit.
+ * Its own module because Start is the one framework whose document module is ALSO the server
+ * render, so what may be written into it — and what must stay out — is a unit.
  */
+import { type SourcePatch } from './patch-kind.js';
 /** TanStack Start's document module — the file that SSRs `<html>`. */
 export declare const TANSTACK_START_ROOT_PATH = "src/routes/__root.tsx";
 /**
- * The TanStack Start recipe, printed rather than written.
+ * Where the connect component goes: beside the `routes/` directory, never inside it — a file under
+ * `routes/` is a route to Start's file-based router.
+ */
+export declare function tanstackStartConnectPath(rootPath?: string): string;
+/**
+ * The connect component.
+ *
+ * A dynamic SDK import inside `useEffect`, because a static import on anything the root document
+ * imports is evaluated during the server render and 500s the page. Effects never run on the server.
+ * The pairing token is the one the Vite plugin inlines as `__RETICLE_TOKEN__`, declared here so the
+ * file passes the scaffold's strict `tsc` — the recipe this replaced used the name undeclared and
+ * failed with `TS2304: Cannot find name '__RETICLE_TOKEN__'`.
+ *
+ * It also loads the app's `src/reticle-dev.ts` after connecting. Start is written `inject: false`,
+ * and the plugin's injected connect is the only other thing that imports that file, so without this
+ * line every store and capability registered there silently never ran.
+ */
+export declare function tanstackStartConnectFile(port: number | undefined, projectId?: string, rootPath?: string): string;
+/**
+ * Render the component in the root document, just before `<Scripts />`.
+ *
+ * `<Scripts />` is the anchor because every Start root has to render it — it is how the client
+ * bundle reaches the page — whatever the component around it is called (`RootDocument` as the
+ * route's `shellComponent` in the current template; `RootComponent` in older ones). A root without
+ * one is a shape we do not recognise, and a half-edited document is worse than a documented step.
+ */
+export declare function patchTanstackStartRoot(source: string, rootPath: string): SourcePatch;
+/**
+ * The recipe, for a root `patchTanstackStartRoot` would not edit.
  *
- * `__root.tsx` is the document. A static import of the SDK on that module SSRs and 500s, so `init`
- * does not write one. The connect has to be a client-only dynamic import inside `useEffect`, with
- * the pairing token the plugin inlines as `__RETICLE_TOKEN__`. Same judgement React Router already
- * makes about `app/entry.client.tsx`: a half-written document is worse than a documented manual step.
+ * The same two edits it makes, stated as edits: create the component, render it before
+ * `<Scripts />`. It used to say "add this useEffect to the App component", naming a component the
+ * current template does not have, and its snippet used `__RETICLE_TOKEN__` undeclared.
  */
 export declare function tanstackStartManual(port: number | undefined, projectId?: string, rootPath?: string): string;