@reticlehq/vite-plugin 2.4.0 → 2.5.0

package/dist/discover-port.js

@@ -33,7 +33,7 @@ export function discoverDaemonPort(projectId, home = join(homedir(), ReticleDir.
         return undefined; // no ~/.reticle yet
     }
     for (const file of files) {
-        if (daemonRegistryPort(file) === null)
+        if (null === daemonRegistryPort(file))
             continue;
         try {
             const parsed = DaemonRegistryEntrySchema.safeParse(JSON.parse(readFileSync(join(home, file), 'utf8')));

package/dist/ensure-token.d.ts

@@ -0,0 +1 @@
+export declare function ensurePairingToken(dir: string): string | undefined;

package/dist/ensure-token.js

@@ -0,0 +1,47 @@
+/**
+ * Read the pairing token, or create it — whichever process gets there first.
+ *
+ * The token is read ONCE, when Vite resolves its config, and inlined as `__RETICLE_TOKEN__`. The
+ * daemon is what normally writes it. So a dev server started BEFORE the daemon froze an empty
+ * string, every page it served was refused by the bridge, and no session ever appeared — with the
+ * SDK loading and the socket opening, so nothing looked broken. Bisected against a real SvelteKit
+ * fixture, where it presented as a regression.
+ *
+ * Restarting the dev server was the only cure, because by the time the daemon minted a token the
+ * empty value had already been baked in.
+ *
+ * The daemon READS-OR-CREATES this file (see the server's `readOrCreatePairingToken`, kept "stable
+ * across restarts so a plugin-injected page keeps working after the daemon bounces"), so the plugin
+ * doing the same makes the two agree whichever order they start in. Same path, same 0600 mode, same
+ * random generation. An existing token is never replaced: overwriting would invalidate every page
+ * the daemon has already handed one to.
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+/** Matches the server's token size. */
+const TOKEN_BYTES = 32;
+const TOKEN_FILE = 'pairing-token';
+export function ensurePairingToken(dir) {
+    try {
+        const existing = readFileSync(join(dir, TOKEN_FILE), 'utf8').trim();
+        if (existing.length > 0)
+            return existing;
+    }
+    catch {
+        /* missing or unreadable — fall through and create one */
+    }
+    try {
+        const token = randomBytes(TOKEN_BYTES).toString('hex');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const path = join(dir, TOKEN_FILE);
+        writeFileSync(path, token, { encoding: 'utf8', mode: 0o600 });
+        // writeFile keeps a pre-existing looser mode, so set it explicitly — same as the daemon does.
+        chmodSync(path, 0o600);
+        return token;
+    }
+    catch {
+        // A dev server must still start. Degrading to the previous tokenless behaviour is correct.
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -24,6 +24,16 @@ export declare const RENDER_PREHOOK_SOURCE = "(function(){try{\nvar K='__REACT_D
 export interface ReticleVitePluginOptions {
     /** Bridge WebSocket port. Defaults to the SDK default; only baked into connect when non-default. */
     port?: number;
+    /**
+     * Project root, so React's absolute `_debugSource.fileName` reports repo-relative. Resolved from
+     * the Vite config at injection time; set it only to override.
+     */
+    root?: string;
+    /**
+     * The installed SDK's version, so a pair skewed against the daemon can name itself instead of
+     * surfacing as a bare -32000. Read from the installed package; set it only to override.
+     */
+    sdkVersion?: string;
     /** Stable session label for the bridge. Defaults to the SDK's auto-generated id. */
     session?: string;
     /**
@@ -94,9 +104,7 @@ export interface ReticleVitePlugin {
     }) => {
         optimizeDeps: {
             include: string[];
-            esbuildOptions: {
-                define: Record<string, string>;
-            };
+            [optionsKey: string]: unknown;
         };
         define: Record<string, string>;
     };
@@ -129,6 +137,29 @@ interface HtmlTag {
     /** `head-prepend` is required for the render pre-hook: it must run before any module script. */
     injectTo: 'body' | 'head-prepend';
 }
+/**
+ * Name each CJS dep ONLY in the bare form, and only when the app root can resolve it.
+ *
+ * This used to try three layouts and emit Vite's nested `a > b > c` form when a hoisted lookup
+ * failed. The guard asked the wrong question: it tested NODE resolvability, walking the chain
+ * segment by segment, and under pnpm that succeeds exactly where Vite fails. Measured on the
+ * sveltekit fixture:
+ *
+ *   ['@testing-library/dom']                                           -> null
+ *   ['@reticlehq/browser', '@testing-library/dom']                     -> null
+ *   ['@reticlehq/react', '@reticlehq/browser', '@testing-library/dom'] -> emitted
+ *
+ * So we emitted the three-segment chain, Vite could not follow it, and the boot warning this
+ * function exists to prevent appeared anyway — `Failed to resolve dependency: …, present in
+ * optimizeDeps.include`, pointing at Reticle, naming a package the developer has never heard of,
+ * and forcing a full re-optimization on every cold start. The comment stated the rule correctly and
+ * the code broke it.
+ *
+ * Dropping the nested form loses nothing that matters: the SDK itself is still pre-bundled, and Vite
+ * follows its imports when it does that, so these deps are handled as part of it. Naming them
+ * separately was belt-and-braces for a locally-aliased SDK, where the bare form resolves anyway.
+ */
+export declare function cjsDepIncludes(appRoot: string, canResolve?: (dep: string) => boolean): string[];
 export declare function readPairingToken(): string | undefined;
 /** The body of the connect module — real imports, resolved by Vite when the module is served. */
 /**

package/dist/index.js

@@ -1,13 +1,15 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { missingTokenWarning } from './missing-token.js';
+import { ensurePairingToken } from './ensure-token.js';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { transformSync } from '@babel/core';
 import reticleSource from '@reticlehq/babel-plugin';
-import { RETICLE_DEFAULT_PORT, RETICLE_RENDER_PREHOOK, bridgeWsUrl, ReticleDir, ReticleEnv, RETICLE_ROOT_GLOBAL, } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, RETICLE_RENDER_PREHOOK, bridgeWsUrl, ReticleDir, ReticleEnv, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, } from '@reticlehq/core';
 import { resolveProjectId } from './project-id.js';
 import { discoverDaemonPort } from './discover-port.js';
 import { SVELTE_FILE, stampSvelte } from './svelte-source.js';
-import { createRequire } from 'node:module';
+import { resolvableChain, sdkPackageVersion, sdkBuildFingerprint, viteMajor, optimizerOptionsKey, } from './installed.js';
 export const RETICLE_VITE_PLUGIN_NAME = 'reticle';
 // The React kit the host app imports the SDK from. It re-exports the browser sensor, so a single
 // specifier yields both `reticle` (connect) and `install` (the React adapter). NOT `@reticlehq/core`
@@ -19,43 +21,6 @@ const RETICLE_PACKAGE = '@reticlehq/react';
  * file it lives in.
  */
 export const RETICLE_TOKEN_GLOBAL = '__RETICLE_TOKEN__';
-/**
- * Whether a package can be resolved from this process. Used to avoid declaring an optimizeDeps entry
- * for something the app does not have, which Vite reports as a resolve failure on every boot.
- */
-function isResolvable(specifier) {
-    try {
-        createRequire(import.meta.url).resolve(specifier);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * A fingerprint of the installed SDK build, mixed into `optimizeDeps` so Vite re-bundles when the
- * SDK changes.
- *
- * Vite's dep-optimizer cache is keyed on the `optimizeDeps` config and the lockfile — NOT on the
- * contents of the packages it bundled. Upgrade the SDK in place (a patched dist, a linked checkout,
- * an overlay) and the version in `package.json` can stay the same, so Vite keeps serving the OLD
- * pre-bundled copy out of `node_modules/.vite` across dev-server restarts. The fix you just shipped
- * is simply not in the browser, and it looks like the fix does not work. That cost a real
- * false-negative during this bug hunt, and every user upgrading in place hits the same thing.
- *
- * Size+mtime is enough: it changes whenever the bundle does and costs one `stat`.
- */
-function sdkBuildFingerprint() {
-    try {
-        const entry = createRequire(import.meta.url).resolve(RETICLE_PACKAGE);
-        const { size, mtimeMs } = statSync(entry);
-        return `${String(size)}-${String(Math.trunc(mtimeMs))}`;
-    }
-    catch {
-        // Unresolvable (not installed yet, exotic layout) — a constant is still correct, just inert.
-        return 'unknown';
-    }
-}
 /** Files we stamp with source info — JSX/TSX only. */
 const JSX_FILE = /\.[jt]sx$/;
 /** Rollup virtual-module ids start with a NUL byte; never transform those. */
@@ -149,11 +114,11 @@ function stamp(code, id) {
         configFile: false,
         babelrc: false,
     });
-    if (out?.code === undefined || out.code === null)
+    if (out?.code === undefined || null === out.code)
         return null;
     return {
         code: out.code,
-        map: out.map === undefined || out.map === null ? null : JSON.stringify(out.map),
+        map: out.map === undefined || null === out.map ? null : JSON.stringify(out.map),
     };
 }
 /**
@@ -170,16 +135,58 @@ const SDK_CJS_DEPS = {
     TESTING_LIBRARY: '@testing-library/dom',
     ARIA_QUERY: 'aria-query',
 };
+/**
+ * Name each CJS dep ONLY in the bare form, and only when the app root can resolve it.
+ *
+ * This used to try three layouts and emit Vite's nested `a > b > c` form when a hoisted lookup
+ * failed. The guard asked the wrong question: it tested NODE resolvability, walking the chain
+ * segment by segment, and under pnpm that succeeds exactly where Vite fails. Measured on the
+ * sveltekit fixture:
+ *
+ *   ['@testing-library/dom']                                           -> null
+ *   ['@reticlehq/browser', '@testing-library/dom']                     -> null
+ *   ['@reticlehq/react', '@reticlehq/browser', '@testing-library/dom'] -> emitted
+ *
+ * So we emitted the three-segment chain, Vite could not follow it, and the boot warning this
+ * function exists to prevent appeared anyway — `Failed to resolve dependency: …, present in
+ * optimizeDeps.include`, pointing at Reticle, naming a package the developer has never heard of,
+ * and forcing a full re-optimization on every cold start. The comment stated the rule correctly and
+ * the code broke it.
+ *
+ * Dropping the nested form loses nothing that matters: the SDK itself is still pre-bundled, and Vite
+ * follows its imports when it does that, so these deps are handled as part of it. Naming them
+ * separately was belt-and-braces for a locally-aliased SDK, where the bare form resolves anyway.
+ */
+export function cjsDepIncludes(appRoot, 
+// Injected so the rule can be tested hermetically. Real module resolution is not: under vitest,
+// `createRequire` from a directory that does not exist still resolves packages out of the runner's
+// own graph, so a filesystem-based test of "nothing is reachable here" silently asserts nothing.
+canResolve = (dep) => null !== resolvableChain([dep], appRoot)) {
+    return [SDK_CJS_DEPS.TESTING_LIBRARY, SDK_CJS_DEPS.ARIA_QUERY].filter(canResolve);
+}
 export function readPairingToken() {
     const override = process.env[ReticleEnv.PAIRING_TOKEN_DIR];
     const dir = override !== undefined && override.length > 0 ? override : join(homedir(), ReticleDir.ROOT);
-    try {
-        const token = readFileSync(join(dir, ReticleDir.PAIRING_TOKEN_FILE), 'utf8').trim();
-        return token.length > 0 ? token : undefined;
-    }
-    catch {
-        return undefined;
+    // Read-or-CREATE, matching the daemon. Reading alone meant a dev server started before the daemon
+    // baked in an empty token and every page it served was refused — with the SDK loading and the
+    // socket opening, so nothing looked broken. See ensure-token for the bisect.
+    return ensurePairingToken(dir);
+}
+/**
+ * Pass the token through, saying so once when it is absent.
+ *
+ * Warned HERE rather than at connect time because this is the moment the value is frozen: by the
+ * time the app is refused, the empty string was inlined minutes ago and restarting the dev server is
+ * the only fix. Once per config resolve, so a watch-mode rebuild does not repeat it.
+ */
+let tokenWarned = false;
+function warnIfTokenMissing(token) {
+    const warning = missingTokenWarning(token);
+    if (warning !== undefined && !tokenWarned) {
+        tokenWarned = true;
+        console.warn(warning);
     }
+    return token;
 }
 /** Build the `reticle.connect` argument literal — only includes keys the user set. */
 function connectArgs(options) {
@@ -193,14 +200,24 @@ function connectArgs(options) {
         args['projectId'] = options.projectId;
     if (options.token !== undefined)
         args['token'] = options.token;
+    // Passed as connect ARGUMENTS, not as a `define`. A define substitutes a bare identifier in the
+    // source it transforms; the SDK reads these as `globalThis[NAME]`, a dynamic lookup no define can
+    // ever reach — so defining them looked right, shipped, and did nothing. Baking them into the
+    // generated connect call is a literal in generated source: no bundler subtleties, works the same
+    // in dev and in a desktop build.
+    if (options.root !== undefined && options.root.length > 0)
+        args['root'] = options.root;
+    if (options.sdkVersion !== undefined && options.sdkVersion.length > 0) {
+        args['sdkVersion'] = options.sdkVersion;
+    }
     // A desktop renderer is a production build by construction; without this the SDK's prod backstop
     // refuses to connect and the app is silently uninstrumented.
-    if (options.desktop === true)
+    if (true === options.desktop)
         args['allowInProduction'] = true;
     // Env wins nothing — it only turns the flag ON, so a config that never set it can still be
     // switched on for one debugging session without editing vite.config and restarting the mental
     // model with it.
-    if (options.captureNetworkBodies === true || process.env['VITE_RETICLE_CAPTURE_BODIES'] === '1') {
+    if (true === options.captureNetworkBodies || '1' === process.env['VITE_RETICLE_CAPTURE_BODIES']) {
         args['captureNetworkBodies'] = true;
     }
     return Object.keys(args).length > 0 ? JSON.stringify(args) : '';
@@ -233,7 +250,7 @@ export function connectModuleSource(options, devModule = null) {
     const base = `import { reticle, install } from '${RETICLE_PACKAGE}';\ninstall();\nreticle.connect(${args});\n`;
     // AFTER connect: registerStore subscribes through the live SDK, and registering before there is a
     // session to report into drops the first diffs.
-    return devModule === null ? base : `${base}import('${devModule}');\n`;
+    return null === devModule ? base : `${base}import('${devModule}');\n`;
 }
 /**
  * Reticle Vite plugin. Add to your `plugins` array and the entire integration is done:
@@ -253,7 +270,7 @@ export function connectModuleSource(options, devModule = null) {
 export function reticle(options = {}) {
     const sourceMapping = options.sourceMapping !== false;
     const inject = options.inject !== false;
-    const desktop = options.desktop === true;
+    const desktop = true === options.desktop;
     // Resolve the stable projectId once (explicit option, else derived from package.json + cwd) so the
     // app is identifiable across port changes with zero config.
     const resolved = {
@@ -284,7 +301,12 @@ export function reticle(options = {}) {
         const port = resolved.port ?? discoverDaemonPort(resolved.projectId);
         const withPort = port !== undefined ? { ...resolved, port } : resolved;
         const token = withPort.token ?? readPairingToken();
-        return token !== undefined ? { ...withPort, token } : withPort;
+        const withToken = token !== undefined ? { ...withPort, token } : withPort;
+        // Resolved here for the same reason as the token: these are Node-side facts about the installed
+        // tree, and they travel in the generated connect call rather than through a `define`.
+        const appRoot = withToken.root ?? root ?? process.cwd();
+        const sdkVersion = withToken.sdkVersion ?? sdkPackageVersion(appRoot);
+        return { ...withToken, root: appRoot, sdkVersion };
     };
     /**
      * The BUILD message. A build always runs every transform, so "my transform never ran" and "the
@@ -322,7 +344,7 @@ export function reticle(options = {}) {
         // Web: serve-only, so a production bundle can never carry the SDK — gating is the tool's job.
         // Desktop: a packaged renderer IS a production build with no dev server, so the plugin must also
         // run for `vite build` or the shipped app has no connect() at all.
-        ...(options.desktop === true ? {} : { apply: 'serve' }),
+        ...(true === options.desktop ? {} : { apply: 'serve' }),
         enforce: 'pre',
         /**
          * Declare the SDK's CJS runtime deps so Vite pre-bundles them.
@@ -342,6 +364,9 @@ export function reticle(options = {}) {
          * tree depends on @testing-library/dom.
          */
         config(config) {
+            // Everything below asks what the APP has installed, so every lookup is rooted here and never
+            // at the plugin's own location. Vite defaults an omitted root to the cwd; so do we.
+            const appRoot = config.root ?? process.cwd();
             return {
                 // Expose the daemon's pairing token to hand-written connects in the same Vite app. The
                 // plugin's own injected connect gets the token directly, but a connect the USER writes —
@@ -350,19 +375,27 @@ export function reticle(options = {}) {
                 // failed". Empty until the daemon has provisioned one; the page reloads once it has.
                 define: {
                     ...(config.define ?? {}),
-                    [RETICLE_TOKEN_GLOBAL]: JSON.stringify(readPairingToken() ?? ''),
+                    [RETICLE_TOKEN_GLOBAL]: JSON.stringify(warnIfTokenMissing(readPairingToken()) ?? ''),
                     // Lets the SDK report React's absolute `_debugSource.fileName` as a repo-relative path,
                     // so source looks the same whichever React version an app is on.
-                    [RETICLE_ROOT_GLOBAL]: JSON.stringify(config.root ?? process.cwd()),
+                    // Kept for HAND-WRITTEN connects (SvelteKit's hook, a custom entry): those live in app
+                    // source, where a define does substitute. The plugin's own injected connect passes both as
+                    // arguments instead — see connectArgs.
+                    [RETICLE_ROOT_GLOBAL]: JSON.stringify(appRoot),
+                    [RETICLE_SDK_VERSION_GLOBAL]: JSON.stringify(sdkPackageVersion(appRoot)),
                 },
                 optimizeDeps: {
                     // Part of the cache key, not of the build: changing it is what makes Vite notice that the
                     // SDK on disk is not the SDK it pre-bundled. See sdkBuildFingerprint.
-                    esbuildOptions: {
+                    //
+                    // Under the key THIS Vite wants. Vite 7 moved the optimizer to rolldown and deprecated
+                    // `esbuildOptions`, warning on every boot — a warning attributed to the plugin that set
+                    // it, which is us.
+                    [optimizerOptionsKey(viteMajor(appRoot))]: {
                         ...(config.optimizeDeps?.esbuildOptions ?? {}),
                         define: {
                             ...(config.optimizeDeps?.esbuildOptions?.define ?? {}),
-                            __RETICLE_SDK_BUILD__: JSON.stringify(sdkBuildFingerprint()),
+                            __RETICLE_SDK_BUILD__: JSON.stringify(sdkBuildFingerprint(appRoot)),
                         },
                     },
                     include: [
@@ -374,9 +407,9 @@ export function reticle(options = {}) {
                         // the one the whole product is judged on — silently did nothing, and it worked on the
                         // next refresh, which is the worst possible shape for a bug like this.
                         RETICLE_PACKAGE,
-                        // Only if present — see above; naming an absent package produces a boot warning that
-                        // blames Reticle for nothing.
-                        ...[SDK_CJS_DEPS.TESTING_LIBRARY, SDK_CJS_DEPS.ARIA_QUERY].filter(isResolvable),
+                        // Only in a form that resolves — see above; a name Vite cannot resolve produces a boot
+                        // warning that blames Reticle, and a forced re-optimization on every cold start.
+                        ...cjsDepIncludes(appRoot),
                     ],
                 },
             };
@@ -398,7 +431,7 @@ export function reticle(options = {}) {
             // map: the insertions are within a line and never move one, and a wrong map is worse than none.
             if (shouldStampSvelte(id)) {
                 const stamped = stampSvelte(code, id);
-                return stamped === null ? null : { code: stamped, map: null };
+                return null === stamped ? null : { code: stamped, map: null };
             }
             if (!shouldStamp(id))
                 return null;
@@ -445,7 +478,7 @@ export function reticle(options = {}) {
             // In serve, the HTML is sent BEFORE the browser requests the entry module, so the check has to
             // be deferred — asserting here would fire on every healthy start. Unref'd so a dev server is
             // never held open by it.
-            if (desktop && inject && command === 'serve') {
+            if (desktop && inject && 'serve' === command) {
                 const timer = setTimeout(checkInjected, DEV_INJECTION_GRACE_MS);
                 timer.unref?.();
             }

package/dist/installed.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Node-side questions about what is actually installed in the app.
+ *
+ * All three answer "what is on disk right now" rather than "what does the plugin do", and each exists
+ * because guessing was wrong in a way that reached a user: a declared-but-absent dependency logs a
+ * resolve failure on every boot, an unnoticed SDK change leaves stale code in the browser, and an
+ * unreported version makes a skewed pair surface as a bare -32000.
+ *
+ * All three resolve from the APP ROOT, never from this file. The SDK is the user's dependency and
+ * deliberately not one of this plugin's, so a resolve based on `import.meta.url` walks the PLUGIN's
+ * node_modules — which under pnpm's strict layout does not contain the SDK at all. Every one of these
+ * then fell into its own catch and returned the "not installed" answer: no `sdkVersion` on the HELLO,
+ * a CONSTANT build fingerprint (so Vite never re-bundled a changed SDK — the exact stale-bundle
+ * false-negative the fingerprint exists to prevent), and no optimizeDeps entry for the SDK itself.
+ * Silently, for every pnpm user, with no error anywhere.
+ */
+/**
+ * Whether a package can be resolved from the app. Used to avoid declaring an optimizeDeps entry for
+ * something the app does not have, which Vite reports as a resolve failure on every boot.
+ */
+export declare function isResolvable(specifier: string, from?: string): boolean;
+/**
+ * Vite's nested include form — `a > b > c` — for a chain that fully resolves, else null.
+ *
+ * A single-segment chain is just the bare specifier, so this also answers "can the app see it
+ * itself". Each further segment is resolved from the PREVIOUS package's directory, which is what
+ * Vite does with the `>` form and the only way to name a dependency the app root cannot see: under
+ * pnpm (and npm's nested layout) `@testing-library/dom` belongs to `@reticlehq/browser`, not to the
+ * user's app. Naming it bare made Vite fail to resolve it and force a re-optimization on every cold
+ * boot. SvelteKit ships `svelte > clsx` for the same reason.
+ */
+export declare function resolvableChain(chain: readonly string[], from: string): string | null;
+/** The installed SDK's package version, for the HELLO's `sdkVersion`. Node-side only. */
+export declare function sdkPackageVersion(from?: string): string;
+/**
+ * A fingerprint of the installed SDK build, mixed into `optimizeDeps` so Vite re-bundles when the
+ * SDK changes.
+ *
+ * Vite's dep-optimizer cache is keyed on the `optimizeDeps` config and the lockfile — NOT on the
+ * contents of the packages it bundled. Upgrade the SDK in place (a patched dist, a linked checkout,
+ * an overlay) and the version in `package.json` can stay the same, so Vite keeps serving the OLD
+ * pre-bundled copy out of `node_modules/.vite` across dev-server restarts. The fix you just shipped
+ * is simply not in the browser, and it looks like the fix does not work. That cost a real
+ * false-negative during this bug hunt, and every user upgrading in place hits the same thing.
+ *
+ * Size+mtime is enough: it changes whenever the bundle does and costs one `stat`.
+ */
+export declare function sdkBuildFingerprint(from?: string): string;
+/**
+ * The installed Vite's major version, or null when it cannot be read.
+ *
+ * Asked from the APP's root, never the plugin's: the plugin and the app can resolve different Vites
+ * in a monorepo, and the one whose deprecation warnings the user sees is the app's.
+ */
+export declare function viteMajor(from?: string): number | null;
+/** Vite renamed the dep-optimizer's passthrough options when it moved to rolldown. */
+export declare const OPTIMIZER_OPTIONS_KEY: {
+    readonly ESBUILD: "esbuildOptions";
+    readonly ROLLDOWN: "rolldownOptions";
+};
+export type OptimizerOptionsKey = (typeof OPTIMIZER_OPTIONS_KEY)[keyof typeof OPTIMIZER_OPTIONS_KEY];
+/**
+ * Which key carries optimizer options on this Vite.
+ *
+ * Vite 7 moved the dep optimizer to rolldown and deprecated `optimizeDeps.esbuildOptions`, warning
+ * on every boot to use `rolldownOptions` instead — a warning attributed to whichever plugin set it,
+ * which is us. Unknown versions get the older key: a deprecation notice is a much smaller failure
+ * than an option the installed Vite has never heard of.
+ */
+export declare function optimizerOptionsKey(major: number | null): OptimizerOptionsKey;

package/dist/installed.js

@@ -0,0 +1,184 @@
+/**
+ * Node-side questions about what is actually installed in the app.
+ *
+ * All three answer "what is on disk right now" rather than "what does the plugin do", and each exists
+ * because guessing was wrong in a way that reached a user: a declared-but-absent dependency logs a
+ * resolve failure on every boot, an unnoticed SDK change leaves stale code in the browser, and an
+ * unreported version makes a skewed pair surface as a bare -32000.
+ *
+ * All three resolve from the APP ROOT, never from this file. The SDK is the user's dependency and
+ * deliberately not one of this plugin's, so a resolve based on `import.meta.url` walks the PLUGIN's
+ * node_modules — which under pnpm's strict layout does not contain the SDK at all. Every one of these
+ * then fell into its own catch and returned the "not installed" answer: no `sdkVersion` on the HELLO,
+ * a CONSTANT build fingerprint (so Vite never re-bundled a changed SDK — the exact stale-bundle
+ * false-negative the fingerprint exists to prevent), and no optimizeDeps entry for the SDK itself.
+ * Silently, for every pnpm user, with no error anywhere.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+/** The React kit the host app imports the SDK from. Mirrors the constant in index.ts. */
+const RETICLE_PACKAGE = '@reticlehq/react';
+/** How far up from the resolved entry to look for the manifest beside it. */
+const MANIFEST_SEARCH_DEPTH = 5;
+/**
+ * A `require` rooted at the app rather than at this plugin. `from` is Vite's `config.root`; the
+ * `process.cwd()` default matches how Vite itself defaults the root when the config omits it.
+ */
+function requireFromApp(from) {
+    return createRequire(join(from, 'package.json'));
+}
+/**
+ * Whether a package can be resolved from the app. Used to avoid declaring an optimizeDeps entry for
+ * something the app does not have, which Vite reports as a resolve failure on every boot.
+ */
+export function isResolvable(specifier, from = process.cwd()) {
+    try {
+        requireFromApp(from).resolve(specifier);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The directory holding `specifier`'s own manifest, resolved from `from`. Null when it is not there.
+ *
+ * Resolves the entry and walks up to the manifest beside it rather than requiring
+ * `<pkg>/package.json` directly: a package with an `exports` map may refuse that subpath, and our
+ * own packages do.
+ */
+function packageDirOf(specifier, from) {
+    try {
+        let dir = dirname(requireFromApp(from).resolve(specifier));
+        for (let up = 0; up < MANIFEST_SEARCH_DEPTH; up++) {
+            const candidate = join(dir, 'package.json');
+            if (existsSync(candidate)) {
+                const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
+                if (parsed.name === specifier)
+                    return dir;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // Unresolvable from here — the caller's next chain, or nothing.
+    }
+    return null;
+}
+/**
+ * Vite's nested include form — `a > b > c` — for a chain that fully resolves, else null.
+ *
+ * A single-segment chain is just the bare specifier, so this also answers "can the app see it
+ * itself". Each further segment is resolved from the PREVIOUS package's directory, which is what
+ * Vite does with the `>` form and the only way to name a dependency the app root cannot see: under
+ * pnpm (and npm's nested layout) `@testing-library/dom` belongs to `@reticlehq/browser`, not to the
+ * user's app. Naming it bare made Vite fail to resolve it and force a re-optimization on every cold
+ * boot. SvelteKit ships `svelte > clsx` for the same reason.
+ */
+export function resolvableChain(chain, from) {
+    let base = from;
+    for (const segment of chain) {
+        const dir = packageDirOf(segment, base);
+        if (null === dir)
+            return null;
+        base = dir;
+    }
+    return 0 === chain.length ? null : chain.join(' > ');
+}
+/** The installed SDK's package version, for the HELLO's `sdkVersion`. Node-side only. */
+export function sdkPackageVersion(from = process.cwd()) {
+    const require_ = requireFromApp(from);
+    // Preferred: the package exports its own manifest. Newer SDKs do.
+    try {
+        const pkg = require_(`${RETICLE_PACKAGE}/package.json`);
+        if ('string' === typeof pkg.version)
+            return pkg.version;
+    }
+    catch {
+        // Falls through — see below.
+    }
+    // Fallback, and it is load-bearing rather than defensive: an OLDER SDK has no `./package.json`
+    // in its exports map, and an older SDK is precisely the skew we are trying to name. Resolve the
+    // main entry instead and walk up to the manifest beside it.
+    try {
+        let dir = dirname(require_.resolve(RETICLE_PACKAGE));
+        for (let up = 0; up < MANIFEST_SEARCH_DEPTH; up++) {
+            const candidate = join(dir, 'package.json');
+            if (existsSync(candidate)) {
+                const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
+                if ('string' === typeof parsed.version)
+                    return parsed.version;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // Unresolvable (not installed yet, exotic layout) — report nothing rather than guessing.
+    }
+    return '';
+}
+/**
+ * A fingerprint of the installed SDK build, mixed into `optimizeDeps` so Vite re-bundles when the
+ * SDK changes.
+ *
+ * Vite's dep-optimizer cache is keyed on the `optimizeDeps` config and the lockfile — NOT on the
+ * contents of the packages it bundled. Upgrade the SDK in place (a patched dist, a linked checkout,
+ * an overlay) and the version in `package.json` can stay the same, so Vite keeps serving the OLD
+ * pre-bundled copy out of `node_modules/.vite` across dev-server restarts. The fix you just shipped
+ * is simply not in the browser, and it looks like the fix does not work. That cost a real
+ * false-negative during this bug hunt, and every user upgrading in place hits the same thing.
+ *
+ * Size+mtime is enough: it changes whenever the bundle does and costs one `stat`.
+ */
+export function sdkBuildFingerprint(from = process.cwd()) {
+    try {
+        const entry = requireFromApp(from).resolve(RETICLE_PACKAGE);
+        const { size, mtimeMs } = statSync(entry);
+        return `${String(size)}-${String(Math.trunc(mtimeMs))}`;
+    }
+    catch {
+        // Unresolvable (not installed yet, exotic layout) — a constant is still correct, just inert.
+        return 'unknown';
+    }
+}
+/**
+ * The installed Vite's major version, or null when it cannot be read.
+ *
+ * Asked from the APP's root, never the plugin's: the plugin and the app can resolve different Vites
+ * in a monorepo, and the one whose deprecation warnings the user sees is the app's.
+ */
+export function viteMajor(from = process.cwd()) {
+    try {
+        const pkg = requireFromApp(from)('vite/package.json');
+        const major = parseInt((pkg.version ?? '').split('.')[0] ?? '', 10);
+        return isNaN(major) ? null : major;
+    }
+    catch {
+        return null;
+    }
+}
+/** Vite renamed the dep-optimizer's passthrough options when it moved to rolldown. */
+export const OPTIMIZER_OPTIONS_KEY = {
+    ESBUILD: 'esbuildOptions',
+    ROLLDOWN: 'rolldownOptions',
+};
+/**
+ * Which key carries optimizer options on this Vite.
+ *
+ * Vite 7 moved the dep optimizer to rolldown and deprecated `optimizeDeps.esbuildOptions`, warning
+ * on every boot to use `rolldownOptions` instead — a warning attributed to whichever plugin set it,
+ * which is us. Unknown versions get the older key: a deprecation notice is a much smaller failure
+ * than an option the installed Vite has never heard of.
+ */
+export function optimizerOptionsKey(major) {
+    return null !== major && 7 <= major
+        ? OPTIMIZER_OPTIONS_KEY.ROLLDOWN
+        : OPTIMIZER_OPTIONS_KEY.ESBUILD;
+}

package/dist/missing-token.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The one build-time condition that guarantees a runtime failure.
+ *
+ * The pairing token is read from disk ONCE, when Vite resolves its config, and inlined as
+ * `__RETICLE_TOKEN__`. The daemon is what writes that file — so a dev server started BEFORE the
+ * daemon bakes in an empty token, and every app it serves opens a WebSocket the bridge then refuses.
+ *
+ * Nothing about that looks broken from outside: the SDK module loads, the socket opens, and then a
+ * session simply never appears. Restarting the dev server is the whole fix, and no other layer is in
+ * a position to say so — by the time the failure is observable, the value was baked in minutes ago.
+ */
+export declare function missingTokenWarning(token: string | undefined): string | undefined;

package/dist/missing-token.js

@@ -0,0 +1,19 @@
+/**
+ * The one build-time condition that guarantees a runtime failure.
+ *
+ * The pairing token is read from disk ONCE, when Vite resolves its config, and inlined as
+ * `__RETICLE_TOKEN__`. The daemon is what writes that file — so a dev server started BEFORE the
+ * daemon bakes in an empty token, and every app it serves opens a WebSocket the bridge then refuses.
+ *
+ * Nothing about that looks broken from outside: the SDK module loads, the socket opens, and then a
+ * session simply never appears. Restarting the dev server is the whole fix, and no other layer is in
+ * a position to say so — by the time the failure is observable, the value was baked in minutes ago.
+ */
+export function missingTokenWarning(token) {
+    if (token !== undefined && token.length > 0)
+        return undefined;
+    return ('[reticle] no pairing token was available when this dev server started, 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 (`reticle serve`, or let your agent start ' +
+        'it) and then RESTART this dev server, because the value is inlined at config time.');
+}

package/dist/project-id.d.ts

@@ -6,16 +6,15 @@
  * package.json name plus a short hash of its absolute root — human-readable AND unique per checkout,
  * and unchanged when the port shifts. An explicit `projectId` option always overrides.
  */
-/**
- * Turn a package name into an id-safe slug: scoped names lose the `@scope/` punctuation
- * (`@acme/web` → `acme-web`), everything non-alphanumeric collapses to single dashes, edges trimmed.
- */
-export declare function slugifyPackageName(name: string): string;
+export { slugifyPackageName } from '@reticlehq/core';
 /** A short, stable hex fingerprint of the absolute project root (disambiguates same-named checkouts). */
 export declare function shortHash(input: string): string;
 /**
  * Derive the stable projectId from the package name (may be undefined) and the absolute root path.
- * Pure — both inputs are passed in. Falls back to the root's folder name, then to "app".
+ *
+ * The rule itself is core's `projectIdFrom`, shared with `reticle init`: this id is what scopes a
+ * session to an app, so what the plugin stamps and what init records must be the same string. They
+ * used to be two identical copies kept in step by a comment.
  */
 export declare function deriveProjectId(pkgName: string | undefined, rootPath: string): string;
 /**

package/dist/project-id.js

@@ -7,31 +7,23 @@
  * and unchanged when the port shifts. An explicit `projectId` option always overrides.
  */
 import { createHash } from 'node:crypto';
-import { basename, dirname, join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
-/**
- * Turn a package name into an id-safe slug: scoped names lose the `@scope/` punctuation
- * (`@acme/web` → `acme-web`), everything non-alphanumeric collapses to single dashes, edges trimmed.
- */
-export function slugifyPackageName(name) {
-    return name
-        .toLowerCase()
-        .replace(/^@/, '')
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
+import { PROJECT_ID_HASH_LENGTH, projectIdFrom } from '@reticlehq/core';
+export { slugifyPackageName } from '@reticlehq/core';
 /** A short, stable hex fingerprint of the absolute project root (disambiguates same-named checkouts). */
 export function shortHash(input) {
-    return createHash('sha1').update(input).digest('hex').slice(0, 8);
+    return createHash('sha1').update(input).digest('hex').slice(0, PROJECT_ID_HASH_LENGTH);
 }
 /**
  * Derive the stable projectId from the package name (may be undefined) and the absolute root path.
- * Pure — both inputs are passed in. Falls back to the root's folder name, then to "app".
+ *
+ * The rule itself is core's `projectIdFrom`, shared with `reticle init`: this id is what scopes a
+ * session to an app, so what the plugin stamps and what init records must be the same string. They
+ * used to be two identical copies kept in step by a comment.
  */
 export function deriveProjectId(pkgName, rootPath) {
-    const fromName = pkgName !== undefined ? slugifyPackageName(pkgName) : '';
-    const base = fromName.length > 0 ? fromName : slugifyPackageName(basename(rootPath)) || 'app';
-    return `${base}-${shortHash(rootPath)}`;
+    return projectIdFrom(pkgName, rootPath, shortHash);
 }
 /** Read the `name` from the nearest package.json at or above `startDir`, or undefined if none. */
 function readNearestPackageName(startDir) {
@@ -41,9 +33,9 @@ function readNearestPackageName(startDir) {
         if (existsSync(pkgPath)) {
             try {
                 const parsed = JSON.parse(readFileSync(pkgPath, 'utf8'));
-                if (typeof parsed === 'object' && parsed !== null) {
+                if ('object' === typeof parsed && parsed !== null) {
                     const name = parsed['name'];
-                    if (typeof name === 'string' && name.length > 0)
+                    if ('string' === typeof name && name.length > 0)
                         return name;
                 }
             }

package/dist/svelte-source.d.ts

@@ -35,13 +35,13 @@
 /** Files this module stamps. `.svelte.ts` (a runes module) is code, not markup — excluded. */
 export declare const SVELTE_FILE: RegExp;
 /** The part of `svelte/compiler` this module uses. Structural, so `svelte` stays un-imported. */
-export interface SvelteCompilerLike {
+interface SvelteCompilerLike {
     parse: (source: string, options?: {
         modern?: boolean;
     }) => unknown;
 }
 /** How the compiler is obtained. Injected in tests; the default resolves it from the app. */
-export type LoadSvelteCompiler = () => SvelteCompilerLike | null;
+type LoadSvelteCompiler = () => SvelteCompilerLike | null;
 /**
  * A character offset as Babel would report it: 1-based line, 0-based column.
  *
@@ -53,8 +53,6 @@ export declare function offsetToLineColumn(source: string, offset: number): {
     line: number;
     column: number;
 };
-/** Project-relative, forward-slashed. A pointer must be the same string on Windows as on Linux. */
-export declare function sourcePathFor(id: string, cwd?: string): string;
 /**
  * Stamp `data-reticle-source="file:line:column"` on every host element of a `.svelte` component.
  *
@@ -64,3 +62,4 @@ export declare function sourcePathFor(id: string, cwd?: string): string;
  * enrichment on top of an app that otherwise works.
  */
 export declare function stampSvelte(code: string, id: string, load?: LoadSvelteCompiler): string | null;
+export {};

package/dist/svelte-source.js

@@ -71,7 +71,7 @@ export function offsetToLineColumn(source, offset) {
     let line = 1;
     let lineStart = 0;
     for (let i = 0; i < offset && i < source.length; i++) {
-        if (source[i] === '\n') {
+        if ('\n' === source[i]) {
             line += 1;
             lineStart = i + 1;
         }
@@ -79,21 +79,21 @@ export function offsetToLineColumn(source, offset) {
     return { line, column: offset - lineStart };
 }
 /** Project-relative, forward-slashed. A pointer must be the same string on Windows as on Linux. */
-export function sourcePathFor(id, cwd = process.cwd()) {
+function sourcePathFor(id, cwd = process.cwd()) {
     return relative(cwd, id).replace(/\\/g, '/');
 }
 function isElementNode(value) {
-    if (value === null || typeof value !== 'object')
+    if (null === value || typeof value !== 'object')
         return false;
     const node = value;
-    return (typeof node.type === 'string' &&
+    return ('string' === typeof node.type &&
         HOST_ELEMENT_TYPES.has(node.type) &&
-        typeof node.name === 'string' &&
-        typeof node.start === 'number');
+        'string' === typeof node.name &&
+        'number' === typeof node.start);
 }
 function isAlreadyStamped(node) {
     return (node.attributes ?? []).some((attr) => attr !== null &&
-        typeof attr === 'object' &&
+        'object' === typeof attr &&
         attr.name === DATA_RETICLE_SOURCE_ATTR);
 }
 /**
@@ -109,7 +109,7 @@ function collectElements(root) {
     const found = [];
     const seen = new Set();
     const visit = (value) => {
-        if (value === null || typeof value !== 'object' || seen.has(value))
+        if (null === value || typeof value !== 'object' || seen.has(value))
             return;
         seen.add(value);
         if (Array.isArray(value)) {
@@ -137,7 +137,7 @@ function collectElements(root) {
  */
 export function stampSvelte(code, id, load = defaultLoadCompiler) {
     const compiler = load();
-    if (compiler === null)
+    if (null === compiler)
         return null;
     let ast;
     try {
@@ -149,7 +149,7 @@ export function stampSvelte(code, id, load = defaultLoadCompiler) {
         return null;
     }
     const elements = collectElements(ast);
-    if (elements.length === 0)
+    if (0 === elements.length)
         return null;
     const file = sourcePathFor(id);
     // Insert from the LAST element backwards: every insertion shifts the offsets after it, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Vite plugin for Reticle: dev-only source-map stamping plus auto-injected reticle.connect(). apply:'serve' guarantees it never ships to production.",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,7 +25,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -34,8 +35,8 @@
   ],
   "dependencies": {
     "@babel/core": "^7.26.0",
-    "@reticlehq/babel-plugin": "2.4.0",
-    "@reticlehq/core": "2.4.0"
+    "@reticlehq/babel-plugin": "2.5.0",
+    "@reticlehq/core": "2.5.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
@@ -60,6 +61,7 @@
     "build": "tsc -b",
     "typecheck": "tsc -b",
     "lint": "eslint src",
-    "test:unit": "vitest run src --passWithNoTests"
+    "test:unit": "vitest run src --passWithNoTests",
+    "test:coverage": "vitest run src --passWithNoTests --coverage.enabled --coverage.provider=v8 --coverage.reporter=text-summary --coverage.include='src/**/*.ts' --coverage.exclude='src/**/*.test.ts'"
   }
 }