npm - @reticlehq/vite-plugin - Versions diffs - 2.7.0 → 2.9.0 - Mend

@reticlehq/vite-plugin 2.7.0 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,275 @@
+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
+ * import resolution, so its bare import would fail in the browser. This path-like id is requested
+ * by the injected <script src> and served by the load hook below.
+ */
+export declare const RETICLE_CONNECT_MODULE = "/@reticle-connect";
+/**
+ * The pre-hook, as source for an inline <head> script.
+ *
+ * Deliberately dependency-free ES5 in a try/catch: it runs before anything else on the page, so it
+ * must not assume a bundler, a module system, or that React is present at all. It installs a faithful
+ * devtools hook (React calls `inject` and expects a renderer id back, and stores the renderer) and
+ * counts commits into a buffer the module-side meter adopts later.
+ */
+export declare const RENDER_PREHOOK_SOURCE = "(function(){try{\nvar K='__REACT_DEVTOOLS_GLOBAL_HOOK__',P='__reticleRenderPreHook';\nif(globalThis[P])return;\nvar B={commits:0,sinks:[]};\nglobalThis[P]=B;\nvar fire=function(){B.commits++;for(var i=0;i<B.sinks.length;i++){try{B.sinks[i].apply(null,arguments);}catch(e){}}};\nvar h=globalThis[K];\nif(h===undefined){\nglobalThis[K]={supportsFiber:true,renderers:new Map(),inject:function(r){var id=this.renderers.size+1;this.renderers.set(id,r);return id;},\nonScheduleFiberRoot:function(){},onCommitFiberRoot:fire,onPostCommitFiberRoot:function(){},onCommitFiberUnmount:function(){}};\n}else{var prev=h.onCommitFiberRoot;h.onCommitFiberRoot=function(){try{fire.apply(null,arguments);}catch(e){}\nif(typeof prev==='function')return prev.apply(this,arguments);};}\n}catch(e){}})();";
+/**
+ * Said ONCE, and it names the symptom the user is looking at rather than the mechanism, because the
+ * mechanism is invisible from a browser: the page reloads and nothing explains why.
+ */
+export declare const connectChurnWarning: () => string;
+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;
+    /**
+     * Stable project identity. Defaults to one derived from the app's package.json name + root path,
+     * so multi-project session scoping works with zero config. Override only for special setups.
+     */
+    projectId?: string;
+    /** Auth token forwarded to connect when the bridge requires one. */
+    token?: string;
+    /** Stamp data-reticle-source for React 19 source mapping. Default true (harmless on React <=18). */
+    sourceMapping?: boolean;
+    /** Auto-inject the dev-gated reticle.connect call. Default true. */
+    inject?: boolean;
+    /**
+     * This build is an Electron/Tauri renderer. Changes two things a desktop shell needs and a web app
+     * must not get:
+     *
+     *  - The plugin also applies to `vite build`. A packaged desktop renderer IS a production build
+     *    loaded from `file://` or a custom protocol — there is no dev server — so the default
+     *    `apply: 'serve'` drops the plugin entirely and the app ships with no `connect()` at all.
+     *  - `connect()` is called with `allowInProduction`, because that same renderer reports
+     *    NODE_ENV=production and the SDK's prod backstop would otherwise refuse to start.
+     *
+     * Off by default and never inferred: turning it on means an instrumented production BUNDLE, which
+     * is exactly what a web app must never ship. Keep it behind your own dev-only build (a dev target,
+     * or `process.env.NODE_ENV !== 'production'` in vite.config) so it cannot reach a release binary.
+     */
+    desktop?: boolean;
+    /**
+     * Record request/response BODIES on `reticle_network`, not just method/url/status.
+     *
+     * Off by default because a body is the one part of a request that routinely carries a card
+     * number, a token or a customer's address, and the daemon journals what it is told.
+     *
+     * It matters that this is reachable at all. The SDK has supported `captureNetworkBodies` on
+     * `connect()` since bodies existed, but the plugin — the documented one-line integration, and the
+     * only `connect()` most apps ever have — had no way to pass it, and calling `connect()` a second
+     * time is a no-op. So for every app wired the recommended way, a payload was unreachable: on a
+     * real payments dashboard, a refund POSTing `amount: 1187.01` into a paise field (a 100x
+     * under-refund) was visible to Playwright's request inspector and invisible here.
+     *
+     * Also settable as `VITE_RETICLE_CAPTURE_BODIES=1`, so it can be turned on for one debugging
+     * session without editing vite.config.
+     */
+    captureNetworkBodies?: boolean;
+    /**
+     * Let Reticle run when the page or the bridge is not on localhost.
+     *
+     * Off by default: the SDK refuses outside localhost so a page on the open internet cannot be
+     * instrumented by a bridge it happened to reach. Turn it on for a dev server that CANNOT be served
+     * on localhost — a host-based multi-tenant frontend, a white-label app resolving the tenant from
+     * the `Host` header, anything with cookie-scoped auth on a custom dev hostname. Without it those
+     * apps cannot use Reticle at all, because the plugin is the only `connect()` they have and a
+     * second, hand-written one is a no-op.
+     *
+     * NOT SUFFICIENT ON ITS OWN — a pairing token is also required. `connectionPolicy` in
+     * `@reticlehq/browser` refuses a non-localhost connect with "a pairing token is required outside
+     * localhost" whenever the token is missing or empty, whatever this flag says. The plugin supplies
+     * one automatically from the daemon's `~/.reticle/pairing-token` (see readPairingToken), so a
+     * started daemon is normally all it takes; pass `token` yourself only when the daemon's file is
+     * unreachable. A non-loopback BRIDGE additionally has to be `wss://`.
+     *
+     * Also settable as `VITE_RETICLE_ALLOW_NON_LOCALHOST=1`, so it can be turned on for one session
+     * without editing vite.config.
+     */
+    allowNonLocalhost?: boolean;
+    /**
+     * Where a diagnostic goes. Defaults to the console; injected so the dev-mode injection check is
+     * testable without capturing global console output.
+     */
+    onWarn?: (message: string) => void;
+}
+/** Structural Vite plugin shape — avoids a hard dependency on `vite` while staying assignable to its `Plugin`. */
+export interface ReticleVitePlugin {
+    name: string;
+    /**
+     * Vite's `config` hook. Used to declare the SDK's CJS runtime deps for pre-bundling — see the
+     * implementation for why omitting them makes the whole SDK fail to load on linked setups.
+     */
+    config?: (config: {
+        optimizeDeps?: {
+            include?: string[];
+            /** Whichever key the app used — the plugin reads both and writes the one this Vite wants. */
+            esbuildOptions?: Record<string, unknown>;
+            rolldownOptions?: Record<string, unknown>;
+        };
+        define?: Record<string, string>;
+        root?: string;
+        server?: {
+            watch?: {
+                ignored?: (string | RegExp)[];
+            };
+        };
+    }) => {
+        optimizeDeps: {
+            include: string[];
+            [optionsKey: string]: unknown;
+        };
+        define: Record<string, string>;
+        server: {
+            watch: {
+                ignored: (string | RegExp)[];
+            };
+        };
+    };
+    /** Absent in desktop mode, where the plugin must also run for `vite build`. */
+    apply?: 'serve';
+    enforce: 'pre';
+    transform: (code: string, id: string) => {
+        code: string;
+        map: string | null;
+    } | null;
+    resolveId: (id: string, importer?: string) => string | null;
+    load: (id: string) => string | null;
+    transformIndexHtml: (html: string) => HtmlTag[];
+    /** Vite hands over the resolved config; used to resolve the HTML entry exactly. */
+    configResolved?: (config: {
+        root?: string;
+        command?: string;
+    }) => void;
+    /** Dev-server hook: keeps the served connect module from outliving the token it was built without. */
+    configureServer?: (server: ViteDevServerLike) => void;
+    /** Build-time post-condition: desktop injection must have happened. */
+    buildEnd?: () => void;
+    /** Runs the dev-mode injection check immediately. Test seam for the deferred timer. */
+    checkInjectedForTest?: () => void;
+}
+/**
+ * The slice of Vite's dev server this plugin touches, structurally — so `vite` stays a peer the
+ * plugin never imports, the same way the Svelte compiler and Playwright are handled elsewhere.
+ */
+export interface ViteDevServerLike {
+    middlewares: {
+        use(handler: (req: {
+            url?: string | undefined;
+        }, res: unknown, next: () => void) => void): void;
+    };
+    moduleGraph: {
+        getModuleById(id: string): object | undefined;
+        invalidateModule(mod: object): void;
+    };
+}
+interface HtmlTag {
+    tag: string;
+    /** Absent on an inline script, which carries its source in `children` instead. */
+    attrs?: Record<string, string>;
+    /** Inline source, for a tag that has no `src`. */
+    children?: string;
+    /** `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. */
+/**
+ * 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;
+/**
+ * Which SDK package this app actually has, and whether `install()` applies.
+ *
+ * The injected connect used to name `@reticlehq/react` unconditionally. That is right for a React
+ * app and fatal for any other: `reticle init` gives a Vue or Svelte codebase the framework-neutral
+ * `@reticlehq/browser` — deliberately, because a package named `@reticlehq/react` with `react` in
+ * its peers has no business in a Vue app — and the injected import then names a package that is not
+ * installed, so nothing connects and the page reports no session with no obvious cause.
+ *
+ * Measured end to end on a pristine `npm create vite --template vue` app: init wrote every file
+ * correctly and the tab never dialled the daemon, because of this one specifier.
+ *
+ * The React kit WINS when both resolve: it is a superset (it re-exports the sensor and adds the
+ * adapter), so an app that has it wants component identity. `install()` is the adapter's alone and
+ * the sensor does not export it — naming it against the sensor would trade a missing module for a
+ * missing export.
+ */
+export declare function installedSdk(appRoot: string, canResolve?: (dep: string) => boolean): {
+    specifier: string;
+    usesInstall: boolean;
+};
+export declare function connectModuleSource(options: ReticleVitePluginOptions, devModule?: string | null): string;
+/**
+ * Reticle Vite plugin. Add to your `plugins` array and the entire integration is done:
+ *
+ * import { reticle } from '@reticlehq/vite-plugin';
+ * export default defineConfig({ plugins: [react(), reticle()] });
+ *
+ * `apply: 'serve'` means Vite drops the plugin entirely from `vite build`, so a web production
+ * bundle is never instrumented — gating is the tool's job, not a user-managed env check.
+ *
+ * `desktop: true` is the ONE documented exception, and it inverts that guarantee deliberately: a
+ * packaged Electron/Tauri renderer IS a production build with no dev server, so serve-only gating
+ * would ship an app with no connect() at all. The cost is that the flag hands gating back to the
+ * caller — keep it behind your own dev-only build target so an instrumented bundle can never reach
+ * a release binary.
+ */
+/**
+ * The daemon's journal directory, as a matcher every chokidar major honours.
+ *
+ * Exported so the one regression test can assert on the matcher itself rather than on a string that
+ * looked right and matched nothing.
+ */
+export declare const JOURNAL_IGNORE: RegExp;
+export declare function reticle(options?: ReticleVitePluginOptions): ReticleVitePlugin;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts CHANGED Viewed

@@ -21,6 +21,11 @@ export declare const RETICLE_CONNECT_MODULE = "/@reticle-connect";
  * counts commits into a buffer the module-side meter adopts later.
  */
 export declare const RENDER_PREHOOK_SOURCE = "(function(){try{\nvar K='__REACT_DEVTOOLS_GLOBAL_HOOK__',P='__reticleRenderPreHook';\nif(globalThis[P])return;\nvar B={commits:0,sinks:[]};\nglobalThis[P]=B;\nvar fire=function(){B.commits++;for(var i=0;i<B.sinks.length;i++){try{B.sinks[i].apply(null,arguments);}catch(e){}}};\nvar h=globalThis[K];\nif(h===undefined){\nglobalThis[K]={supportsFiber:true,renderers:new Map(),inject:function(r){var id=this.renderers.size+1;this.renderers.set(id,r);return id;},\nonScheduleFiberRoot:function(){},onCommitFiberRoot:fire,onPostCommitFiberRoot:function(){},onCommitFiberUnmount:function(){}};\n}else{var prev=h.onCommitFiberRoot;h.onCommitFiberRoot=function(){try{fire.apply(null,arguments);}catch(e){}\nif(typeof prev==='function')return prev.apply(this,arguments);};}\n}catch(e){}})();";
+/**
+ * Said ONCE, and it names the symptom the user is looking at rather than the mechanism, because the
+ * mechanism is invisible from a browser: the page reloads and nothing explains why.
+ */
+export declare const connectChurnWarning: () => string;
 export interface ReticleVitePluginOptions {
     /** Bridge WebSocket port. Defaults to the SDK default; only baked into connect when non-default. */
     port?: number;
@@ -79,6 +84,27 @@ export interface ReticleVitePluginOptions {
      * session without editing vite.config.
      */
     captureNetworkBodies?: boolean;
+    /**
+     * Let Reticle run when the page or the bridge is not on localhost.
+     *
+     * Off by default: the SDK refuses outside localhost so a page on the open internet cannot be
+     * instrumented by a bridge it happened to reach. Turn it on for a dev server that CANNOT be served
+     * on localhost — a host-based multi-tenant frontend, a white-label app resolving the tenant from
+     * the `Host` header, anything with cookie-scoped auth on a custom dev hostname. Without it those
+     * apps cannot use Reticle at all, because the plugin is the only `connect()` they have and a
+     * second, hand-written one is a no-op.
+     *
+     * NOT SUFFICIENT ON ITS OWN — a pairing token is also required. `connectionPolicy` in
+     * `@reticlehq/browser` refuses a non-localhost connect with "a pairing token is required outside
+     * localhost" whenever the token is missing or empty, whatever this flag says. The plugin supplies
+     * one automatically from the daemon's `~/.reticle/pairing-token` (see readPairingToken), so a
+     * started daemon is normally all it takes; pass `token` yourself only when the daemon's file is
+     * unreachable. A non-loopback BRIDGE additionally has to be `wss://`.
+     *
+     * Also settable as `VITE_RETICLE_ALLOW_NON_LOCALHOST=1`, so it can be turned on for one session
+     * without editing vite.config.
+     */
+    allowNonLocalhost?: boolean;
     /**
      * Where a diagnostic goes. Defaults to the console; injected so the dev-mode injection check is
      * testable without capturing global console output.
@@ -101,12 +127,22 @@ export interface ReticleVitePlugin {
         };
         define?: Record<string, string>;
         root?: string;
+        server?: {
+            watch?: {
+                ignored?: (string | RegExp)[];
+            };
+        };
     }) => {
         optimizeDeps: {
             include: string[];
             [optionsKey: string]: unknown;
         };
         define: Record<string, string>;
+        server: {
+            watch: {
+                ignored: (string | RegExp)[];
+            };
+        };
     };
     /** Absent in desktop mode, where the plugin must also run for `vite build`. */
     apply?: 'serve';
@@ -190,6 +226,27 @@ export declare function readPairingToken(): string | undefined;
 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;
+/**
+ * Which SDK package this app actually has, and whether `install()` applies.
+ *
+ * The injected connect used to name `@reticlehq/react` unconditionally. That is right for a React
+ * app and fatal for any other: `reticle init` gives a Vue or Svelte codebase the framework-neutral
+ * `@reticlehq/browser` — deliberately, because a package named `@reticlehq/react` with `react` in
+ * its peers has no business in a Vue app — and the injected import then names a package that is not
+ * installed, so nothing connects and the page reports no session with no obvious cause.
+ *
+ * Measured end to end on a pristine `npm create vite --template vue` app: init wrote every file
+ * correctly and the tab never dialled the daemon, because of this one specifier.
+ *
+ * The React kit WINS when both resolve: it is a superset (it re-exports the sensor and adds the
+ * adapter), so an app that has it wants component identity. `install()` is the adapter's alone and
+ * the sensor does not export it — naming it against the sensor would trade a missing module for a
+ * missing export.
+ */
+export declare function installedSdk(appRoot: string, canResolve?: (dep: string) => boolean): {
+    specifier: string;
+    usesInstall: boolean;
+};
 export declare function connectModuleSource(options: ReticleVitePluginOptions, devModule?: string | null): string;
 /**
  * Reticle Vite plugin. Add to your `plugins` array and the entire integration is done:
@@ -206,5 +263,12 @@ export declare function connectModuleSource(options: ReticleVitePluginOptions, d
  * caller — keep it behind your own dev-only build target so an instrumented bundle can never reach
  * a release binary.
  */
+/**
+ * The daemon's journal directory, as a matcher every chokidar major honours.
+ *
+ * Exported so the one regression test can assert on the matcher itself rather than on a string that
+ * looked right and matched nothing.
+ */
+export declare const JOURNAL_IGNORE: RegExp;
 export declare function reticle(options?: ReticleVitePluginOptions): ReticleVitePlugin;
 export {};

package/dist/index.js CHANGED Viewed

@@ -15,6 +15,8 @@ export const RETICLE_VITE_PLUGIN_NAME = 'reticle';
 // 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';
+/** The framework-neutral sensor, which a Vue or Svelte app gets instead. See installedSdk. */
+const RETICLE_SENSOR = '@reticlehq/browser';
 /**
  * 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
@@ -61,6 +63,27 @@ if(typeof prev==='function')return prev.apply(this,arguments);};}
  * large app can take a moment. A false warning would train people to ignore a real one.
  */
 const DEV_INJECTION_GRACE_MS = 10_000;
+/**
+ * How many times the connect module's source may legitimately change in one dev-server session
+ * before the plugin says so.
+ *
+ * The source is a function of the port, the projectId, the pairing token and whether the app has a
+ * `reticle-dev` module. In a healthy session that settles almost immediately: the daemon starting
+ * after Vite is one change, a dev module being created is another. Anything past a handful means
+ * an input is oscillating, and an oscillating connect module is what makes Vite re-resolve it on
+ * every page load — the reload loop this counter exists to make audible instead of mysterious.
+ */
+const CONNECT_CHURN_LIMIT = 5;
+/**
+ * Said ONCE, and it names the symptom the user is looking at rather than the mechanism, because the
+ * mechanism is invisible from a browser: the page reloads and nothing explains why.
+ */
+export const connectChurnWarning = () => `[${RETICLE_VITE_PLUGIN_NAME}] the injected connect module has changed ${String(CONNECT_CHURN_LIMIT)} ` +
+    'times in one dev-server session. Something it depends on (the bridge port, the pairing token, ' +
+    'or a reticle-dev module appearing and disappearing) is not settling, and that can make the page ' +
+    'reload repeatedly. Reticle will keep serving the newest version. Please report this at ' +
+    'https://github.com/ReticleHQ/reticle/issues with your vite.config and whether more than one ' +
+    'daemon is running (`npx @reticlehq/server status`).';
 /**
  * Is this resolved module id the one the HTML referenced?
  *
@@ -220,6 +243,12 @@ function connectArgs(options) {
     if (true === options.captureNetworkBodies || '1' === process.env['VITE_RETICLE_CAPTURE_BODIES']) {
         args['captureNetworkBodies'] = true;
     }
+    // Same shape, same reason: without it an app that cannot be served on localhost has no way to
+    // reach the SDK option at all. The pairing token still applies — see the option's docstring.
+    if (true === options.allowNonLocalhost ||
+        '1' === process.env['VITE_RETICLE_ALLOW_NON_LOCALHOST']) {
+        args['allowNonLocalhost'] = 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. */
@@ -245,9 +274,38 @@ export function findDevModule(root, exists) {
     }
     return null;
 }
+/**
+ * Which SDK package this app actually has, and whether `install()` applies.
+ *
+ * The injected connect used to name `@reticlehq/react` unconditionally. That is right for a React
+ * app and fatal for any other: `reticle init` gives a Vue or Svelte codebase the framework-neutral
+ * `@reticlehq/browser` — deliberately, because a package named `@reticlehq/react` with `react` in
+ * its peers has no business in a Vue app — and the injected import then names a package that is not
+ * installed, so nothing connects and the page reports no session with no obvious cause.
+ *
+ * Measured end to end on a pristine `npm create vite --template vue` app: init wrote every file
+ * correctly and the tab never dialled the daemon, because of this one specifier.
+ *
+ * The React kit WINS when both resolve: it is a superset (it re-exports the sensor and adds the
+ * adapter), so an app that has it wants component identity. `install()` is the adapter's alone and
+ * the sensor does not export it — naming it against the sensor would trade a missing module for a
+ * missing export.
+ */
+export function installedSdk(appRoot, canResolve = (dep) => null !== resolvableChain([dep], appRoot)) {
+    if (canResolve(RETICLE_PACKAGE))
+        return { specifier: RETICLE_PACKAGE, usesInstall: true };
+    if (canResolve(RETICLE_SENSOR))
+        return { specifier: RETICLE_SENSOR, usesInstall: false };
+    // Neither resolves: keep the historical name so the failure reads as "the SDK is not installed"
+    // rather than as a package nobody recognises.
+    return { specifier: RETICLE_PACKAGE, usesInstall: true };
+}
 export function connectModuleSource(options, devModule = null) {
     const args = connectArgs(options);
-    const base = `import { reticle, install } from '${RETICLE_PACKAGE}';\ninstall();\nreticle.connect(${args});\n`;
+    const sdk = installedSdk(options.root ?? process.cwd());
+    const named = sdk.usesInstall ? 'reticle, install' : 'reticle';
+    const call = sdk.usesInstall ? 'install();\n' : '';
+    const base = `import { ${named} } from '${sdk.specifier}';\n${call}reticle.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`;
@@ -267,6 +325,13 @@ export function connectModuleSource(options, devModule = null) {
  * caller — keep it behind your own dev-only build target so an instrumented bundle can never reach
  * a release binary.
  */
+/**
+ * The daemon's journal directory, as a matcher every chokidar major honours.
+ *
+ * Exported so the one regression test can assert on the matcher itself rather than on a string that
+ * looked right and matched nothing.
+ */
+export const JOURNAL_IGNORE = new RegExp(`(^|[\\\\/])${ReticleDir.ROOT.replace('.', '\\.')}([\\\\/]|$)`);
 export function reticle(options = {}) {
     const sourceMapping = options.sourceMapping !== false;
     const inject = options.inject !== false;
@@ -308,6 +373,16 @@ export function reticle(options = {}) {
         const sdkVersion = withToken.sdkVersion ?? sdkPackageVersion(appRoot);
         return { ...withToken, root: appRoot, sdkVersion };
     };
+    /**
+     * The connect module's source as it would be served RIGHT NOW. Recomputed rather than cached: the
+     * daemon's token and the app's dev module can both appear after the dev server started, which is
+     * the whole reason the module is re-read at all.
+     */
+    const currentConnectSource = () => connectModuleSource(resolveLazy(), root === undefined ? null : findDevModule(root, existsSync));
+    /** The source `load` last handed to Vite, or undefined before the first serve. */
+    let lastServedConnectSource;
+    /** How many times the served source has actually changed. See connectChurnWarning. */
+    let connectChanges = 0;
     /**
      * The BUILD message. A build always runs every transform, so "my transform never ran" and "the
      * bundle has no connect()" are the same statement there, and stating it as a certainty is correct.
@@ -369,6 +444,37 @@ export function reticle(options = {}) {
             const appRoot = config.root ?? process.cwd();
             const optimizerKey = optimizerOptionsKey(viteMajor(appRoot));
             return {
+                // Keep the daemon's journal out of the dev server's watcher.
+                //
+                // The daemon writes `.reticle/` into the PROJECT root — session journals, and `ambient.json`
+                // rewritten atomically as `ambient.json.tmp` + rename on a live session. Vite watches the
+                // project root and does not ignore that directory, so every journal write read as a project
+                // file changing and Vite answered with a full page reload.
+                //
+                // That is a loop with no exit: page loads -> SDK connects and streams events -> daemon
+                // journals them -> Vite reloads the page -> SDK reconnects -> more events. It ran several
+                // times a second for as long as the dev server was up, and the damage was total but
+                // misattributed: every ref went stale, every act_and_wait died mid-flight, and the log
+                // filled with connect/disconnect pairs that looked like a flapping SDK rather than a
+                // watcher chasing its own tail.
+                //
+                // A RegExp, not a glob, and that is the whole difference between this working and not.
+                // chokidar dropped glob support in v4 — Vite 7+ ships v4/v5, where a pattern like
+                // `**/.reticle/**` is silently accepted and matches nothing. MEASURED against the chokidar
+                // this repo resolves: with the glob, a write to `.reticle/ambient.json` still fires; with
+                // this RegExp it does not, while a normal file still does. Vite's own defaults are globs and
+                // have the same problem, which is why it is not safe to copy their shape here.
+                //
+                // Anchored on `^` or a separator so it matches the directory and not a file that merely ends
+                // in those characters, and both separators are accepted because chokidar reports the path in
+                // the platform's own form.
+                //
+                // Appends to the app's list rather than replacing it, so nothing it already excluded is lost.
+                server: {
+                    watch: {
+                        ignored: [...(config.server?.watch?.ignored ?? []), JOURNAL_IGNORE],
+                    },
+                },
                 // 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,
@@ -406,7 +512,11 @@ export function reticle(options = {}) {
                         // 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,
+                        //
+                        // Whichever SDK this app actually has: naming `@reticlehq/react` in a Vue app that was
+                        // given the sensor produces the exact boot warning the note below is about, for a
+                        // package that is correctly absent.
+                        installedSdk(appRoot).specifier,
                         // 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),
@@ -455,9 +565,9 @@ export function reticle(options = {}) {
         load(id) {
             if (!inject || id !== RETICLE_CONNECT_MODULE)
                 return null;
-            // 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);
+            const source = currentConnectSource();
+            lastServedConnectSource = source;
+            return source;
         },
         configResolved(config) {
             root = config.root;
@@ -475,17 +585,31 @@ export function reticle(options = {}) {
          * the dev server cleared it, which is not a step anybody guesses.
          *
          * Dropping the cached module before it is served makes `load` re-read the token, so starting the
-         * daemon and reloading the page is enough. Costs one string compare per request and re-runs a
-         * three-line module — no reason to be cleverer about when to invalidate.
+         * daemon and reloading the page is enough.
+         *
+         * Only when the source would ACTUALLY differ, though. This used to invalidate on every request
+         * for the module, forever — and a module that is force-invalidated on every request is
+         * re-resolved against Vite's dep optimizer on every page load, which is the shape of a
+         * self-sustaining reload loop: reload → request → invalidate → re-resolve → reload. Reported
+         * from the field on a Vite + React Router app pinned to a non-default port: every route
+         * reloaded the whole page about once a second, `/@reticle-connect` was fetched in every cycle,
+         * and removing the plugin stopped it instantly. Comparing the source first costs one string
+         * compare, keeps the late-daemon fix intact (the token appearing IS a change), and makes the
+         * module inert once it has settled.
          */
         configureServer(server) {
             if (!inject)
                 return;
             server.middlewares.use((req, _res, next) => {
                 if ((req.url ?? '').split('?')[0] === RETICLE_CONNECT_MODULE) {
-                    const mod = server.moduleGraph.getModuleById(RETICLE_CONNECT_MODULE);
-                    if (mod !== undefined)
-                        server.moduleGraph.invalidateModule(mod);
+                    if (currentConnectSource() !== lastServedConnectSource) {
+                        connectChanges++;
+                        if (CONNECT_CHURN_LIMIT === connectChanges)
+                            warn(connectChurnWarning());
+                        const mod = server.moduleGraph.getModuleById(RETICLE_CONNECT_MODULE);
+                        if (mod !== undefined)
+                            server.moduleGraph.invalidateModule(mod);
+                    }
                 }
                 next();
             });

package/dist/svelte-source.js CHANGED Viewed

@@ -49,6 +49,13 @@ function defaultLoadCompiler() {
     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.
+    //
+    // `import.meta.url` is this module's own location and is the ESM spelling of it. The package also
+    // ships a CJS build (an app without `"type": "module"` can only `require` its Vite config), where
+    // `import.meta` is empty — so that build SUBSTITUTES `__filename` here rather than leaving the
+    // expression to evaluate to nothing. Both artefacts therefore try the same two origins; see
+    // scripts/build-cjs.mjs. Reading it unguarded is deliberate: the build fails loudly if the
+    // substitution is ever dropped.
     for (const from of [`${process.cwd()}/package.json`, import.meta.url]) {
         try {
             cachedCompiler = createRequire(from)('svelte/compiler');