@reticlehq/init 3.1.0 → 3.3.0

package/dist/patch/snippets.js

@@ -2,9 +2,10 @@
  * Generated file contents and copy-paste snippets for `reticle init`. Kept as named constants/builders
  * so the runner never inlines free strings.
  */
-import { RETICLE_DEFAULT_PORT, ReticleDir, bridgeWsUrl, RETICLE_CLIENT_HOST, RETICLE_WS_PATH, } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, bridgeWsUrl, RETICLE_CLIENT_HOST, RETICLE_WS_PATH, } from '@reticlehq/core';
 import { UiLibrary } from '../detect/detect.js';
 import { RETICLE_VERSION } from '../version.js';
+import { VITE_ENV_DEV_DECLARATION } from './vite-env-types.js';
 /**
  * The SDK as one import a plain page can actually resolve.
  *
@@ -113,11 +114,13 @@ pointers, not the app.`;
   import { reticle } from '@reticlehq/vite-plugin';
 
   export default defineConfig({
-    plugins: [${frameworkPluginExample(uiLibrary)}, ${call}],
+    plugins: [${call}, ${frameworkPluginExample(uiLibrary)}],
   });
 
-Keep \`reticle()\` LAST so it sees the output of your other plugins. It only applies during \`vite\`
-(dev) — it is dropped from \`vite build\`.${note}`;
+The position in the array does not matter: the plugin declares \`enforce: 'pre'\`, so Vite runs it
+before every normal plugin wherever you put it. Shown first only because that is where \`init\`
+writes it when it patches the config for you. It applies during \`vite\` (dev) only — it is dropped
+from \`vite build\`.${note}`;
 }
 /**
  * The electron-vite recipe: the plugin belongs in `renderer`, never in `main` or `preload`.
@@ -202,10 +205,13 @@ export function ReticleDev() {
         // withReticle() finds the daemon serving this project on every dev-server start. It wins over
         // any port written into this file at install time, so moving the daemon needs no edit here.
         const url = process.env.NEXT_PUBLIC_RETICLE_URL;
+        // So a version-skewed pair names the SDK's version instead of "an unknown older wire".
+        const sdkVersion = process.env.NEXT_PUBLIC_RETICLE_SDK_VERSION;
         reticle.connect({
           ${fields}...(url ? { url } : {}),
           ...(token ? { token } : {}),
           ...(root ? { root } : {}),
+          ...(sdkVersion ? { sdkVersion } : {}),
         });
 
         // ── Start with ONE flow. ────────────────────────────────────────────────────────────────
@@ -261,10 +267,9 @@ layoutPath) {
         ? `\n          url: '${bridgeWsUrl(port)}',`
         : '';
     const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
-    // Astro owns its Vite instance, so it has a build-time channel of its own: the same `define` that
-    // already inlines the token can inline the daemon URL, resolved every time the config is read —
-    // that is, on every `astro dev`. The port above is written once at install time and goes stale the
-    // moment the daemon moves; this does not.
+    // Astro owns its Vite instance, so the layout can resolve the daemon URL in frontmatter on every
+    // `astro dev` and put it on a <meta> the client script reads. The port above is written once at
+    // install time and goes stale the moment the daemon moves; this does not.
     //
     // Needs the projectId to know WHICH daemon is ours. Without one there is nothing to match on, and
     // adopting a daemon serving another project would report its state as this app's, so the whole
@@ -274,10 +279,8 @@ layoutPath) {
     // `bridgeWsUrl` builds, and a generator that spells it out by hand is exactly how the four call
     // sites that constant exists to unify drifted apart in the first place.
     const RETICLE_CLIENT_HOST_LITERAL = `ws://${RETICLE_CLIENT_HOST}:`;
-    const urlHelper = canDiscover
+    const urlFrontmatter = canDiscover
         ? `
-  // The live daemon serving THIS project, re-read on every \`astro dev\`. Same rule as the Vite and
-  // Next plugins: skip dead daemons, match on projectId, lowest port wins, '' when none matches.
   function reticleUrl() {
     const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
     let best;
@@ -293,63 +296,77 @@ layoutPath) {
     } catch { return ''; }
     return best === undefined ? '' : '${RETICLE_CLIENT_HOST_LITERAL}' + best + '${RETICLE_WS_PATH}';
   }
+  const pairingUrl = import.meta.env.DEV ? reticleUrl() : '';
 `
         : '';
-    const urlDefine = canDiscover ? `\n        __RETICLE_URL__: JSON.stringify(reticleUrl()),` : '';
+    const urlMeta = canDiscover ? `\n  <meta name="reticle-pairing-url" content={pairingUrl} />` : '';
     const urlRead = canDiscover
-        ? `\n      const url = typeof __RETICLE_URL__ !== 'undefined' ? __RETICLE_URL__ : '';`
+        ? `\n  const url = document.querySelector('meta[name="reticle-pairing-url"]')?.getAttribute('content') ?? '';`
         : '';
-    // After the baked port, so the discovered one wins: later key in an object literal.
-    const urlSpread = canDiscover ? `\n          ...(url.length > 0 ? { url } : {}),` : '';
-    return `Astro renders its own HTML, so the connect goes in a page <script> and the pairing token is inlined by the config.
+    const urlSpread = canDiscover ? `\n    ...(url.length > 0 ? { url } : {}),` : '';
+    return `Astro renders its own HTML, so the connect goes in a local module the page statically imports. Do not put the pairing token through \`vite.define\`: on Astro 7.2+ that substitution never reaches the client, the identifier stays literal, and the bridge refuses the dial. Read the token in frontmatter and put it on a <meta> the module can query. Reading it per request also means a token written after the dev server started is picked up on the next load instead of needing a restart.
 
-1. In astro.config.mjs — inline the daemon's token and raise the build target:
+1. In astro.config.mjs, raise the build target. The token does NOT belong here:
 
-  import { readFileSync, readdirSync } from 'node:fs';
-  import { homedir } from 'node:os';
-  import { join } from 'node:path';
-
-  function reticleToken() {
-    const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
-    try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
-  }
-${urlHelper}
   export default defineConfig({
     vite: {
       // Astro's default target down-levels the modern SDK bundle and fails on a destructuring transform.
       build: { target: 'es2022' },
-      optimizeDeps: { esbuildOptions: { target: 'es2022' } },
-      define: {
-        __RETICLE_TOKEN__: JSON.stringify(reticleToken()),${urlDefine}
-        // Without this, source pointers come back as absolute paths from YOUR machine — useless in a
-        // report. Every other framework gets it from its build plugin; Astro owns its Vite instance.
-        __RETICLE_ROOT__: JSON.stringify(process.cwd()),
-      },
+      optimizeDeps: { include: ['@reticlehq/react'] },
     },
   });
 
 ${layoutHost(layoutPath)}
 
+  ---
+  import { readFileSync${canDiscover ? ', readdirSync' : ''} } from 'node:fs';
+  import { homedir } from 'node:os';
+  import { join } from 'node:path';
+  const pairingToken = (() => {
+    if (!import.meta.env.DEV) return '';
+    const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+    try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+  })();
+  const pairingRoot = import.meta.env.DEV ? process.cwd() : '';${urlFrontmatter}  ---
+  <meta name="reticle-pairing-token" content={pairingToken} />
+  <meta name="reticle-pairing-root" content={pairingRoot} />${urlMeta}
   <script>
+    import connectReticle from '../components/ReticleDev';
     if (import.meta.env.DEV) {
-      const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-      const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';${urlRead}
-      const { reticle, install } = await import('@reticlehq/react');
-      install();
-      reticle.connect({${id}${extra}${urlSpread}
-          ...(token.length > 0 ? { token } : {}),
-          ...(root.length > 0 ? { root } : {}),
-      });
+      connectReticle();
     }
   </script>
 
-3. In src/env.d.ts — declare the Vite define names so \`astro check\` can see them (create-astro's
-   default build runs check first, and without this it fails with Cannot find name '__RETICLE_TOKEN__'):
+  The <script> tag must not sit inside a conditional. Astro hoists them statically, so
+  \`{isDev && (<script />)}\` is never hoisted and the module 404s.
+  The dev gate belongs in the imported module.
 
-  declare const __RETICLE_TOKEN__: string | undefined;
-  declare const __RETICLE_ROOT__: string | undefined;
+3. Create src/components/ReticleDev.ts — Vite owns this file, so the SDK is a static import:
 
-Start the daemon BEFORE \`astro dev\`, so the token file exists when the config is read. Until it does the token is empty and the page reloads once the daemon is up.`;
+  import { reticle, install } from '@reticlehq/react';
+  export default function connectReticle() {
+    const token = document.querySelector('meta[name="reticle-pairing-token"]')?.getAttribute('content') ?? '';
+    const root = document.querySelector('meta[name="reticle-pairing-root"]')?.getAttribute('content') ?? '';${urlRead}
+    if (token.length === 0) {
+      console.warn('[reticle] no pairing token was available when this page rendered, so the app will connect and be refused — you will see NO SESSION even though the SDK loads and the socket opens. The token is written by the Reticle daemon: start it and reload this page.');
+    }
+    install();
+    reticle.connect({${id}${extra}${urlSpread}
+      ...(token.length > 0 ? { token } : {}),
+      ...(root.length > 0 ? { root } : {}),
+    });
+  }
+
+4. In src/env.d.ts — declare the window names so \`astro check\` can see them (create-astro's
+   default build runs check first):
+
+  interface Window {
+    __RETICLE_TOKEN__?: string;
+    __RETICLE_ROOT__?: string;
+  }
+
+Start the daemon, then load the page. The token is read when the page renders, so a reload is enough
+once the token file exists — you do not have to restart \`astro dev\`.`;
 }
 /**
  * The `registerCapabilities` call every generated connect carries.
@@ -422,7 +439,8 @@ ${storeBlock}
     stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
   });
 }
-`;
+
+${VITE_ENV_DEV_DECLARATION}`;
 }
 /** Where that module goes. Matches @reticlehq/vite-plugin's convention list. */
 export const VITE_DEV_MODULE_PATH = 'src/reticle-dev.ts';
@@ -502,7 +520,7 @@ st.html(
  * `<head>`, so the SDK sees a parsed document.
  */
 export function djangoMiddlewareSnippet(connectArgLiteral) {
-    return `# reticle_dev.py — add to MIDDLEWARE while DEBUG is on:
+    return `# reticle_dev.py: add to MIDDLEWARE while DEBUG is on:
 #   MIDDLEWARE = [..., "reticle_dev.ReticleDevMiddleware"]
 from django.conf import settings
 
@@ -682,7 +700,7 @@ export const REACT_ROUTER_ENTRY_PATH = 'app/entry.client.tsx';
 /** The dev-only module @reticlehq/vite-plugin serves: connect() with the token already in it. */
 const RETICLE_CONNECT_MODULE = '/@reticle-connect';
 /** The one line that puts Reticle in a React Router client entry. */
-export const REACT_ROUTER_CONNECT_LINE = `if (import.meta.env.DEV) void import('/@reticle-connect');`;
+const REACT_ROUTER_CONNECT_LINE = `if (import.meta.env.DEV) void import('/@reticle-connect');`;
 /**
  * The client entry `init` writes when React Router framework mode has none.
  *
@@ -735,135 +753,7 @@ export function reactRouterEntryPatch(source) {
     lines.splice(lastImport + 1, 0, REACT_ROUTER_CONNECT_LINE);
     return lines.join('\n');
 }
-/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
-export const NUXT_PLUGIN_PATH = 'app/plugins/reticle.client.ts';
-/**
- * The plugin directory Nuxt actually scans, which is not the same on 3 and 4.
- *
- * Nuxt 4's default `srcDir` is `app/`, so plugins live in `app/plugins/`. Nuxt 3's is the project
- * root, so they live in `plugins/`. Writing to the wrong one is the silent failure this whole change
- * exists to remove: the file is on disk, `init` reports it green, Nuxt never scans that directory,
- * and no plugin is ever registered. Keyed on whether the app HAS an `app/` directory, which is the
- * same signal Nuxt itself uses to pick its srcDir.
- */
-export function nuxtPluginPath(hasAppDir) {
-    return hasAppDir ? NUXT_PLUGIN_PATH : 'plugins/reticle.client.ts';
-}
-/**
- * The dev-only Nuxt client plugin `init` writes.
- *
- * Every trap in it is one somebody actually hit. `import.meta.dev` rather than a hostname check: the
- * reported failure was a snippet guarded on `window.location.hostname === 'localhost'`, which is
- * false on any hosts-file alias or LAN address and throws during SSR, so the connect never ran with
- * no error and no log line. `.client.ts` rather than an SSR guard, because that suffix is what keeps
- * this out of the server bundle. `@reticlehq/browser` rather than the React kit, because installing
- * a package named `@reticlehq/react` into a Vue codebase is the single thing most likely to make
- * somebody abandon the setup.
- *
- * The token is inlined by `nuxt.config`'s `vite.define` (see nuxt-patch.ts). The bridge requires it
- * even on localhost, and nothing in a browser can read the file it lives in.
- */
-export function nuxtPluginFile(port, projectId, testids = []) {
-    const base = connectArg(port, projectId);
-    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
-    return `// Dev-only: connect Reticle from a Nuxt client plugin. Nuxt owns its own Vite instance and
-// renders its own HTML, so the Vite plugin's index.html injection never fires — a .client plugin is
-// the path that can register a session at all.
-export default defineNuxtPlugin(() => {
-  // import.meta.dev is resolved at BUILD time, so it does not care what hostname you develop on.
-  // Do NOT guard on window.location.hostname === 'localhost': that is false on any hosts-file alias
-  // or LAN address, and window does not exist during SSR.
-  if (!import.meta.dev) return;
-  void import('@reticlehq/browser').then(({ reticle, registerCapabilities }) => {
-    // Both inlined by nuxt.config's vite.define, which \`reticle init\` wrote. The bridge refuses a
-    // connect with no token even on localhost; the root makes source paths repo-relative.
-    const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-    const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
-    reticle.connect({
-      ${fields}...(token.length > 0 ? { token } : {}),
-      ...(root.length > 0 ? { root } : {}),
-    });
-
-    // What the agent can drive without guessing. Add a store here too — registerStore('cart',
-    // piniaStore(useCartStore())) — and the agent can check what the app BELIEVES, not just what it
-    // rendered. See node_modules/@reticlehq/server/docs/usage.md.
-${registerCapabilitiesCall(testids, '    ')}
-  });
-});
-
-declare const __RETICLE_TOKEN__: string | undefined;
-declare const __RETICLE_ROOT__: string | undefined;
-`;
-}
-/**
- * Said as its own NOTICE beside the write, not inside it: a running dev server does not pick up a
- * new plugin, and off localhost the connect needs two more arguments.
- *
- * A ✓ line is one SKILL.md tells the reader to skip, so a caveat carried on the ✓ is a caveat nobody
- * reads — and both of these end with an app that boots, looks correct and never pairs.
- */
-export const NUXT_PLUGIN_NOTICE = 'Restart the dev server: one that is already running does not pick up a new plugin — it will not ' +
-    'appear in .nuxt/plugins/client.mjs and the app comes up with no SDK at all. And if your dev host ' +
-    'is anything other than localhost (a hosts-file alias, a LAN IP, a tunnel), that connect call ' +
-    'needs TWO additions, not one: allowNonLocalhost: true AND the token from ~/.reticle/pairing-token. ' +
-    'The flag alone is NOT sufficient off localhost.';
-/**
- * The Nuxt recipe, written out in full because each trap in it is one a Nuxt 4 app actually hit:
- * a Vue codebase classified as `html` and handed `@reticlehq/react`, a connect guarded on
- * `window.location.hostname === 'localhost'` (false on any hosts-file alias, and `window` does not
- * exist during SSR), and a running dev server that never picked up the new plugin.
- *
- * So: `import.meta.dev` instead of a hostname check, `.client.ts` instead of an SSR guard, the
- * framework-neutral sensor instead of the React kit, the non-localhost flag named up front, and the
- * restart said out loud.
- */
-export function nuxtManual(port, projectId) {
-    const base = connectArg(port, projectId);
-    const fields = '' === base ? '' : base.slice(1, -1).trim();
-    const connect = '' === fields ? 'reticle.connect()' : `reticle.connect({ ${fields} })`;
-    return `Nuxt owns its own Vite instance and renders its own HTML, so there is no vite.config to patch
-and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which is Nuxt's own idiom:
-
-1. Create ${NUXT_PLUGIN_PATH}:
-
-     export default defineNuxtPlugin(() => {
-       // import.meta.dev is the correct guard: it is resolved at build time, so it does not care
-       // what hostname you develop on. Do NOT guard on window.location.hostname === 'localhost' —
-       // that is false on any hosts-file alias or LAN address, and window does not exist in SSR.
-       if (!import.meta.dev) return
-       void import('@reticlehq/browser').then(({ reticle }) => {
-         ${connect}
-       })
-     })
-
-   The .client.ts suffix is load-bearing: it is what keeps this out of the server bundle.
-
-2. Restart the dev server. A dev server that is already running does not pick up a new plugin —
-   it will not appear in .nuxt/plugins/client.mjs, and the app will come up with no SDK at all.
-
-3. If your dev host is anything other than localhost (a hosts-file alias, a LAN IP, a tunnel), that
-   connect call needs TWO additions, not one: allowNonLocalhost: true AND a pairing token passed as
-   token. The flag alone is NOT sufficient off localhost. The token is the one in
-   ~/.reticle/pairing-token. Without both, the SDK loads and then refuses, and the only sign is one
-   line in the browser console.
-
-4. Add this to nuxt.config, so the dev server does not watch Reticle's own journal:
-
-     vite: { server: { watch: { ignored: [/(^|[\\\\/])\\.${ReticleDir.ROOT.slice(1)}([\\\\/]|$)/] } } }
-
-   Reticle journals every session into ${ReticleDir.ROOT}/ in your project root, rewriting one file
-   in it continuously while a session is live. Nuxt's dev server watches that root, so without this
-   it sees each write as a project file changing and full-reloads the page — which reconnects the
-   SDK, which produces the next write. The loop runs several times a second and looks like anything
-   except what it is: refs go stale, actions die mid-flight, and the session appears to flap.
-   It is a RegExp rather than a glob on purpose — chokidar dropped glob support in v4, so a
-   double-star pattern here is accepted and matches nothing.
-
-The package is @reticlehq/browser — the framework-neutral sensor. DOM, network, console, routing and
-source file:line all work in Vue. What you do not get is React component identity, which is the only
-thing the React adapter adds. There is no Nuxt app in this project's CI, so this path is UNVERIFIED:
-if something does not work, please open an issue.`;
-}
+export { nuxtPluginPath, nuxtPluginFile, NUXT_PLUGIN_NOTICE, nuxtManual } from './nuxt-snippets.js';
 /**
  * Root-level project config for Reticle. Written by `reticle init`; read by `reticle mcp` for the port
  * and by tooling for the stable projectId (the app's identity across port changes).

package/dist/patch/vite-env-types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The generated dev module must compile even when the host excludes `vite/client` ambient types.
+ * Keep the guard itself as `import.meta.env.DEV` so Vite can remove dev-only code from production.
+ *
+ * These declarations must merge with Vite's existing interfaces: DEV is mutable there, while env
+ * is readonly and refers to the named ImportMetaEnv interface. A triple-slash package reference
+ * would also require vite to be directly resolvable, which electron-vite-only projects need not have.
+ */
+export declare const VITE_ENV_DEV_DECLARATION = "// Supply the dev flag type when the host does not include vite/client.\n// These interfaces merge with vite/client when it is already present.\ndeclare global {\n  interface ImportMetaEnv {\n    DEV: boolean;\n  }\n  interface ImportMeta {\n    readonly env: ImportMetaEnv;\n  }\n}\n";

package/dist/patch/vite-env-types.js

@@ -0,0 +1,19 @@
+/**
+ * The generated dev module must compile even when the host excludes `vite/client` ambient types.
+ * Keep the guard itself as `import.meta.env.DEV` so Vite can remove dev-only code from production.
+ *
+ * These declarations must merge with Vite's existing interfaces: DEV is mutable there, while env
+ * is readonly and refers to the named ImportMetaEnv interface. A triple-slash package reference
+ * would also require vite to be directly resolvable, which electron-vite-only projects need not have.
+ */
+export const VITE_ENV_DEV_DECLARATION = `// Supply the dev flag type when the host does not include vite/client.
+// These interfaces merge with vite/client when it is already present.
+declare global {
+  interface ImportMetaEnv {
+    DEV: boolean;
+  }
+  interface ImportMeta {
+    readonly env: ImportMetaEnv;
+  }
+}
+`;

package/dist/patch/vite-owning-config.d.ts

@@ -21,5 +21,18 @@ export interface ViteOwningConfig {
     readonly defineCall: RegExp;
     /** The SDK package this framework's connect imports, declared so Vite pre-bundles it. */
     readonly sdkSpecifier: string;
+    /**
+     * When true (default), inline the pairing token and project root via `vite.define`.
+     *
+     * Nuxt still needs this: its client plugin reads `__RETICLE_TOKEN__` from the define. Astro 7.2+
+     * no longer substitutes `define` into the client pipeline (#1008), so Astro sets this false and
+     * puts the token on a frontmatter `<meta>` instead.
+     */
+    readonly defineToken?: boolean;
+    /**
+     * Present once this patch has applied. Defaults to `__RETICLE_TOKEN__`, which is what the define
+     * path writes. Astro's path never writes that name into the config, so it supplies its own.
+     */
+    readonly alreadyMarker?: string;
 }
 export declare function patchViteOwningConfig(source: string, config: ViteOwningConfig): SourcePatch;

package/dist/patch/vite-owning-config.js

@@ -18,7 +18,13 @@ import { ReticleDir } from '@reticlehq/core';
 import { blockAfter } from './brace-scan.js';
 import { PatchKind } from './patch-kind.js';
 /** Present in a patched config AND in a hand-followed recipe — so both count as already wired. */
-const CONFIG_MARKER = '__RETICLE_TOKEN__';
+const DEFINE_TOKEN_MARKER = '__RETICLE_TOKEN__';
+function usesDefineToken(config) {
+    return config.defineToken !== false;
+}
+function alreadyMarker(config) {
+    return config.alreadyMarker ?? DEFINE_TOKEN_MARKER;
+}
 /**
  * The SDK, declared so Vite pre-bundles it BEFORE the first page load.
  *
@@ -82,30 +88,36 @@ import { join } from 'node:path';
  * cosmetic: Astro's default down-levels the modern SDK bundle and dies on a destructuring transform.
  */
 function viteKeys(config) {
-    return [
+    const keys = [
         { key: 'build', inner: `\n      target: 'es2022',` },
         {
             key: 'optimizeDeps',
             inner: `\n      include: [${sdkInclude(config)}],\n      esbuildOptions: { target: 'es2022' },`,
         },
-        {
-            key: 'define',
-            inner: `\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),`,
-        },
         // Merged in first, so a `server: { port }` the app already set keeps its port. An app that
         // already sets `server.watch` itself is the one shape this loses to — the inner `watch` key would
         // be duplicated and the app's would win — which is the same nested-merge ceiling `build` has.
         { key: 'server', inner: `\n      watch: { ignored: [${WATCH_IGNORE_LITERAL}] },` },
     ];
+    if (usesDefineToken(config)) {
+        keys.splice(2, 0, {
+            key: 'define',
+            inner: `\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),`,
+        });
+    }
+    return keys;
 }
 /** Whole-key form, for a `vite:` block that does not have the key at all. */
 function wholeKeys(config) {
-    return {
+    const keys = {
         build: `\n    build: { target: 'es2022' },`,
         optimizeDeps: `\n    optimizeDeps: { include: [${sdkInclude(config)}], esbuildOptions: { target: 'es2022' } },`,
-        define: `\n    define: {\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),\n    },`,
         server: `\n    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },`,
     };
+    if (usesDefineToken(config)) {
+        keys.define = `\n    define: {\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),\n    },`;
+    }
+    return keys;
 }
 /**
  * Add our keys to an existing `vite: { ... }` block, merging into any the app already set.
@@ -160,19 +172,34 @@ function withoutInclude(inner, config) {
  * that ran `init`.
  */
 function viteBlock(config) {
-    return `  vite: {
-    build: { target: 'es2022' },
-    optimizeDeps: { include: [${sdkInclude(config)}], esbuildOptions: { target: 'es2022' } },
-    define: {
+    const marker = usesDefineToken(config) ? '' : `    /* ${alreadyMarker(config)} */\n`;
+    const define = usesDefineToken(config)
+        ? `    define: {
       __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
       __RETICLE_ROOT__: JSON.stringify(process.cwd()),
     },
-    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },
+`
+        : '';
+    return `  vite: {
+${marker}    build: { target: 'es2022' },
+    optimizeDeps: { include: [${sdkInclude(config)}], esbuildOptions: { target: 'es2022' } },
+${define}    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },
   },
 `;
 }
+function withHelper(source, config) {
+    if (!usesDefineToken(config)) {
+        return source.endsWith('\n') ? source : `${source}\n`;
+    }
+    return `${HELPER_IMPORTS}${source.trimStart()}\n${HELPER}`.trimEnd() + '\n';
+}
+function withOwningMarker(source, config, braceAt) {
+    if (usesDefineToken(config) || source.includes(alreadyMarker(config)))
+        return source;
+    return insertAt(source, braceAt, `\n    /* ${alreadyMarker(config)} */`);
+}
 export function patchViteOwningConfig(source, config) {
-    if (source.includes(CONFIG_MARKER))
+    if (source.includes(alreadyMarker(config)))
         return { kind: PatchKind.ALREADY };
     // A `vite: { ... }` block is an object literal, so our keys can go straight after the brace and
     // whatever is already in there is untouched. Refusing outright was the only genuine install defect
@@ -186,7 +213,7 @@ export function patchViteOwningConfig(source, config) {
         if (merged !== null) {
             return {
                 kind: PatchKind.APPLY,
-                code: `${HELPER_IMPORTS}${merged.trimStart()}\n${HELPER}`.trimEnd() + '\n',
+                code: withHelper(withOwningMarker(merged, config, at), config),
             };
         }
         return {
@@ -214,6 +241,6 @@ export function patchViteOwningConfig(source, config) {
     const withBlock = `${source.slice(0, at)}\n${viteBlock(config)}${source.slice(at)}`;
     return {
         kind: PatchKind.APPLY,
-        code: `${HELPER_IMPORTS}${withBlock.trimStart()}\n${HELPER}`.trimEnd() + '\n',
+        code: withHelper(withBlock, config),
     };
 }

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

@@ -34,8 +34,9 @@ export declare const StepTitle: {
     readonly SVELTEKIT_UNVERIFIED: "SvelteKit is UNVERIFIED";
     readonly CLIENT_HOOK: "Reticle client hook";
     readonly CONNECT_SNIPPET_ASTRO: "Connect snippet (Astro)";
-    readonly ASTRO_CONFIG: "Astro config (token + build target)";
-    readonly ASTRO_ENV_DTS: "Astro env types (Vite defines)";
+    readonly ASTRO_RETICLE_DEV: "Astro ReticleDev module";
+    readonly ASTRO_CONFIG: "Astro config (build target)";
+    readonly ASTRO_ENV_DTS: "Astro env types (window token)";
     readonly CSP: "Content-Security-Policy";
     readonly CONNECT_SNIPPET: "Connect snippet";
 };

package/dist/plan/connect-steps.js

@@ -35,8 +35,9 @@ export const StepTitle = {
     SVELTEKIT_UNVERIFIED: 'SvelteKit is UNVERIFIED',
     CLIENT_HOOK: 'Reticle client hook',
     CONNECT_SNIPPET_ASTRO: 'Connect snippet (Astro)',
-    ASTRO_CONFIG: 'Astro config (token + build target)',
-    ASTRO_ENV_DTS: 'Astro env types (Vite defines)',
+    ASTRO_RETICLE_DEV: 'Astro ReticleDev module',
+    ASTRO_CONFIG: 'Astro config (build target)',
+    ASTRO_ENV_DTS: 'Astro env types (window token)',
     CSP: CSP_STEP_TITLE,
     CONNECT_SNIPPET: 'Connect snippet',
 };
@@ -54,6 +55,7 @@ export const CONNECT_STEP_TITLES = new Set([
     StepTitle.CONNECT_SNIPPET,
     StepTitle.CONNECT_SNIPPET_CRA,
     StepTitle.CONNECT_SNIPPET_ASTRO,
+    StepTitle.ASTRO_RETICLE_DEV,
     StepTitle.CONNECT_SNIPPET_NUXT,
     // The config is the other half of the Nuxt connect, not a nicety: it is the only thing in a Nuxt
     // app that can inline the pairing token, and the bridge refuses a connect without one even on

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

@@ -24,11 +24,7 @@ import type { PlanInput, Step } from './plan-types.js';
 export declare const RETICLE_REACT_KIT = "@reticlehq/react";
 /** The framework-neutral sensor, for stacks the React adapter has nothing to attach to. */
 export declare const RETICLE_BROWSER_SDK = "@reticlehq/browser";
-export declare const RETICLE_VITE_PLUGIN = "@reticlehq/vite-plugin";
-export declare const RETICLE_NEXT_PLUGIN = "@reticlehq/next";
-/** The Electron main/preload helper — what makes IPC and screenshots exist at all. */
-export declare const RETICLE_ELECTRON = "@reticlehq/electron";
-export interface FrameworkAdapter {
+interface FrameworkAdapter {
     /**
      * The dev dependencies `init` installs, given the kit the UI-library check chose
      * (`@reticlehq/react` or the neutral sensor). A framework that knows its own renderer ignores the
@@ -67,3 +63,4 @@ 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[];
+export {};

package/dist/plan/framework-adapter.js

@@ -29,10 +29,10 @@ import { electronViteSteps } from './plan-electron-vite.js';
 export const RETICLE_REACT_KIT = '@reticlehq/react';
 /** The framework-neutral sensor, for stacks the React adapter has nothing to attach to. */
 export const RETICLE_BROWSER_SDK = '@reticlehq/browser';
-export const RETICLE_VITE_PLUGIN = '@reticlehq/vite-plugin';
-export const RETICLE_NEXT_PLUGIN = '@reticlehq/next';
+const RETICLE_VITE_PLUGIN = '@reticlehq/vite-plugin';
+const RETICLE_NEXT_PLUGIN = '@reticlehq/next';
 /** The Electron main/preload helper — what makes IPC and screenshots exist at all. */
-export const RETICLE_ELECTRON = '@reticlehq/electron';
+const RETICLE_ELECTRON = '@reticlehq/electron';
 export const FRAMEWORK_ADAPTERS = {
     [Framework.NEXT]: {
         // Next is React by construction, so the detection cannot disagree in a way worth honouring.
@@ -92,10 +92,11 @@ export const FRAMEWORK_ADAPTERS = {
     },
     [Framework.ASTRO]: {
         // Astro owns its own Vite instance and renders its own HTML, so there is no config for the
-        // plugin to attach to — the kit alone, connected from a page <script> (see astroManual).
+        // plugin to attach to — the kit alone, connected from a local module the page imports
+        // (see astroManual).
         packages: (kit) => [kit],
         steps: astroSteps,
-        connectStepTitles: [StepTitle.CONNECT_SNIPPET_ASTRO],
+        connectStepTitles: [StepTitle.CONNECT_SNIPPET_ASTRO, StepTitle.ASTRO_RETICLE_DEV],
         carriesOwnUnverifiedNote: false,
     },
     [Framework.ELECTRON_VITE]: {

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

@@ -85,7 +85,7 @@ export declare function reactRouterSteps(input: PlanInput): Step[];
 export declare function tanstackStartSteps(input: PlanInput): Step[];
 export declare function svelteKitSteps(input: PlanInput): Step[];
 /**
- * Astro: the config define + build target, and the connect script in ONE layout.
+ * Astro: the config build target, and the connect script (with the pairing token) in ONE layout.
  *
  * Astro was the last gated stack left printing a recipe it did not apply. It still falls back to the
  * printed one whenever the choice is not obvious — no config, no single layout, or a shape the