@reticlehq/init 3.7.0 → 3.8.0

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

package/dist/patch/static-page.js

@@ -18,11 +18,11 @@
  *   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';
+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) -->';
@@ -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)) {

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,6 +18,7 @@ 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";

package/dist/plan/connect-steps.js

@@ -19,6 +19,7 @@ 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',

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';
@@ -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-framework.js

@@ -28,6 +28,20 @@ const STATIC_TOKEN_DETAIL = `write this machine’s pairing token to ${STATIC_TO
 const STATIC_IGNORE_DETAIL = `add ${STATIC_TOKEN_MODULE} to ${STATIC_GITIGNORE_PATH} — it holds this machine’s pairing token`;
 const STATIC_CONNECT_DETAIL = 'write the dev-only connect snippet (loopback hosts only)';
 const STATIC_CONNECT_ALREADY_DETAIL = `${HTML_INDEX_PATH} already loads the Reticle SDK`;
+/** The package whose presence makes a static page an Electron renderer. */
+const ELECTRON_PACKAGE = 'electron';
+/**
+ * An Electron app often serves its renderer from a local HTTP server, so the packaged app runs on
+ * `localhost` on every user's machine. The localhost-only guard then lets the snippet run in
+ * production, and a packager glob such as `**\/*.js` can ship the token module.
+ */
+const ELECTRON_STATIC_DETAIL = `This is an Electron app. Its packaged renderer can also run on localhost, so init did not ` +
+    `write the localhost-only snippet into ${HTML_INDEX_PATH} or the ${STATIC_TOKEN_MODULE} token ` +
+    'module. Connect only in development: for example, send `!app.isPackaged` from the main ' +
+    'process to the renderer, and call `reticle.connect()` only when it is true. Use ' +
+    `@reticlehq/electron for IPC and capture. If ${STATIC_TOKEN_MODULE} is in the project, keep ` +
+    `it out of the package: electron-builder \`files: ["!${STATIC_TOKEN_MODULE}"]\`, or Electron ` +
+    `Forge \`packagerConfig.ignore: [/${STATIC_TOKEN_MODULE.replaceAll('.', '\\.')}$/]\`.`;
 /**
  * Turn a conservative source patch into a step: applied when it patched, already when the wiring is
  * there, and the hand-edit instructions when the file shape wasn't one we recognise.
@@ -60,15 +74,21 @@ export function patchStep(title, path, patch, applyDetail, manualDetail) {
  */
 /** The env var withReticle sets from the discovered daemon, and the component must read. */
 const NEXT_DAEMON_URL_ENV = 'NEXT_PUBLIC_RETICLE_URL';
+const NEXT_SDK_VERSION_ENV = 'NEXT_PUBLIC_RETICLE_SDK_VERSION';
 /**
  * The two-line edit that unfreezes an existing install's port.
  *
  * Stated as the edit rather than as a problem, because the reader is an agent that can apply it in
  * one write and is otherwise going to ask what to do.
  */
-const NEXT_DEV_FILE_STALE_DETAIL = 'predates daemon discovery, so it dials the port init saw when it ran. In this file add ' +
+const NEXT_DEV_FILE_STALE_DETAIL_SOLO = 'predates daemon discovery, so it dials the port init saw when it ran. In this file add ' +
     '`const url = process.env.NEXT_PUBLIC_RETICLE_URL;` and spread `...(url ? { url } : {})` into ' +
     'reticle.connect(), after any url already there. Nothing else needs to change.';
+const NEXT_DEV_FILE_STALE_DETAIL_DUAL = 'predates daemon discovery, so it dials the port init saw when it ran. In this file add ' +
+    '`const url = process.env.NEXT_PUBLIC_RETICLE_URL;` and spread `...(url ? { url } : {})` into ' +
+    'reticle.connect(), after any url already there.';
+const NEXT_SDK_VERSION_DETAIL = 'lacks the SDK version. In this file add `const sdkVersion = process.env.NEXT_PUBLIC_RETICLE_SDK_VERSION;` ' +
+    'and spread `...(sdkVersion ? { sdkVersion } : {})` into the reticle.connect() options.';
 export function nextSteps(input) {
     const configFile = input.nextConfigFile ?? 'next.config.mjs';
     const devPath = input.nextReticleDevPath ?? NEXT_RETICLE_DEV_PATH;
@@ -82,34 +102,52 @@ export function nextSteps(input) {
     const devStale = true === input.nextReticleDevExists &&
         'string' === typeof input.nextReticleDevSource &&
         !input.nextReticleDevSource.includes(NEXT_DAEMON_URL_ENV);
-    const devFile = input.nextReticleDevExists
-        ? devStale
-            ? {
+    const sdkVersionMissing = true === input.nextReticleDevExists &&
+        'string' === typeof input.nextReticleDevSource &&
+        !input.nextReticleDevSource.includes(NEXT_SDK_VERSION_ENV);
+    const baseDevStep = devStale
+        ? {
+            title: StepTitle.RETICLE_DEV_COMPONENT,
+            target: devPath,
+            status: StepStatus.MANUAL,
+            detail: sdkVersionMissing
+                ? `${NEXT_DEV_FILE_STALE_DETAIL_DUAL} Also ${NEXT_SDK_VERSION_DETAIL}`
+                : NEXT_DEV_FILE_STALE_DETAIL_SOLO,
+        }
+        : alreadyOrMovedPort({
+            title: StepTitle.RETICLE_DEV_COMPONENT,
+            target: devPath,
+            status: StepStatus.ALREADY,
+            detail: 'file exists',
+        }, input.nextReticleDevSource, input.options.port);
+    const devNoticeSteps = !devStale && sdkVersionMissing
+        ? [
+            {
                 title: StepTitle.RETICLE_DEV_COMPONENT,
                 target: devPath,
-                status: StepStatus.MANUAL,
-                detail: NEXT_DEV_FILE_STALE_DETAIL,
-            }
-            : alreadyOrMovedPort({
+                status: StepStatus.NOTICE,
+                detail: NEXT_SDK_VERSION_DETAIL,
+            },
+        ]
+        : [];
+    const devFileSteps = input.nextReticleDevExists
+        ? [baseDevStep, ...devNoticeSteps]
+        : [
+            {
                 title: StepTitle.RETICLE_DEV_COMPONENT,
                 target: devPath,
-                status: StepStatus.ALREADY,
-                detail: 'file exists',
-            }, input.nextReticleDevSource, input.options.port)
-        : {
-            title: StepTitle.RETICLE_DEV_COMPONENT,
-            target: devPath,
-            status: StepStatus.APPLY,
-            detail: 'create dev-only connect component',
-            write: {
-                path: devPath,
-                content: nextReticleDevFile(input.options.port, input.options.projectId, input.testids ?? [], input.storeHints ?? [], 
-                // Next's dev module is not a sibling of `src/` — its imports are resolved from wherever
-                // the component actually lands (`app/`, or `src/app/` in a --src-dir app).
-                input.nextFoundStores ?? []),
+                status: StepStatus.APPLY,
+                detail: 'create dev-only connect component',
+                write: {
+                    path: devPath,
+                    content: nextReticleDevFile(input.options.port, input.options.projectId, input.testids ?? [], input.storeHints ?? [], 
+                    // Next's dev module is not a sibling of `src/` — its imports are resolved from wherever
+                    // the component actually lands (`app/`, or `src/app/` in a --src-dir app).
+                    input.nextFoundStores ?? []),
+                },
+                dependsOnInstall: true,
             },
-            dependsOnInstall: true,
-        };
+        ];
     const configPatch = null === input.nextConfigSource || input.nextConfigSource === undefined
         ? { kind: PatchKind.MANUAL, reason: `no ${configFile} found` }
         : patchNextConfig(input.nextConfigSource, true !== input.detection?.customReconciler);
@@ -141,11 +179,26 @@ export function nextSteps(input) {
             },
         ]
         : [];
+    // Each route-group root layout renders only its own routes, so one mount covers one group: the
+    // routes under the other root layouts render without ReticleDev, and saying nothing about them
+    // would read as an app that is fully wired.
+    const unmounted = input.nextUnmountedLayouts ?? [];
+    const otherRootLayouts = null !== layout && 0 < unmounted.length
+        ? [
+            {
+                title: StepTitle.ROUTE_GROUPS_WITHOUT_RETICLE_DEV,
+                target: unmounted.join(', '),
+                status: StepStatus.NOTICE,
+                detail: `<ReticleDev /> is mounted in ${layout.path} only; ${unmounted.join(', ')} ${1 === unmounted.length ? 'is a root layout' : 'are root layouts'} of ${1 === unmounted.length ? 'its' : 'their'} own, so the routes under ${1 === unmounted.length ? 'it' : 'them'} render without it and Reticle sees nothing there. Mount it there too (dev-only) to cover them.`,
+            },
+        ]
+        : [];
     return [
-        devFile,
+        ...devFileSteps,
         ...nextTodo,
         patchStep(StepTitle.NEXT_CONFIG, configFile, configPatch, 'wrap the export in withReticle (source mapping, dev-only)', nextConfigManual(configFile, true !== input.detection?.customReconciler)),
         patchStep(StepTitle.MOUNT_RETICLE_DEV, layout?.path ?? NEXT_LAYOUT_PATH, layoutPatch, 'mount <ReticleDev /> in the root layout (dev-only)', NEXT_LAYOUT_MANUAL),
+        ...otherRootLayouts,
     ];
 }
 /**
@@ -529,6 +582,16 @@ export function astroSteps(input) {
         patchStep(StepTitle.ASTRO_ENV_DTS, ASTRO_ENV_DTS_PATH, envPatch, 'declare window.__RETICLE_TOKEN__ / __RETICLE_ROOT__ for astro check', manualWithLayout),
     ];
 }
+/** Write the gitignored module that holds this machine's pairing token, and its ignore line. */
+function staticTokenSteps(input) {
+    return Object.entries(staticTokenFiles(input.pairingToken, (path) => input.htmlLocalSources?.[path] ?? null)).map(([path, content]) => ({
+        title: StepTitle.STATIC_PAIRING_TOKEN,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: STATIC_GITIGNORE_PATH === path ? STATIC_IGNORE_DETAIL : STATIC_TOKEN_DETAIL,
+        write: { path, content },
+    }));
+}
 /**
  * The plain-HTML path: write the static connect when the page exists, otherwise print the recipe.
  *
@@ -537,17 +600,21 @@ export function astroSteps(input) {
  * where the if/else chain this replaced used to hand it these instructions silently.
  */
 export function htmlSteps(input) {
+    if (input.detection.dependencies?.[ELECTRON_PACKAGE] !== undefined) {
+        return [
+            {
+                title: StepTitle.CONNECT_SNIPPET,
+                target: HTML_INDEX_PATH,
+                status: StepStatus.MANUAL,
+                detail: ELECTRON_STATIC_DETAIL,
+            },
+        ];
+    }
     const index = input.htmlIndexSource ?? null;
     if (null !== index) {
         // The page is publishable; the pairing token belongs in its gitignored sibling module instead.
         // Refresh that module even when the connect block itself is already in place.
-        const steps = Object.entries(staticTokenFiles(input.pairingToken, (path) => input.htmlLocalSources?.[path] ?? null)).map(([path, content]) => ({
-            title: StepTitle.STATIC_PAIRING_TOKEN,
-            target: path,
-            status: StepStatus.APPLY,
-            detail: STATIC_GITIGNORE_PATH === path ? STATIC_IGNORE_DETAIL : STATIC_TOKEN_DETAIL,
-            write: { path, content },
-        }));
+        const steps = staticTokenSteps(input);
         const written = withStaticSnippet(index, connectArg(input.options.port, input.options.projectId));
         return [
             ...steps,
@@ -568,6 +635,8 @@ export function htmlSteps(input) {
         ];
     }
     return [
+        // The manual snippet imports the token from this module rather than printing it.
+        ...staticTokenSteps(input),
         {
             title: StepTitle.CONNECT_SNIPPET,
             target: HTML_INDEX_PATH,