@reticlehq/init 3.6.0 → 3.8.0

package/dist/patch/snippets.d.ts

@@ -35,19 +35,16 @@ export declare const CDN_SDK_URL: string;
  * (so the app is identifiable across port changes). Empty string only when neither applies.
  */
 export declare function connectArg(port: number | undefined, projectId?: string): string;
+/** The gitignored module beside the page that holds this machine's pairing token. */
+export declare const LOCAL_TOKEN_MODULE = "reticle.local.js";
 /**
- * The same literal, with the pairing token folded in.
+ * A connect literal with `token` set to a JS expression, never to the token itself.
  *
- * The token belongs INSIDE the call the user pastes. Every other stack has a build step to inline
- * it (the Vite plugin's `define`, Next's NEXT_PUBLIC_*, Astro's config, CRA's .env); the hand-wired
- * paths have none, so `init` inlines the literal it already read. Without it the bridge closes the
- * socket with AUTH_FAILED and no session ever appears: see Bridge's hello handler.
- *
- * An empty token is omitted rather than emitted as `token: ''`. A daemon that could not write to
- * $HOME runs without auth and trusts loopback, and an empty string would fail the comparison against
- * one that does hold a token.
+ * The token used to be a literal in every printed snippet. It then stayed in terminal history,
+ * in agent transcripts, and in every file the snippet was pasted into. The snippets now read it at
+ * run time: from the gitignored module, or, in Python, from the token file.
  */
-export declare function connectArgWithToken(port: number | undefined, projectId: string | undefined, pairingToken: string | undefined): string;
+export declare function withTokenExpression(connectArgLiteral: string, tokenExpression: string): string;
 export declare function usesReactKit(uiLibrary: UiLibrary, framework?: Framework): boolean;
 /**
  * Which SDK package the GENERATED code should import, and whether `install()` applies.
@@ -152,26 +149,8 @@ export declare const NEXT_LAYOUT_MANUAL = "Mount <ReticleDev /> in your root lay
  * opposite sign, so the two share a builder rather than a copy.
  */
 export declare function staticPageSnippet(connectArgLiteral: string): string;
-/**
- * Streamlit has no served HTML template, and `st.markdown` inserts script markup without executing
- * it. Streamlit 1.63 added an explicit JavaScript boundary to `st.html`; use a classic script there
- * so it can dynamically import the ESM SDK in the app document. A head marker makes reruns
- * idempotent and is removed after an import failure so the next rerun can retry.
- */
-export declare function streamlitPageSnippet(connectArgLiteral: string): string;
-/**
- * DEBUG-only middleware that injects Reticle into every Django-rendered page.
- *
- * Django serves templates, so the generic script tag has no single home: an app has many templates
- * and a base template it may not have. Middleware has exactly one, runs for every page, and is the
- * idiomatic Django answer — a field reporter arrived at this same shape by hand after `init` printed
- * a script tag and exited 1, and had to write the middleware and `.reticle.json` themselves.
- *
- * Guarded on `settings.DEBUG` so it can never reach production, and on the response being HTML so it
- * does not corrupt a JSON API response or a file download. Injected before `</body>` rather than in
- * `<head>`, so the SDK sees a parsed document.
- */
-export declare function djangoMiddlewareSnippet(connectArgLiteral: string): string;
+/** The same snippet, with the token read from the gitignored module beside the page. */
+export declare function staticPageSnippetWithLocalToken(connectArgLiteral: 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";
@@ -182,7 +161,7 @@ export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
  * reporting all-green.
  */
 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 SVELTEKIT_SETUP_GATED_NOTE = "The install gate scaffolds a SvelteKit app whenever the install path changes 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

package/dist/patch/snippets.js

@@ -46,24 +46,21 @@ export function connectArg(port, projectId) {
         parts.push(`projectId: '${projectId}'`);
     return parts.length > 0 ? `{ ${parts.join(', ')} }` : '';
 }
+/** The gitignored module beside the page that holds this machine's pairing token. */
+export const LOCAL_TOKEN_MODULE = 'reticle.local.js';
+/** The token as the printed and written snippets read it, from the module they import. */
+const LOCAL_TOKEN_EXPR = 'local.token';
 /**
- * The same literal, with the pairing token folded in.
+ * A connect literal with `token` set to a JS expression, never to the token itself.
  *
- * The token belongs INSIDE the call the user pastes. Every other stack has a build step to inline
- * it (the Vite plugin's `define`, Next's NEXT_PUBLIC_*, Astro's config, CRA's .env); the hand-wired
- * paths have none, so `init` inlines the literal it already read. Without it the bridge closes the
- * socket with AUTH_FAILED and no session ever appears: see Bridge's hello handler.
- *
- * An empty token is omitted rather than emitted as `token: ''`. A daemon that could not write to
- * $HOME runs without auth and trusts loopback, and an empty string would fail the comparison against
- * one that does hold a token.
+ * The token used to be a literal in every printed snippet. It then stayed in terminal history,
+ * in agent transcripts, and in every file the snippet was pasted into. The snippets now read it at
+ * run time: from the gitignored module, or, in Python, from the token file.
  */
-export function connectArgWithToken(port, projectId, pairingToken) {
-    const base = connectArg(port, projectId);
-    if (pairingToken === undefined || 0 === pairingToken.length)
-        return base;
-    const inner = base.length > 0 ? base.slice(1, -1).trim() : '';
-    return `{ ${[inner, `token: '${pairingToken}'`].filter((p) => p.length > 0).join(', ')} }`;
+export function withTokenExpression(connectArgLiteral, tokenExpression) {
+    return '' === connectArgLiteral
+        ? `{ token: ${tokenExpression} }`
+        : `{ ...${connectArgLiteral}, token: ${tokenExpression} }`;
 }
 /**
  * Does this codebase want the React kit, or the framework-neutral sensor? The ONE answer, read by
@@ -537,104 +534,44 @@ export function staticPageSnippet(connectArgLiteral) {
         reticle.connect(${connectArgLiteral});
       </script>`;
 }
-/**
- * Streamlit has no served HTML template, and `st.markdown` inserts script markup without executing
- * it. Streamlit 1.63 added an explicit JavaScript boundary to `st.html`; use a classic script there
- * so it can dynamically import the ESM SDK in the app document. A head marker makes reruns
- * idempotent and is removed after an import failure so the next rerun can retry.
- */
-export function streamlitPageSnippet(connectArgLiteral) {
-    return `import streamlit as st
-
-st.html(
-    """
-    <script>
-      (() => {
-        if (document.getElementById('reticle-streamlit-connect')) return;
-        const marker = document.createElement('meta');
-        marker.id = 'reticle-streamlit-connect';
-        document.head.appendChild(marker);
-        void import('${CDN_SDK_URL}')
-          .then(({ reticle }) => reticle.connect(${connectArgLiteral}))
-          .catch((error) => {
-            marker.remove();
-            throw error;
-          });
-      })();
-    </script>
-    """,
-    unsafe_allow_javascript=True,
-)`;
-}
-/**
- * DEBUG-only middleware that injects Reticle into every Django-rendered page.
- *
- * Django serves templates, so the generic script tag has no single home: an app has many templates
- * and a base template it may not have. Middleware has exactly one, runs for every page, and is the
- * idiomatic Django answer — a field reporter arrived at this same shape by hand after `init` printed
- * a script tag and exited 1, and had to write the middleware and `.reticle.json` themselves.
- *
- * Guarded on `settings.DEBUG` so it can never reach production, and on the response being HTML so it
- * does not corrupt a JSON API response or a file download. Injected before `</body>` rather than in
- * `<head>`, so the SDK sees a parsed document.
- */
-export function djangoMiddlewareSnippet(connectArgLiteral) {
-    return `# reticle_dev.py: add to MIDDLEWARE while DEBUG is on:
-#   MIDDLEWARE = [..., "reticle_dev.ReticleDevMiddleware"]
-from django.conf import settings
-
-_SNIPPET = """<script type="module">
-  import { reticle } from '${CDN_SDK_URL}';
-  reticle.connect(${connectArgLiteral});
-</script>"""
-
-
-class ReticleDevMiddleware:
-    """Inject the Reticle SDK into HTML responses during development only."""
-
-    def __init__(self, get_response):
-        self.get_response = get_response
-
-    def __call__(self, request):
-        response = self.get_response(request)
-        if not settings.DEBUG:
-            return response
-        if "text/html" not in response.get("Content-Type", ""):
-            return response
-        # Streaming responses have no .content to rewrite; leave them alone.
-        if getattr(response, "streaming", False):
-            return response
-        body = response.content.decode(response.charset)
-        if "</body>" not in body:
-            return response
-        response.content = body.replace("</body>", _SNIPPET + "</body>", 1).encode(
-            response.charset
-        )
-        if response.has_header("Content-Length"):
-            response["Content-Length"] = str(len(response.content))
-        return response
-`;
+/** The same snippet, with the token read from the gitignored module beside the page. */
+export function staticPageSnippetWithLocalToken(connectArgLiteral) {
+    return `      <script type="module">
+        Promise.all([
+          import('${CDN_SDK_URL}'),
+          import('./${LOCAL_TOKEN_MODULE}').catch(() => ({})),
+        ]).then(([{ reticle }, local]) => reticle.connect(${withTokenExpression(connectArgLiteral, LOCAL_TOKEN_EXPR)}));
+      </script>`;
 }
 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 base = connectArg(port, projectId);
+    // The token is read from the gitignored module that `init` writes, never printed here.
+    const hasToken = pairingToken !== undefined && 0 < pairingToken.length;
+    const withToken = hasToken ? withTokenExpression(base, LOCAL_TOKEN_EXPR) : base;
     const sdk = sdkImport(uiLibrary, Framework.HTML);
-    const bundledImport = sdk.usesInstall
-        ? `void import('${sdk.specifier}').then(({ reticle, install }) => {
-          install();
+    const install = sdk.usesInstall ? '\n          install();' : '';
+    const names = sdk.usesInstall ? '{ reticle, install }' : '{ reticle }';
+    const bundledImport = hasToken
+        ? `void Promise.all([
+          import('${sdk.specifier}'),
+          import('./${LOCAL_TOKEN_MODULE}').catch(() => ({})),
+        ]).then(([${names}, local]) => {${install}
           reticle.connect(${withToken});
         });`
-        : `void import('${sdk.specifier}').then(({ reticle }) => {
+        : `void import('${sdk.specifier}').then((${names}) => {${install}
           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
-  bridge REJECTS a connect without it ("authentication failed") and no session appears. It is
-  per-machine and local-only, so do not commit it — a teammate's daemon mints their own.`;
+    const tokenNote = hasToken
+        ? `\n\n  \`${LOCAL_TOKEN_MODULE}\` holds this machine's pairing token. Init wrote it at the project root and
+  added it to .gitignore. Change the import path so it points there from your entry module. Keep it:
+  the bridge REJECTS a connect without the token ("authentication failed") and no session appears.
+  It is per-machine, so do not commit it. A teammate runs \`reticle init\` for their own.`
+        : '';
+    const pageSnippet = hasToken ? staticPageSnippetWithLocalToken(base) : staticPageSnippet(base);
     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
@@ -648,7 +585,7 @@ uiLibrary = UiLibrary.UNKNOWN) {
     paste this into the page, in a template you only serve in development. There is nothing to
     install: no npm, no bundler, no package.json.
 
-${staticPageSnippet(withToken)}
+${pageSnippet}
 
   Serving the app on something other than localhost (a hosts-file alias, a LAN IP, a container, a
   tunnel)? You need TWO things, not one: \`allowNonLocalhost: true\` AND a pairing token, passed as
@@ -675,9 +612,9 @@ export function unverifiedUiLibraryNote(library, installGated = false) {
     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} ${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.`;
+    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 whenever the install path changes, so this SETUP is proven; no gate drives it to a verdict, so the drive is not.` : `No CI gate covers ${library}.`} Driven to a verdict in CI: Vite + React and Next.js; Astro is checked for a connected session. If something doesn't work, 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 SVELTEKIT_SETUP_GATED_NOTE = 'The install gate scaffolds a SvelteKit app whenever the install path changes 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

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

@@ -22,6 +22,7 @@
 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";
+export declare const STATIC_GITIGNORE_PATH = ".gitignore";
 /** 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. */

package/dist/patch/static-page.js

@@ -18,12 +18,12 @@
  *   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';
+import { CDN_SDK_URL, LOCAL_TOKEN_MODULE, withTokenExpression } 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';
+export const STATIC_TOKEN_MODULE = LOCAL_TOKEN_MODULE;
+export const STATIC_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 -->';
@@ -42,9 +42,7 @@ export function hasStaticSnippet(html) {
 }
 function block(connectArgLiteral) {
     const hosts = LOOPBACK_HOSTS.map((h) => `'${h}'`).join(', ');
-    const arg = '' === connectArgLiteral
-        ? '{ token: local.token }'
-        : `{ ...${connectArgLiteral}, token: local.token }`;
+    const arg = withTokenExpression(connectArgLiteral, 'local.token');
     return `    ${STATIC_SNIPPET_MARKER}
     <script type="module">
       if ([${hosts}].includes(location.hostname)) {
@@ -71,12 +69,12 @@ export function staticTokenFiles(pairingToken, readFile) {
     const module = staticTokenModule(pairingToken);
     if (readFile(STATIC_TOKEN_MODULE) !== module)
         files[STATIC_TOKEN_MODULE] = module;
-    const ignore = readFile(GITIGNORE_PATH) ?? '';
+    const ignore = readFile(STATIC_GITIGNORE_PATH) ?? '';
     const covered = ignore
         .split('\n')
         .some((l) => [STATIC_TOKEN_MODULE, `/${STATIC_TOKEN_MODULE}`].includes(l.trim()));
     if (!covered) {
-        files[GITIGNORE_PATH] =
+        files[STATIC_GITIGNORE_PATH] =
             `${'' === ignore ? '' : ignore.replace(/\n*$/, '\n')}${STATIC_TOKEN_MODULE}\n`;
     }
     return files;

package/dist/patch/vite-config.js

@@ -44,6 +44,12 @@ function reticlePluginCall(opts) {
 }
 /** Matches the start of a `plugins: [` array literal. */
 const PLUGINS_ARRAY = /plugins\s*:\s*\[/;
+/**
+ * A `plugins` key in any shape: `plugins: <expr>`, or the shorthand `{ plugins }`. When this holds
+ * and PLUGINS_ARRAY does not, the key is there but not as an array literal, so adding our own key
+ * would make a second one. The later key wins, and one of the two lists is lost.
+ */
+const PLUGINS_KEY = /\bplugins\s*[:,}]/;
 /** Matches an ES import statement (used to place our import after the last one). */
 const IMPORT_LINE = /^import\s.+from\s+['"][^'"]+['"];?\s*$/gm;
 /**
@@ -59,6 +65,8 @@ const CONFIG_OBJECT = /(export\s+default\s+(?:defineConfig\s*\(\s*)?)\{/;
 /** Alias kept so existing call sites read in Vite terms; the vocabulary is shared (see patch-kind). */
 export const VitePatchKind = PatchKind;
 const NO_PLUGINS_REASON = "couldn't find a `plugins: [...]` array to extend";
+const PLUGINS_NOT_ARRAY_REASON = 'the `plugins` key is not an array literal, so init did not change it. Add `reticle()` to the ' +
+    'list that the key builds. Do not add a second `plugins` key: the later key replaces the first.';
 function insertImport(source) {
     const matches = [...source.matchAll(IMPORT_LINE)];
     const last = matches[matches.length - 1];
@@ -114,6 +122,9 @@ export function patchViteConfig(source, port, captureBodies = false, inject = tr
     if (PLUGINS_ARRAY.test(source)) {
         return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, call)) };
     }
+    if (PLUGINS_KEY.test(source)) {
+        return { kind: VitePatchKind.MANUAL, reason: PLUGINS_NOT_ARRAY_REASON };
+    }
     if (CONFIG_OBJECT.test(source)) {
         return { kind: VitePatchKind.APPLY, code: insertImport(insertPluginsKey(source, call)) };
     }

package/dist/plan/connect-steps.d.ts

@@ -18,9 +18,11 @@ export declare const StepTitle: {
     readonly RETICLE_DEV_COMPONENT: "ReticleDev component";
     readonly NEXT_CONFIG: "Next config (withReticle)";
     readonly MOUNT_RETICLE_DEV: "Mount ReticleDev";
+    readonly ROUTE_GROUPS_WITHOUT_RETICLE_DEV: "Route groups without ReticleDev";
     readonly CONNECT_MODULE: "Reticle connect module";
     readonly PAIRING_TOKEN: "Pairing token";
     readonly PAIRING_TOKEN_PER_MACHINE: "Pairing token is per-machine";
+    readonly STATIC_PAIRING_TOKEN: "Pairing token (static page)";
     readonly CONNECT_SNIPPET_CRA: "Connect snippet (CRA)";
     readonly CONNECT_SNIPPET_NUXT: "Connect snippet (Nuxt)";
     readonly NUXT_CONFIG: "Nuxt config (token + watcher)";

package/dist/plan/connect-steps.js

@@ -19,9 +19,11 @@ export const StepTitle = {
     RETICLE_DEV_COMPONENT: 'ReticleDev component',
     NEXT_CONFIG: 'Next config (withReticle)',
     MOUNT_RETICLE_DEV: 'Mount ReticleDev',
+    ROUTE_GROUPS_WITHOUT_RETICLE_DEV: 'Route groups without ReticleDev',
     CONNECT_MODULE: 'Reticle connect module',
     PAIRING_TOKEN: 'Pairing token',
     PAIRING_TOKEN_PER_MACHINE: 'Pairing token is per-machine',
+    STATIC_PAIRING_TOKEN: 'Pairing token (static page)',
     CONNECT_SNIPPET_CRA: 'Connect snippet (CRA)',
     CONNECT_SNIPPET_NUXT: 'Connect snippet (Nuxt)',
     NUXT_CONFIG: 'Nuxt config (token + watcher)',
@@ -98,6 +100,10 @@ export const CONNECT_STEP_TITLES = new Set([
     // not, and `gate:install` scaffolds no CRA app, so that change would ship with no coverage of the
     // path it changes. It is worth doing, and worth doing with a scaffold behind it.
     StepTitle.VITE_PLUGIN,
+    // A plain page imports its token from a gitignored sibling module. Unlike CRA's, this step never
+    // goes MANUAL by plan: it is ⚠ only when the write itself failed — no token module means the page
+    // is refused, and no ignore entry means the token is on disk without the protection we promised.
+    StepTitle.STATIC_PAIRING_TOKEN,
     // electron-vite's connect IS the renderer plugin. Without it the SDK never injects, and the
     // preload/capture steps are not enough to produce a session.
     StepTitle.ELECTRON_VITE_PLUGIN,

package/dist/plan/framework-adapter.d.ts

@@ -65,4 +65,14 @@ export declare const FRAMEWORK_ADAPTERS: Record<Framework, FrameworkAdapter>;
  * for the packages, the connect-step titles and the unverified-note flag in the same edit.
  */
 export declare function frameworkSteps(input: PlanInput): Step[];
+/**
+ * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
+ *
+ * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
+ * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
+ * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
+ * right after `init` had detected the real UI library and said so on screen.
+ */
+export declare function frameworkPackages(framework: Framework, uiLibrary?: UiLibrary): readonly string[];
+export declare function installStep(input: PlanInput): Step;
 export {};

package/dist/plan/framework-adapter.js

@@ -18,7 +18,10 @@
  *
  * `framework-adapter.test.ts` asserts the seam between the two halves.
  */
-import { Framework, UiLibrary } from '../detect/detect.js';
+import { Framework, UiLibrary, installCommand, installCommandParts } from '../detect/detect.js';
+import { installFailureHint } from '../diagnose/install-hint.js';
+import { installRetries } from '../diagnose/install-retries.js';
+import { usesReactKit } from '../patch/snippets.js';
 import { StepTitle } from './connect-steps.js';
 import { astroSteps, craSteps, htmlSteps, nextSteps, nuxtSteps, reactRouterSteps, svelteKitSteps, tanstackStartSteps, } from './plan-framework.js';
 import { VITE_PLUGIN_DETAIL, viteSteps } from './plan-vite.js';
@@ -223,10 +226,10 @@ export const FRAMEWORK_ADAPTERS = {
         carriesOwnUnverifiedNote: false,
     },
     [Framework.HTML]: {
-        // No bundler plugin to install — just the kit; connect is wired by hand (see htmlManual).
+        // No bundler plugin to install — write the static connect into index.html when it is present.
         packages: (kit) => [kit],
         steps: htmlSteps,
-        connectStepTitles: [StepTitle.CONNECT_SNIPPET],
+        connectStepTitles: [StepTitle.CONNECT_SNIPPET, StepTitle.STATIC_PAIRING_TOKEN],
         carriesOwnUnverifiedNote: false,
     },
 };
@@ -241,3 +244,119 @@ export const FRAMEWORK_ADAPTERS = {
 export function frameworkSteps(input) {
     return FRAMEWORK_ADAPTERS[input.detection.framework].steps(input);
 }
+/**
+ * Pin the SDK to the CLI's own version.
+ *
+ * `pnpm add -D @reticlehq/react` once installed an older release in one project while npm and yarn
+ * took the current one in the next — a stale registry metadata cache, invisible to everyone. A
+ * version-skewed SDK talking to a newer daemon is the `-32000` failure path: the app connects, the
+ * protocol disagrees, and nothing on either side names a version. Asking for the CLI's exact version
+ * makes the cache irrelevant, and a skewed pair impossible to install by accident.
+ */
+function pinnedPackages(packages, version) {
+    if (version === undefined || 0 === version.length) {
+        return packages;
+    }
+    return packages.map((p) => `${p}@${version}`);
+}
+/**
+ * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
+ *
+ * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
+ * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
+ * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
+ * right after `init` had detected the real UI library and said so on screen.
+ */
+export function frameworkPackages(framework, uiLibrary = UiLibrary.UNKNOWN) {
+    const kit = usesReactKit(uiLibrary, framework) ? RETICLE_REACT_KIT : RETICLE_BROWSER_SDK;
+    return FRAMEWORK_ADAPTERS[framework].packages(kit);
+}
+/**
+ * What to say when the install command fails.
+ *
+ * pnpm's `minimumReleaseAge` refuses any release younger than the configured window — a deliberate
+ * supply-chain policy, not a bug — with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`. Unpinned it silently
+ * resolves to an OLDER version instead, which is how an app ends up running a stale SDK against a
+ * newer daemon: the connection succeeds, the protocol disagrees, and the failure surfaces as -32000
+ * with nothing naming a version. Pinning turns that into this loud failure, which is the better
+ * trade — but only if the message says what to do about it.
+ */
+/**
+ * Is this package already declared at the version we would pin?
+ *
+ * The caret is the point. `npm i -D pkg@3.2.0` WRITES `^3.2.0`, so on every later run the pinned
+ * `3.2.0` failed a string comparison against the range npm had just created, and init re-installed
+ * for ever. Only the two forms a package manager writes by itself are read - an exact version, and
+ * `^`/`~` over that same version.
+ *
+ * Everything else installs. A false "already" leaves somebody with no SDK and an install that
+ * claims to have run; a redundant install only costs time, so the unreadable cases go the safe way.
+ */
+function alreadyDeclared(declared, pinned) {
+    if (declared === undefined) {
+        return false;
+    }
+    if (pinned === undefined || 0 === pinned.length) {
+        return true;
+    }
+    return declared === pinned || `^${pinned}` === declared || `~${pinned}` === declared;
+}
+export function installStep(input) {
+    const pm = input.detection.packageManager;
+    // `Detection.packageManagerCommand` (see `preflight.ts`, #1149). Falling back to `pm` covers every
+    // caller that never went through preflight (tests, and any future one).
+    const pmCommand = input.detection.packageManagerCommand ?? pm;
+    const packages = pinnedPackages(frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion);
+    const command = installCommand(pm, packages, pmCommand);
+    /*
+     * A re-run over an already-wired project does NO dependency work.
+     *
+     * Reported from the field: `init` on an instrumented npm-workspaces project ran a pnpm dependency
+     * migration, which moved the existing `node_modules` aside and broke the dev server. Whatever
+     * manager gets chosen, the redundant install is the step that touches the tree — so the fix that
+     * matters is not running one that nothing needs. `init` is documented as idempotent; this is the
+     * step that was not.
+     */
+    const declared = input.detection.dependencies ?? {};
+    const version = input.options.sdkVersion;
+    const names = frameworkPackages(input.detection.framework, input.detection.uiLibrary);
+    if (names.length > 0 && names.every((n) => alreadyDeclared(declared[n], version))) {
+        return {
+            title: 'Install dependencies',
+            target: 'package.json',
+            status: StepStatus.ALREADY,
+            detail: `${names.join(', ')} already declared${version === undefined || 0 === version.length ? '' : ` at ${version}`}`,
+        };
+    }
+    // Never install into a linked tree: the package manager replaces the link (a workspace's tree).
+    if (true === input.nodeModulesLinked) {
+        return {
+            title: 'Install dependencies',
+            target: 'package.json',
+            status: StepStatus.SKIP,
+            detail: `skipped: node_modules is a link to another tree, which an install here would replace; install them where it points: ${command}`,
+        };
+    }
+    // The person said `--no-install`: a choice, not a step left undone, so not a ⚠.
+    if (!input.options.install) {
+        return {
+            title: 'Install dependencies',
+            target: 'package.json',
+            status: StepStatus.SKIP,
+            detail: `skipped (--no-install); install them yourself: ${command}`,
+        };
+    }
+    const parts = installCommandParts(pm, packages, [], pmCommand);
+    return {
+        title: 'Install dependencies',
+        target: 'package.json',
+        status: StepStatus.APPLY,
+        detail: command,
+        exec: {
+            command: parts.command,
+            args: parts.args,
+            fallback: `${command}\n\n${installFailureHint(pm, pmCommand)}`,
+        },
+        retries: installRetries(pm, packages, frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion, pmCommand),
+    };
+}

package/dist/plan/notices.js

@@ -8,7 +8,7 @@
  *
  * They live together because that shared test is a real seam.
  */
-import { CONTAINERISED_TITLE, containerisedDevServerNote } from '../diagnose/containerised-dev-server.js';
+import { CONTAINERISED_TITLE, containerisedDevServerNote, } from '../diagnose/containerised-dev-server.js';
 import { mcpWindowsNote } from '../register/mcp.js';
 import { unverifiedUiLibraryNote, WEBGL_CANVAS_LIMIT_NOTE } from '../patch/snippets.js';
 import { FRAMEWORK_ADAPTERS, installGated } from './framework-adapter.js';

package/dist/plan/plan-angular.js

@@ -9,7 +9,7 @@ import { StepTitle } from './connect-steps.js';
 import { patchStep } from './plan-framework.js';
 import { alreadyOrMovedPort, retargetPort } from './port-steps.js';
 import { StepStatus } from './plan-types.js';
-const ANGULAR_SETUP_GATED_NOTE = 'The install gate scaffolds an Angular app (Angular 21, no SSR) on every release and requires a ' +
+const ANGULAR_SETUP_GATED_NOTE = 'The install gate scaffolds an Angular app (Angular 21, no SSR) whenever the install path changes and requires a ' +
     'session, and this wiring was proven by hand on Angular 22 with and without SSR; nothing yet ' +
     'drives an Angular app to a verdict on each change. DOM, network, console and state ' +
     'tools work here; component identity does not (that is the React adapter). If no session ' +

package/dist/plan/plan-framework.d.ts

@@ -66,7 +66,7 @@ export declare function svelteKitSteps(input: PlanInput): Step[];
  */
 export declare function astroSteps(input: PlanInput): Step[];
 /**
- * The plain-HTML path: no bundler to hook, so the connect snippet is printed for a hand edit.
+ * The plain-HTML path: write the static connect when the page exists, otherwise print the recipe.
  *
  * A function of its own, and NOT a fallthrough. Every framework is sent here on purpose or not at
  * all — a member of `Framework` with no adapter entry is a compile error in `FRAMEWORK_ADAPTERS`,