@reticlehq/vite-plugin 2.3.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

@@ -1,4 +1,10 @@
 export declare const RETICLE_VITE_PLUGIN_NAME = "reticle";
+/**
+ * Compile-time global carrying the daemon's pairing token, for connects the plugin does not write
+ * itself. The bridge requires the token even on localhost, and nothing in a browser can read the
+ * file it lives in.
+ */
+export declare const RETICLE_TOKEN_GLOBAL = "__RETICLE_TOKEN__";
 /**
  * The connect code is served as a real module (not an inline <script>) so that Vite's import
  * pipeline resolves the bare `@reticlehq/react` specifier. An inline injected script is NOT run through
@@ -18,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;
     /**
@@ -79,11 +95,18 @@ export interface ReticleVitePlugin {
     config?: (config: {
         optimizeDeps?: {
             include?: string[];
+            esbuildOptions?: {
+                define?: Record<string, string>;
+            };
         };
+        define?: Record<string, string>;
+        root?: string;
     }) => {
         optimizeDeps: {
             include: string[];
+            [optionsKey: string]: unknown;
         };
+        define: Record<string, string>;
     };
     /** Absent in desktop mode, where the plugin must also run for `vite build`. */
     apply?: 'serve';
@@ -114,9 +137,43 @@ 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. */
-export declare function connectModuleSource(options: ReticleVitePluginOptions): string;
+/**
+ * The conventional app-side dev module: `registerStore` / `registerCapabilities` live here.
+ *
+ * It is imported by CONVENTION rather than by patching the app's entry file. The connect is injected
+ * into a virtual module, so there is nowhere for a user to add these calls without `init` editing
+ * `src/main.tsx` — an edit to the file people actually own, for something that is opt-in enrichment.
+ * Convention costs one `existsSync` and leaves their entry untouched.
+ */
+export declare const RETICLE_DEV_MODULE_CANDIDATES: readonly ["src/reticle-dev.ts", "src/reticle-dev.js", "src/reticle-dev.tsx", "src/reticle-dev.jsx"];
+/** The app's dev module, as an importable path — or null when the app has none. */
+export declare function findDevModule(root: string, exists: (p: string) => boolean): string | null;
+export declare function connectModuleSource(options: ReticleVitePluginOptions, devModule?: string | null): string;
 /**
  * Reticle Vite plugin. Add to your `plugins` array and the entire integration is done:
  *

package/dist/index.js

@@ -1,16 +1,26 @@
-import { readFileSync } 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, } 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 { 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`
 // — that is the isomorphic foundation and exports neither.
 const RETICLE_PACKAGE = '@reticlehq/react';
+/**
+ * Compile-time global carrying the daemon's pairing token, for connects the plugin does not write
+ * itself. The bridge requires the token even on localhost, and nothing in a browser can read the
+ * file it lives in.
+ */
+export const RETICLE_TOKEN_GLOBAL = '__RETICLE_TOKEN__';
 /** 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. */
@@ -77,14 +87,23 @@ function isHtmlEntry(id, specifier, root) {
     // buildEnd post-condition means a wrong match cannot pass unnoticed as "nothing happened".
     return candidate.endsWith(target.startsWith('/') ? target : `/${target}`);
 }
-function shouldStamp(id) {
+/** A module id we may stamp at all: not virtual, not a dependency. Extension decides which stamper. */
+function stampableId(id) {
     if (id.startsWith(VIRTUAL_PREFIX))
-        return false;
+        return null;
     if (id.includes(NODE_MODULES))
-        return false;
+        return null;
     // Strip any query suffix (?worker, ?raw,...) before matching the extension.
-    const clean = id.split('?')[0] ?? id;
-    return JSX_FILE.test(clean);
+    return id.split('?')[0] ?? id;
+}
+function shouldStamp(id) {
+    const clean = stampableId(id);
+    return clean !== null && JSX_FILE.test(clean);
+}
+/** A `.svelte` single-file component, which needs the Svelte stamper rather than Babel. */
+function shouldStampSvelte(id) {
+    const clean = stampableId(id);
+    return clean !== null && SVELTE_FILE.test(clean);
 }
 function stamp(code, id) {
     const out = transformSync(code, {
@@ -95,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),
     };
 }
 /**
@@ -116,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) {
@@ -139,22 +200,57 @@ 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) : '';
 }
 /** The body of the connect module — real imports, resolved by Vite when the module is served. */
-export function connectModuleSource(options) {
+/**
+ * The conventional app-side dev module: `registerStore` / `registerCapabilities` live here.
+ *
+ * It is imported by CONVENTION rather than by patching the app's entry file. The connect is injected
+ * into a virtual module, so there is nowhere for a user to add these calls without `init` editing
+ * `src/main.tsx` — an edit to the file people actually own, for something that is opt-in enrichment.
+ * Convention costs one `existsSync` and leaves their entry untouched.
+ */
+export const RETICLE_DEV_MODULE_CANDIDATES = [
+    'src/reticle-dev.ts',
+    'src/reticle-dev.js',
+    'src/reticle-dev.tsx',
+    'src/reticle-dev.jsx',
+];
+/** The app's dev module, as an importable path — or null when the app has none. */
+export function findDevModule(root, exists) {
+    for (const rel of RETICLE_DEV_MODULE_CANDIDATES) {
+        if (exists(`${root}/${rel}`))
+            return `/${rel}`;
+    }
+    return null;
+}
+export function connectModuleSource(options, devModule = null) {
     const args = connectArgs(options);
-    return `import { reticle, install } from '${RETICLE_PACKAGE}';\ninstall();\nreticle.connect(${args});\n`;
+    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 null === devModule ? base : `${base}import('${devModule}');\n`;
 }
 /**
  * Reticle Vite plugin. Add to your `plugins` array and the entire integration is done:
@@ -174,7 +270,7 @@ export function connectModuleSource(options) {
 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 = {
@@ -205,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
@@ -243,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.
@@ -256,15 +357,59 @@ export function reticle(options = {}) {
          * developer has never heard of. Measured on the react-admin demo with the SDK aliased to a local
          * checkout: zero sessions, and it looked like the app was failing to render.
          *
-         * Declaring them is free when Vite would have found them anyway.
+         * Declaring them is free when Vite would have found them anyway — but only when they are
+         * actually installed. Naming a package that is not there makes Vite log `Failed to resolve
+         * dependency: …, present in optimizeDeps.include` on every boot, which is a scary line pointing
+         * at Reticle for a problem that does not exist. SvelteKit apps hit exactly that: nothing in that
+         * 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 —
+                // SvelteKit's client hook, a custom entry — had no way to reach a file only Node can read,
+                // so it called connect() with no credential and the bridge answered "authentication
+                // failed". Empty until the daemon has provisioned one; the page reloads once it has.
+                define: {
+                    ...(config.define ?? {}),
+                    [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.
+                    // 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.
+                    //
+                    // 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(appRoot)),
+                        },
+                    },
                     include: [
                         ...(config.optimizeDeps?.include ?? []),
-                        SDK_CJS_DEPS.TESTING_LIBRARY,
-                        SDK_CJS_DEPS.ARIA_QUERY,
+                        // The SDK ITSELF. Without this, Vite does not learn about @reticlehq/react until the
+                        // injected connect module is requested — mid-flight, on the very first page load. It
+                        // then pre-bundles it and forces a full reload, and the connect is lost in that reload:
+                        // no WebSocket, no session, no console message. The FIRST load after `reticle init` —
+                        // 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 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),
                     ],
                 },
             };
@@ -279,7 +424,16 @@ export function reticle(options = {}) {
                 const stamped = sourceMapping && shouldStamp(id) ? stamp(withConnect, id) : null;
                 return stamped ?? { code: withConnect, map: null };
             }
-            if (!sourceMapping || !shouldStamp(id))
+            if (!sourceMapping)
+                return null;
+            // `.svelte` runs on the RAW component source, which is only still markup because this plugin
+            // declares `enforce: 'pre'` and therefore transforms before @sveltejs/vite-plugin-svelte. No
+            // 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 null === stamped ? null : { code: stamped, map: null };
+            }
+            if (!shouldStamp(id))
                 return null;
             return stamp(code, id);
         },
@@ -301,7 +455,9 @@ export function reticle(options = {}) {
         load(id) {
             if (!inject || id !== RETICLE_CONNECT_MODULE)
                 return null;
-            return connectModuleSource(resolveLazy());
+            // Resolved at load, not at config: the file may be created after the dev server starts.
+            const devModule = root === undefined ? null : findDevModule(root, existsSync);
+            return connectModuleSource(resolveLazy(), devModule);
         },
         configResolved(config) {
             root = config.root;
@@ -322,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

@@ -0,0 +1,65 @@
+/**
+ * `data-reticle-source` for `.svelte` single-file components.
+ *
+ * A SvelteKit app onboards, connects, and gets DOM, network, console, routing and storage — and then
+ * every verdict comes back without the `file:line` the whole product leads with, because the JSX
+ * stamper is Babel and a `.svelte` file is not JavaScript. This is the Svelte half.
+ *
+ * ## Where in the pipeline
+ *
+ * A Vite `transform` on the RAW component source, in the Reticle plugin, which already declares
+ * `enforce: 'pre'` — so it runs before `@sveltejs/vite-plugin-svelte` and hands the compiler markup
+ * that already carries the attribute. Getting the order wrong is the failure mode worth naming: run
+ * it after, and there is no markup left to stamp, only generated JavaScript whose original line
+ * numbers are gone. A Svelte *preprocessor* would also work and would be equally correct, but it has
+ * to be wired into `svelte.config.js` by the user, and an integration nobody enables is an
+ * integration that does not exist.
+ *
+ * ## Why the compiler is loaded the way it is
+ *
+ * `svelte` must never become a dependency of this package: a React project installing the Vite
+ * plugin must not acquire a Svelte compiler, and its build must be unaffected. So the compiler is
+ * resolved lazily, from the APP's directory, only when a `.svelte` id actually arrives, and its
+ * absence returns null rather than throwing. Same shape as the optional `playwright` import in the
+ * server's pool launcher.
+ *
+ * Resolution is synchronous (`createRequire`) rather than `await import()` because Svelte ships a CJS
+ * build of its compiler and the plugin's `transform` is synchronous — making the whole hook async to
+ * fetch an optional dependency would change the contract of every other path through it.
+ *
+ * ## Scope
+ *
+ * The attribute only. Mapping a DOM node to the COMPONENT that rendered it — what `@reticlehq/react`
+ * does through the fiber tree — is a separate and much larger problem, and is not attempted here.
+ */
+/** 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. */
+interface SvelteCompilerLike {
+    parse: (source: string, options?: {
+        modern?: boolean;
+    }) => unknown;
+}
+/** How the compiler is obtained. Injected in tests; the default resolves it from the app. */
+type LoadSvelteCompiler = () => SvelteCompilerLike | null;
+/**
+ * A character offset as Babel would report it: 1-based line, 0-based column.
+ *
+ * Matching Babel exactly is not cosmetic — `parseSourceAttr` in the browser SDK reads one format,
+ * and a Svelte pointer that was 0-based on line would land every verdict one line off while looking
+ * completely plausible.
+ */
+export declare function offsetToLineColumn(source: string, offset: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Stamp `data-reticle-source="file:line:column"` on every host element of a `.svelte` component.
+ *
+ * Returns null — never throws — when the compiler is absent or the component does not parse. In dev
+ * the transform runs on every keystroke, so a half-typed component is the NORMAL case; failing the
+ * build over one would make Reticle the reason the dev server is red, for a feature that is pure
+ * 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

@@ -0,0 +1,166 @@
+import { createRequire } from 'node:module';
+import { relative } from 'node:path';
+import { DATA_RETICLE_SOURCE_ATTR } from '@reticlehq/core';
+/**
+ * `data-reticle-source` for `.svelte` single-file components.
+ *
+ * A SvelteKit app onboards, connects, and gets DOM, network, console, routing and storage — and then
+ * every verdict comes back without the `file:line` the whole product leads with, because the JSX
+ * stamper is Babel and a `.svelte` file is not JavaScript. This is the Svelte half.
+ *
+ * ## Where in the pipeline
+ *
+ * A Vite `transform` on the RAW component source, in the Reticle plugin, which already declares
+ * `enforce: 'pre'` — so it runs before `@sveltejs/vite-plugin-svelte` and hands the compiler markup
+ * that already carries the attribute. Getting the order wrong is the failure mode worth naming: run
+ * it after, and there is no markup left to stamp, only generated JavaScript whose original line
+ * numbers are gone. A Svelte *preprocessor* would also work and would be equally correct, but it has
+ * to be wired into `svelte.config.js` by the user, and an integration nobody enables is an
+ * integration that does not exist.
+ *
+ * ## Why the compiler is loaded the way it is
+ *
+ * `svelte` must never become a dependency of this package: a React project installing the Vite
+ * plugin must not acquire a Svelte compiler, and its build must be unaffected. So the compiler is
+ * resolved lazily, from the APP's directory, only when a `.svelte` id actually arrives, and its
+ * absence returns null rather than throwing. Same shape as the optional `playwright` import in the
+ * server's pool launcher.
+ *
+ * Resolution is synchronous (`createRequire`) rather than `await import()` because Svelte ships a CJS
+ * build of its compiler and the plugin's `transform` is synchronous — making the whole hook async to
+ * fetch an optional dependency would change the contract of every other path through it.
+ *
+ * ## Scope
+ *
+ * The attribute only. Mapping a DOM node to the COMPONENT that rendered it — what `@reticlehq/react`
+ * does through the fiber tree — is a separate and much larger problem, and is not attempted here.
+ */
+/** Files this module stamps. `.svelte.ts` (a runes module) is code, not markup — excluded. */
+export const SVELTE_FILE = /\.svelte$/;
+/** Element node types that are a real place in the DOM, in Svelte 5's AST and Svelte 4's. */
+const HOST_ELEMENT_TYPES = new Set(['RegularElement', 'Element']);
+/** The `parent` back-reference some AST shapes carry; following it would walk forever. */
+const PARENT_KEY = 'parent';
+/** Resolved once per process: `null` means "looked, not installed" and must not be retried per file. */
+let cachedCompiler;
+function defaultLoadCompiler() {
+    if (cachedCompiler !== undefined)
+        return cachedCompiler;
+    cachedCompiler = null;
+    // From the APP's root first. The plugin may be linked, hoisted, or in a pnpm store far from the
+    // project, and the compiler that matters is the one the app's own Svelte plugin will use.
+    for (const from of [`${process.cwd()}/package.json`, import.meta.url]) {
+        try {
+            cachedCompiler = createRequire(from)('svelte/compiler');
+            break;
+        }
+        catch {
+            // Not resolvable from here — try the next origin, then give up silently.
+        }
+    }
+    return cachedCompiler;
+}
+/**
+ * A character offset as Babel would report it: 1-based line, 0-based column.
+ *
+ * Matching Babel exactly is not cosmetic — `parseSourceAttr` in the browser SDK reads one format,
+ * and a Svelte pointer that was 0-based on line would land every verdict one line off while looking
+ * completely plausible.
+ */
+export function offsetToLineColumn(source, offset) {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < offset && i < source.length; i++) {
+        if ('\n' === source[i]) {
+            line += 1;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: offset - lineStart };
+}
+/** Project-relative, forward-slashed. A pointer must be the same string on Windows as on Linux. */
+function sourcePathFor(id, cwd = process.cwd()) {
+    return relative(cwd, id).replace(/\\/g, '/');
+}
+function isElementNode(value) {
+    if (null === value || typeof value !== 'object')
+        return false;
+    const node = value;
+    return ('string' === typeof node.type &&
+        HOST_ELEMENT_TYPES.has(node.type) &&
+        'string' === typeof node.name &&
+        'number' === typeof node.start);
+}
+function isAlreadyStamped(node) {
+    return (node.attributes ?? []).some((attr) => attr !== null &&
+        'object' === typeof attr &&
+        attr.name === DATA_RETICLE_SOURCE_ATTR);
+}
+/**
+ * Collect every host element in the AST.
+ *
+ * A GENERIC walk over the object graph rather than a switch over Svelte's block types. `{#if}`,
+ * `{#each}`, `{#await}`, `{#key}`, `{#snippet}` and whatever the next release adds each nest their
+ * children under a differently-named field, and a hand-written descent silently misses the ones it
+ * has not heard of — elements inside an `{#each}` would simply never be stamped, with nothing to
+ * indicate they were skipped.
+ */
+function collectElements(root) {
+    const found = [];
+    const seen = new Set();
+    const visit = (value) => {
+        if (null === value || typeof value !== 'object' || seen.has(value))
+            return;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (isElementNode(value) && !isAlreadyStamped(value))
+            found.push(value);
+        for (const [key, child] of Object.entries(value)) {
+            if (key !== PARENT_KEY)
+                visit(child);
+        }
+    };
+    visit(root);
+    return found;
+}
+/**
+ * Stamp `data-reticle-source="file:line:column"` on every host element of a `.svelte` component.
+ *
+ * Returns null — never throws — when the compiler is absent or the component does not parse. In dev
+ * the transform runs on every keystroke, so a half-typed component is the NORMAL case; failing the
+ * build over one would make Reticle the reason the dev server is red, for a feature that is pure
+ * enrichment on top of an app that otherwise works.
+ */
+export function stampSvelte(code, id, load = defaultLoadCompiler) {
+    const compiler = load();
+    if (null === compiler)
+        return null;
+    let ast;
+    try {
+        // `modern: true` selects Svelte 5's AST; Svelte 4 ignores the option and returns its own shape.
+        // `collectElements` accepts both, so one call covers either major without a version probe.
+        ast = compiler.parse(code, { modern: true });
+    }
+    catch {
+        return null;
+    }
+    const elements = collectElements(ast);
+    if (0 === elements.length)
+        return null;
+    const file = sourcePathFor(id);
+    // Insert from the LAST element backwards: every insertion shifts the offsets after it, and
+    // applying them in source order would put each stamp progressively further from its own tag.
+    const ordered = [...elements].sort((a, b) => b.start - a.start);
+    let out = code;
+    for (const node of ordered) {
+        const { line, column } = offsetToLineColumn(code, node.start);
+        const insertAt = node.start + 1 + node.name.length;
+        const attribute = ` ${DATA_RETICLE_SOURCE_ATTR}="${file}:${String(line)}:${String(column)}"`;
+        out = `${out.slice(0, insertAt)}${attribute}${out.slice(insertAt)}`;
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "2.3.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,11 +35,12 @@
   ],
   "dependencies": {
     "@babel/core": "^7.26.0",
-    "@reticlehq/babel-plugin": "2.3.0",
-    "@reticlehq/core": "2.3.0"
+    "@reticlehq/babel-plugin": "2.5.0",
+    "@reticlehq/core": "2.5.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
+    "svelte": "^5.56.8",
     "vite": "^8"
   },
   "peerDependencies": {
@@ -59,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'"
   }
 }