@reticlehq/vite-plugin 2.14.0 → 3.1.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-export declare const RETICLE_VITE_PLUGIN_NAME = "reticle";
+import { type InjectionWatch } from './injection-postcondition.js';
+export { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
 /**
  * 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
@@ -88,31 +89,22 @@ export interface ReticleVitePluginOptions {
      * 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.
+     * Exposed HERE because the plugin is the only `connect()` most apps have and a second `connect()`
+     * is a no-op, so an SDK option the plugin cannot pass is an option that does not exist.
      *
-     * Also settable as `VITE_RETICLE_CAPTURE_BODIES=1`, so it can be turned on for one debugging
-     * session without editing vite.config.
+     * Also settable as `VITE_RETICLE_CAPTURE_BODIES=1`.
      */
     captureNetworkBodies?: boolean;
     /**
      * Retain a FAILED request's response body even with `captureNetworkBodies` off. Default true.
      *
-     * Reachable here for the reason `captureNetworkBodies` is: the plugin is the only `connect()`
-     * most apps ever have. Also settable as `VITE_RETICLE_NO_ERROR_BODIES=1`, which turns it OFF --
-     * the inverse of the other env vars, because this is the one that defaults on (#800).
+     * Also settable as `VITE_RETICLE_NO_ERROR_BODIES=1`, which turns it OFF -- the inverse of the
+     * other env vars, because this is the one that defaults on (#800).
      */
     captureErrorBodies?: boolean;
     /**
      * Make Reticle's OWN presenter visible to snapshots and queries. CONTRIBUTORS ONLY.
      *
-     * Reachable here for the same reason `captureNetworkBodies` is: the plugin is the only `connect()`
-     * most apps ever have, so an SDK option the plugin cannot pass is an option that does not exist.
-     *
      * The presenter is hidden from every tool by design — an agent that can drive Reticle's own
      * interface can fabricate its own impact report. The cost is that a HUD change is the only kind of
      * change Reticle cannot be used to check. This is the hatch for that one case, and the app reports
@@ -127,9 +119,7 @@ export interface ReticleVitePluginOptions {
      * 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.
+     * the `Host` header, anything with cookie-scoped auth on a custom dev hostname.
      *
      * 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
@@ -138,8 +128,7 @@ export interface ReticleVitePluginOptions {
      * 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.
+     * Also settable as `VITE_RETICLE_ALLOW_NON_LOCALHOST=1`.
      */
     allowNonLocalhost?: boolean;
     /**
@@ -230,6 +219,9 @@ export interface ReticleVitePlugin {
     buildEnd?: () => void;
     /** Runs the dev-mode injection check immediately. Test seam for the deferred timer. */
     checkInjectedForTest?: () => void;
+    checkHtmlHookForTest?: () => void;
+    /** The post-condition watch itself, so a test drives the real predicate and not a copy of it. */
+    injectionWatchForTest?: InjectionWatch;
 }
 /**
  * The slice of Vite's dev server this plugin touches, structurally — so `vite` stays a peer the
@@ -259,6 +251,9 @@ export interface ViteDevServerLike {
     middlewares: {
         use(handler: (req: {
             url?: string | undefined;
+            headers?: {
+                accept?: string | undefined;
+            } | undefined;
         }, res: unknown, next: () => void) => void): void;
     };
     moduleGraph: {
@@ -286,10 +281,9 @@ export declare function readPairingToken(): string | undefined;
 /**
  * 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.
+ * Imported by CONVENTION rather than by patching the app's entry file: the connect is injected into
+ * a virtual module, so the alternative is `init` editing `src/main.tsx` — a file the user owns — for
+ * something that is opt-in enrichment. Convention costs one `existsSync`.
  */
 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. */
@@ -297,14 +291,11 @@ export declare function findDevModule(root: string, exists: (p: string) => boole
 /**
  * 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
+ * The injected connect must NOT 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.
+ * its peers has no business in a Vue app — and the injected import would then name a package that is
+ * not installed, so nothing connects and the page reports no session with no obvious cause.
  *
  * 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
@@ -339,5 +330,4 @@ export declare function connectModuleSource(options: ReticleVitePluginOptions, d
  */
 export declare const JOURNAL_IGNORE: RegExp;
 export declare function reticle(options?: ReticleVitePluginOptions): ReticleVitePlugin;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export declare const RETICLE_VITE_PLUGIN_NAME = "reticle";
+import { type InjectionWatch } from './injection-postcondition.js';
+export { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
 /**
  * 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
@@ -88,31 +89,22 @@ export interface ReticleVitePluginOptions {
      * 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.
+     * Exposed HERE because the plugin is the only `connect()` most apps have and a second `connect()`
+     * is a no-op, so an SDK option the plugin cannot pass is an option that does not exist.
      *
-     * Also settable as `VITE_RETICLE_CAPTURE_BODIES=1`, so it can be turned on for one debugging
-     * session without editing vite.config.
+     * Also settable as `VITE_RETICLE_CAPTURE_BODIES=1`.
      */
     captureNetworkBodies?: boolean;
     /**
      * Retain a FAILED request's response body even with `captureNetworkBodies` off. Default true.
      *
-     * Reachable here for the reason `captureNetworkBodies` is: the plugin is the only `connect()`
-     * most apps ever have. Also settable as `VITE_RETICLE_NO_ERROR_BODIES=1`, which turns it OFF --
-     * the inverse of the other env vars, because this is the one that defaults on (#800).
+     * Also settable as `VITE_RETICLE_NO_ERROR_BODIES=1`, which turns it OFF -- the inverse of the
+     * other env vars, because this is the one that defaults on (#800).
      */
     captureErrorBodies?: boolean;
     /**
      * Make Reticle's OWN presenter visible to snapshots and queries. CONTRIBUTORS ONLY.
      *
-     * Reachable here for the same reason `captureNetworkBodies` is: the plugin is the only `connect()`
-     * most apps ever have, so an SDK option the plugin cannot pass is an option that does not exist.
-     *
      * The presenter is hidden from every tool by design — an agent that can drive Reticle's own
      * interface can fabricate its own impact report. The cost is that a HUD change is the only kind of
      * change Reticle cannot be used to check. This is the hatch for that one case, and the app reports
@@ -127,9 +119,7 @@ export interface ReticleVitePluginOptions {
      * 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.
+     * the `Host` header, anything with cookie-scoped auth on a custom dev hostname.
      *
      * 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
@@ -138,8 +128,7 @@ export interface ReticleVitePluginOptions {
      * 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.
+     * Also settable as `VITE_RETICLE_ALLOW_NON_LOCALHOST=1`.
      */
     allowNonLocalhost?: boolean;
     /**
@@ -230,6 +219,9 @@ export interface ReticleVitePlugin {
     buildEnd?: () => void;
     /** Runs the dev-mode injection check immediately. Test seam for the deferred timer. */
     checkInjectedForTest?: () => void;
+    checkHtmlHookForTest?: () => void;
+    /** The post-condition watch itself, so a test drives the real predicate and not a copy of it. */
+    injectionWatchForTest?: InjectionWatch;
 }
 /**
  * The slice of Vite's dev server this plugin touches, structurally — so `vite` stays a peer the
@@ -259,6 +251,9 @@ export interface ViteDevServerLike {
     middlewares: {
         use(handler: (req: {
             url?: string | undefined;
+            headers?: {
+                accept?: string | undefined;
+            } | undefined;
         }, res: unknown, next: () => void) => void): void;
     };
     moduleGraph: {
@@ -286,10 +281,9 @@ export declare function readPairingToken(): string | undefined;
 /**
  * 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.
+ * Imported by CONVENTION rather than by patching the app's entry file: the connect is injected into
+ * a virtual module, so the alternative is `init` editing `src/main.tsx` — a file the user owns — for
+ * something that is opt-in enrichment. Convention costs one `existsSync`.
  */
 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. */
@@ -297,14 +291,11 @@ export declare function findDevModule(root: string, exists: (p: string) => boole
 /**
  * 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
+ * The injected connect must NOT 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.
+ * its peers has no business in a Vue app — and the injected import would then name a package that is
+ * not installed, so nothing connects and the page reports no session with no obvious cause.
  *
  * 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
@@ -339,4 +330,3 @@ export declare function connectModuleSource(options: ReticleVitePluginOptions, d
  */
 export declare const JOURNAL_IGNORE: RegExp;
 export declare function reticle(options?: ReticleVitePluginOptions): ReticleVitePlugin;
-export {};

package/dist/index.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { missingTokenWarning } from './missing-token.js';
-import { ensurePairingToken } from './ensure-token.js';
+import { missingTokenWarning } from './token/missing-token.js';
+import { ensurePairingToken } from './token/ensure-token.js';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { transformSync } from '@babel/core';
@@ -11,7 +11,9 @@ import { discoverDaemonPort } from './discover-port.js';
 import { announceDevServer } from './announce.js';
 import { SVELTE_FILE, stampSvelte } from './svelte-source.js';
 import { resolvableChain, sdkPackageVersion, sdkBuildFingerprint, viteMajor, optimizerOptionsKey, optimizerOptions, } from './installed.js';
-export const RETICLE_VITE_PLUGIN_NAME = 'reticle';
+import { createInjectionWatch, notInjectedMessage, } from './injection-postcondition.js';
+import { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
+export { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
 // 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.
@@ -84,22 +86,14 @@ onScheduleFiberRoot:function(){},onCommitFiberRoot:fire,onPostCommitFiberRoot:fu
 }else{var prev=h.onCommitFiberRoot;h.onCommitFiberRoot=function(){try{fire.apply(null,arguments);}catch(e){}
 if(typeof prev==='function')return prev.apply(this,arguments);};}
 }catch(e){}})();`;
-/**
- * How long after serving the HTML to wait before concluding the entry was never injected.
- *
- * Generous on purpose: the browser has to request the entry, and a cold dev server transforming a
- * 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.
+ * `reticle-dev` module — in a healthy session, the daemon starting after Vite is one change and a
+ * dev module appearing is another. Past a handful, an input is oscillating, which makes Vite
+ * re-resolve the module on every page load: the reload loop this counter makes audible.
  */
 const CONNECT_CHURN_LIMIT = 5;
 /**
@@ -260,10 +254,9 @@ function connectArgs(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.
+ * Imported by CONVENTION rather than by patching the app's entry file: the connect is injected into
+ * a virtual module, so the alternative is `init` editing `src/main.tsx` — a file the user owns — for
+ * something that is opt-in enrichment. Convention costs one `existsSync`.
  */
 export const RETICLE_DEV_MODULE_CANDIDATES = [
     'src/reticle-dev.ts',
@@ -282,14 +275,11 @@ export function findDevModule(root, exists) {
 /**
  * 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
+ * The injected connect must NOT 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.
+ * its peers has no business in a Vue app — and the injected import would then name a package that is
+ * not installed, so nothing connects and the page reports no session with no obvious cause.
  *
  * 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
@@ -388,6 +378,14 @@ export function reticle(options = {}) {
     const warn = options.onWarn ?? ((message) => globalThis.console.warn(message));
     /** Whether connect() actually reached a module — asserted at buildEnd, never assumed. */
     let injected = false;
+    /**
+     * Whether Vite ever asked us to transform the app's HTML.
+     *
+     * On the web this is how the connect script gets in, so "this never happened" and "this app will
+     * not connect" are the same statement — which is what makes a warning safe here, unlike the
+     * desktop entry-module flag above.
+     */
+    let htmlTransformed = false;
     /**
      * Resolve port + token at the moment of injection, not at plugin construction. By the time a
      * module is served or built the daemon is up and has written its pairing token; resolving early
@@ -415,37 +413,17 @@ export function reticle(options = {}) {
     /** 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.
+     * When to conclude injection failed, and which of the three messages to say. Lives beside those
+     * messages rather than here: choosing between them is the subtlety, and it was a thousand lines
+     * from the wording it chose. The flags are read through getters because both flip mid-session.
      */
-    const notInjectedMessage = () => `[${RETICLE_VITE_PLUGIN_NAME}] could not inject reticle.connect(): the HTML entry module was ` +
-        'never matched, so this app carries no instrumentation and will never connect. Check that ' +
-        'index.html references your entry with a <script type="module" src="...">, or pass ' +
-        '`inject: false` and call reticle.connect({ token: __RETICLE_TOKEN__ }) yourself. The plugin ' +
-        'still inlines that define; a connect without it is refused.';
-    /**
-     * The DEV message, which must be weaker — and this is the whole reason the two are separate.
-     *
-     * In serve, `injected` records "my transform ran THIS session", which is not the same as "the app
-     * has no connect()". Vite serves an unchanged module straight from its transform cache, so on a
-     * warm cache the transform never runs, the flag stays false, and the old wording announced that
-     * the app "will never connect" while the served entry demonstrably contained the injection —
-     * verified by fetching it from the dev server. A false alarm, in the tool whose entire argument is
-     * that it does not raise them.
-     *
-     * So dev reports what it actually knows: unconfirmed, with the benign explanation first.
-     */
-    const unconfirmedInjectionMessage = () => `[${RETICLE_VITE_PLUGIN_NAME}] could not confirm reticle.connect() was injected: the HTML entry ` +
-        'module was not transformed this session. That is expected when Vite served it from its ' +
-        'transform cache. If the app does not appear in `reticle status`, restart the dev server with ' +
-        '`--force` to bypass the cache, then check that index.html references your entry with a ' +
-        '<script type="module" src="...">.';
-    /** Warn (never throw) in dev — a running dev server should report the doubt, not die of it. */
-    const checkInjected = () => {
-        if (!desktop || !inject || injected)
-            return;
-        warn(unconfirmedInjectionMessage());
-    };
+    const watch = createInjectionWatch({
+        desktop,
+        inject,
+        injected: () => injected,
+        htmlTransformed: () => htmlTransformed,
+        warn,
+    });
     return {
         name: RETICLE_VITE_PLUGIN_NAME,
         // Web: serve-only, so a production bundle can never carry the SDK — gating is the tool's job.
@@ -456,42 +434,31 @@ export function reticle(options = {}) {
         /**
          * Declare the SDK itself and the optimizer cache fingerprint.
          *
-         * The browser SDK used to need extra CJS query-engine deps here. It no longer imports that
-         * second accessibility engine, so keeping those names would make Vite pre-bundle packages the
-         * app may not have and blame Reticle for a false `Failed to resolve dependency` warning.
+         * The SDK itself only. It does not import a second accessibility engine, and naming CJS deps it
+         * does not use would make Vite pre-bundle packages the app may not have, then blame Reticle for a
+         * false `Failed to resolve dependency` warning.
          */
         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.
+            // at the plugin's own location. Vite defaults an omitted root to the cwd, and so does this.
             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.
+                // rewritten atomically as `ambient.json.tmp` + rename on a live session. Unignored, every
+                // journal write reads as a project file changing and Vite answers with a full page reload,
+                // which is a loop with no exit: page loads -> SDK connects and streams events -> daemon
+                // journals them -> Vite reloads the page -> SDK reconnects.
                 //
-                // 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.
+                // A RegExp, NOT a glob: chokidar dropped glob support in v4, and Vite 7+ ships v4/v5, where
+                // `**/.reticle/**` is silently accepted and matches nothing. Vite's own defaults are globs
+                // and have the same problem, so their shape is not safe to copy 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.
+                // the platform's own form. Appends to the app's list rather than replacing it.
                 server: {
                     watch: {
                         ignored: mergeIgnored(config.server?.watch?.ignored, JOURNAL_IGNORE),
@@ -499,8 +466,8 @@ export function reticle(options = {}) {
                 },
                 // 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
+                // SvelteKit's client hook, a custom entry — cannot reach a file only Node can read, so it
+                // would call connect() with no credential and the bridge would answer "authentication
                 // failed". Empty until the daemon has provisioned one; the page reloads once it has.
                 define: {
                     ...(config.define ?? {}),
@@ -598,29 +565,32 @@ export function reticle(options = {}) {
          * Serve the connect module fresh, every time.
          *
          * `load` reads the daemon's pairing token at serve time precisely because the daemon may start
-         * after the dev server — but Vite caches the module it produced, and answers every later request
-         * from that cache, INCLUDING after a full page reload. So a dev server started first served a
-         * tokenless connect module once and then kept serving it: the SDK got a 1008 `authentication
-         * failed`, stopped retrying (correctly — a wrong token does not fix itself), and `reticle status`
-         * showed no session while the page demonstrably contained `/@reticle-connect`. Only restarting
-         * the dev server cleared it, which is not a step anybody guesses.
+         * after the dev server — but Vite caches the module it produced and answers every later request
+         * from that cache, INCLUDING after a full page reload. A dev server started first therefore keeps
+         * serving a tokenless connect module: the SDK gets a 1008 `authentication failed` and stops
+         * retrying (correctly — a wrong token does not fix itself), so `reticle status` shows no session
+         * while the page demonstrably contains `/@reticle-connect`, and only a dev-server restart clears
+         * it.
          *
          * Dropping the cached module before it is served makes `load` re-read the token, so starting the
          * 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.
+         * Only when the source would ACTUALLY differ, though. A module force-invalidated on every
+         * request is re-resolved against Vite's dep optimizer on every page load, which is a
+         * self-sustaining reload loop: reload → request → invalidate → re-resolve → reload. 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;
+            // The web post-condition is armed by the first DOCUMENT REQUEST, in the middleware below.
+            //
+            // Not from `transformIndexHtml`, because a framework that renders its own HTML never calls it
+            // and the check would be unreachable in the one case it exists for. But not from boot either:
+            // that fires whether or not anybody has opened the app, and tells a healthy project it will
+            // never connect. The request is the earliest moment the plugin knows enough to have an
+            // opinion.
             // Tell `~/.reticle` this dev server exists, the moment it is actually listening.
             //
             // This is the one fact nobody outside this process could observe: the plugin is loaded in the
@@ -666,6 +636,11 @@ export function reticle(options = {}) {
                 announce();
             }
             server.middlewares.use((req, _res, next) => {
+                // One middleware, two observations. A second `use()` would work equally well in Vite and
+                // is the obvious way to write this, but it makes the ORDER of registration load-bearing for
+                // anything that records a single handler — so both live here instead.
+                if (!desktop && watch.isDocumentRequest(req))
+                    watch.noteHtmlRequest();
                 // Matched against BOTH forms: plugin middlewares run ahead of Vite's own base
                 // middleware, so the request still carries `base` here, while a middleware-mode host may
                 // have stripped it already.
@@ -693,15 +668,13 @@ export function reticle(options = {}) {
                 return;
             throw new Error(notInjectedMessage());
         },
-        checkInjectedForTest: checkInjected,
+        checkInjectedForTest: watch.checkInjected,
+        checkHtmlHookForTest: watch.checkHtmlHookRan,
+        injectionWatchForTest: watch,
         transformIndexHtml() {
-            // 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 && 'serve' === command) {
-                const timer = setTimeout(checkInjected, DEV_INJECTION_GRACE_MS);
-                timer.unref?.();
-            }
+            htmlTransformed = true;
+            if (desktop && inject && 'serve' === command)
+                watch.armDesktopCheck();
             // Desktop injects via the entry module instead (see transform) — a tag here would be a dead
             // URL in a packaged build. A Vitest run gets nothing unless `inject: true` says otherwise —
             // see isVitestBrowserServer.

package/dist/injection-postcondition.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The check that says whether `reticle.connect()` actually made it into the page, and what to say
+ * when it did not.
+ *
+ * These three messages live together because choosing between them is the whole subtlety. Each says
+ * exactly as much as the plugin actually knows and no more, and getting that wrong in either
+ * direction has cost real users:
+ *
+ *  - Claim "this is broken" when it is not, and the tool whose entire pitch is that it does not
+ *    raise false alarms has just raised one.
+ *  - Say nothing when it IS broken, and someone waits twenty minutes for a session that can never
+ *    arrive.
+ */
+/**
+ * How long to wait before concluding that the connect script never made it in.
+ *
+ * Generous on purpose: the browser has to request the entry, and a cold dev server transforming a
+ * large app can take a moment. A false warning would train people to ignore a real one.
+ */
+export declare const DEV_INJECTION_GRACE_MS = 10000;
+/**
+ * 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.
+ */
+export declare const notInjectedMessage: () => string;
+/**
+ * The DEV message, which must be weaker — and this is the whole reason the two are separate.
+ *
+ * In serve, `injected` records "my transform ran THIS session", which is not the same as "the app
+ * has no connect()". Vite serves an unchanged module straight from its transform cache, so on a
+ * warm cache the transform never runs and the flag stays false, so wording that announces the app
+ * "will never connect" is a false alarm raised over a served entry that does contain the injection.
+ *
+ * So dev reports what it actually knows: unconfirmed, with the benign explanation first.
+ */
+export declare const unconfirmedInjectionMessage: () => string;
+/**
+ * The web message.
+ *
+ * On the web the connect script is added by `transformIndexHtml`. A framework that renders its own
+ * HTML never calls that hook, so the script is never added and the app never appears in
+ * `reticle status`. Known examples: SvelteKit, Nuxt, Astro, React Router in framework mode and
+ * TanStack Start. Each was found the same way — a user waiting on a session that could never
+ * arrive — so the plain-language cause comes first and the fix comes second.
+ */
+export declare const htmlHookNeverRanMessage: () => string;
+/**
+ * The state behind those three messages, and the rules for reaching each one.
+ *
+ * Beside the wording rather than in the plugin factory: choosing BETWEEN these messages is the whole
+ * subtlety, the flags are only ever read by these four functions, and every defect in this area has
+ * been a rule about when to speak rather than a bug in the speaking.
+ */
+export interface InjectionWatchDeps {
+    /** Desktop builds keep the certainty; web dev does not. See the two messages above. */
+    readonly desktop: boolean;
+    /** `inject: false` means the user wires connect() themselves; the plugin has no opinion then. */
+    readonly inject: boolean;
+    /** Whether the desktop entry module was transformed. Read late: it flips during the session. */
+    readonly injected: () => boolean;
+    /** Whether Vite ever asked us to transform the app's HTML. Read late, for the same reason. */
+    readonly htmlTransformed: () => boolean;
+    readonly warn: (message: string) => void;
+    /** Injected so a test does not wait ten real seconds. Defaults to the module-level timer. */
+    readonly schedule?: (run: () => void, ms: number) => void;
+}
+export interface InjectionWatch {
+    /** Record a browser asking for a page, and start the grace period from there. */
+    noteHtmlRequest: () => void;
+    /** A navigation, as opposed to the module and asset fetches Vite serves constantly. */
+    isDocumentRequest: (req: {
+        headers?: {
+            accept?: string | undefined;
+        } | undefined;
+    }) => boolean;
+    checkHtmlHookRan: () => void;
+    checkInjected: () => void;
+    /** Defer the desktop check past the HTML response, which lands before the entry module. */
+    armDesktopCheck: () => void;
+}
+export declare function createInjectionWatch(deps: InjectionWatchDeps): InjectionWatch;