npm - @reticlehq/vite-plugin - Versions diffs - 2.13.1 → 3.1.0 - Mend

@reticlehq/vite-plugin 2.13.1 → 3.1.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 (20) hide show

package/dist/index.cjs +581 -463
package/dist/index.d.cts +85 -44
package/dist/index.d.ts +85 -44
package/dist/index.js +129 -106
package/dist/injection-postcondition.d.ts +81 -0
package/dist/injection-postcondition.js +123 -0
package/dist/installed.d.ts +2 -1
package/dist/plugin-name.d.ts +7 -0
package/dist/plugin-name.js +7 -0
package/dist/project-id.d.ts +24 -6
package/dist/project-id.js +67 -22
package/dist/vitest-browser.d.ts +31 -0
package/dist/vitest-browser.js +37 -0
package/dist/watch-ignore.d.ts +18 -0
package/dist/watch-ignore.js +26 -0
package/package.json +7 -6
/package/dist/{ensure-token.d.ts → token/ensure-token.d.ts} +0 -0
/package/dist/{ensure-token.js → token/ensure-token.js} +0 -0
/package/dist/{missing-token.d.ts → token/missing-token.d.ts} +0 -0
/package/dist/{missing-token.js → token/missing-token.js} +0 -0

package/dist/index.js CHANGED Viewed

@@ -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.
@@ -36,6 +38,33 @@ const NODE_MODULES = 'node_modules';
  * by the injected <script src> and served by the load hook below.
  */
 export const RETICLE_CONNECT_MODULE = '/@reticle-connect';
+/**
+ * The URL the injected `<script src>` must actually point at: `base` + the module id.
+ *
+ * {@link RETICLE_CONNECT_MODULE} is a SERVER-ROOT path, and emitting it verbatim is only correct
+ * when Vite is serving from the root. Under `base: '/playground/'` the browser asked for
+ * `/@reticle-connect`, Vite answered 404 with its own "did you mean /playground/@reticle-connect"
+ * hint, and the page rendered perfectly while never connecting (#676) — the exact failure shape
+ * Reticle exists to catch, in Reticle's own setup path.
+ *
+ * Vite does not prefix tags returned from `transformIndexHtml`, so the prefix has to be applied
+ * here. Only a path base is joined: Vite serves the dev app from the root when `base` is an
+ * external URL, so prefixing a CDN origin onto a dev-server module would point the tag off-host.
+ */
+import { mergeIgnored } from './watch-ignore.js';
+import { isVitestBrowserServer } from './vitest-browser.js';
+export function connectModuleUrl(base) {
+    if (undefined === base || !base.startsWith('/'))
+        return RETICLE_CONNECT_MODULE;
+    // Trimmed by slicing rather than with `/\/+$/`: a trailing-slash-run regex is a polynomial
+    // backtracking shape over a value that comes out of the user's config, and CodeQL is right to
+    // flag it. This is linear and says the same thing.
+    let end = base.length;
+    while (0 < end && '/' === base[end - 1])
+        end -= 1;
+    const trimmed = base.slice(0, end);
+    return 0 === trimmed.length ? RETICLE_CONNECT_MODULE : `${trimmed}${RETICLE_CONNECT_MODULE}`;
+}
 /**
  * The pre-hook, as source for an inline <head> script.
  *
@@ -57,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;
 /**
@@ -207,6 +228,16 @@ function connectArgs(options) {
     if (true === options.captureNetworkBodies || '1' === process.env['VITE_RETICLE_CAPTURE_BODIES']) {
         args['captureNetworkBodies'] = true;
     }
+    // Only the OPT-OUT is announced, never the default. The daemon reads absence as "unknown", so
+    // sending `true` here would say nothing it does not already assume — while sending `false` is the
+    // one fact a red verdict needs to stop prescribing a plugin this project has deliberately muted.
+    if (false === options.sourceMapping)
+        args['sourceMapping'] = false;
+    // The one option that defaults ON, so the env var and the config flag both DISABLE rather than
+    // enable. Emitted only when switched off; the default stays implicit in the SDK.
+    if (false === options.captureErrorBodies || '1' === process.env['VITE_RETICLE_NO_ERROR_BODIES']) {
+        args['captureErrorBodies'] = false;
+    }
     // Same shape, same reason. Off unless asked for, in a config or for one session.
     if (true === options.exposePresenter || '1' === process.env['VITE_RETICLE_EXPOSE_PRESENTER']) {
         args['exposePresenter'] = true;
@@ -223,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',
@@ -245,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
@@ -344,9 +371,21 @@ export function reticle(options = {}) {
     let root;
     /** 'serve' | 'build'. The dev check only applies to serve; buildEnd covers the other. */
     let command;
+    /** Vite's resolved `base`. Undefined until configResolved, which is before any HTML is served. */
+    let base;
+    /** True only when THIS server is Vitest's browser-mode runner — see isVitestBrowserServer. */
+    let vitestBrowser = false;
     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
@@ -374,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.
-     */
-    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.
+     * 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 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.
@@ -415,51 +434,40 @@ 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.
-                //
-                // 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.
+                // 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.
                 //
-                // 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: [...(config.server?.watch?.ignored ?? []), JOURNAL_IGNORE],
+                        ignored: mergeIgnored(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,
-                // 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 ?? {}),
@@ -550,34 +558,39 @@ export function reticle(options = {}) {
         configResolved(config) {
             root = config.root;
             command = config.command;
+            base = config.base;
+            vitestBrowser = isVitestBrowserServer(config);
         },
         /**
          * 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
@@ -623,7 +636,16 @@ export function reticle(options = {}) {
                 announce();
             }
             server.middlewares.use((req, _res, next) => {
-                if ((req.url ?? '').split('?')[0] === RETICLE_CONNECT_MODULE) {
+                // 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.
+                const requestPath = (req.url ?? '').split('?')[0];
+                if (requestPath === RETICLE_CONNECT_MODULE || requestPath === connectModuleUrl(base)) {
                     if (currentConnectSource() !== lastServedConnectSource) {
                         connectChanges++;
                         if (CONNECT_CHURN_LIMIT === connectChanges)
@@ -646,19 +668,20 @@ 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.
+            // URL in a packaged build. A Vitest run gets nothing unless `inject: true` says otherwise —
+            // see isVitestBrowserServer.
             if (!inject || desktop)
                 return [];
+            if (true !== options.inject && vitestBrowser)
+                return [];
             return [
                 // A CLASSIC inline script in <head>, and it has to be both.
                 //
@@ -669,7 +692,7 @@ export function reticle(options = {}) {
                 // `renderers.size === 0`, so the render meter counted zero forever while the docs advertised
                 // commit counts. This runs during parse, before any module, and the meter adopts its buffer.
                 { tag: 'script', children: RENDER_PREHOOK_SOURCE, injectTo: 'head-prepend' },
-                { tag: 'script', attrs: { type: 'module', src: RETICLE_CONNECT_MODULE }, injectTo: 'body' },
+                { tag: 'script', attrs: { type: 'module', src: connectModuleUrl(base) }, injectTo: 'body' },
             ];
         },
     };

package/dist/injection-postcondition.d.ts ADDED Viewed

@@ -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;

package/dist/injection-postcondition.js ADDED Viewed

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ */
+import { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
+/**
+ * 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 const DEV_INJECTION_GRACE_MS = 10_000;
+/**
+ * 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 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 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 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="...">.';
+/**
+ * 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 const htmlHookNeverRanMessage = () => `[${RETICLE_VITE_PLUGIN_NAME}] this app will never connect: the dev server never asked this ` +
+    'plugin to transform any HTML, so reticle.connect() was never added to the page. That usually ' +
+    'means your framework renders its own HTML instead of serving index.html — SvelteKit, Nuxt, ' +
+    'Astro, React Router (framework mode) and TanStack Start all do. Fix: import ' +
+    "'@reticlehq/browser' and call reticle.connect({ token: __RETICLE_TOKEN__ }) yourself from your " +
+    'app entry file, and pass `inject: false` to this plugin so the two do not both try.';
+const defaultSchedule = (run, ms) => {
+    const timer = setTimeout(run, ms);
+    // Never hold a dev server open on account of a warning it may not even need to print.
+    timer.unref?.();
+};
+export function createInjectionWatch(deps) {
+    /**
+     * Has a browser actually asked this dev server for a PAGE?
+     *
+     * The fact that makes "the HTML hook never ran" mean anything. `transformIndexHtml` only runs when
+     * a document is requested, so on a dev server nobody has opened it has correctly never run — and
+     * a check that cannot tell that apart from a framework owning its own HTML will call a perfectly
+     * healthy app permanently broken. That is what it did: the timer was armed at server boot, so ten
+     * seconds after startup an unopened dev server was told its app would never connect.
+     */
+    let htmlRequested = false;
+    const isDocumentRequest = (req) => true === req.headers?.accept?.includes('text/html');
+    /**
+     * Warn when the HTML hook never ran. NOT scheduled from `transformIndexHtml` — a hook that never
+     * runs would never arm its own check, and it would be unreachable in exactly the case it exists
+     * for. It hangs off the first request instead: independent of the hook, but still evidence-based.
+     *
+     * `htmlRequested` is re-checked here rather than only at the arming site. The timer is one caller;
+     * this states the precondition where the claim is actually made, which is where somebody reading
+     * `warn(htmlHookNeverRanMessage())` needs to see it.
+     */
+    const checkHtmlHookRan = () => {
+        if (deps.desktop || !deps.inject || deps.htmlTransformed())
+            return;
+        // Nobody has opened the app. That says nothing about whether it can connect.
+        if (!htmlRequested)
+            return;
+        deps.warn(htmlHookNeverRanMessage());
+    };
+    /**
+     * Note a document request, and start the clock from THERE.
+     *
+     * The grace period is meant to cover "the browser asked, so the transform should have happened by
+     * now". Measured from server start it was covering "the server booted", which is a question about
+     * the developer's attention rather than about the app.
+     */
+    const noteHtmlRequest = () => {
+        if (htmlRequested)
+            return;
+        htmlRequested = true;
+        (deps.schedule ?? defaultSchedule)(checkHtmlHookRan, DEV_INJECTION_GRACE_MS);
+    };
+    /** Warn (never throw) in dev — a running dev server should report the doubt, not die of it. */
+    const checkInjected = () => {
+        if (!deps.desktop || !deps.inject || deps.injected())
+            return;
+        deps.warn(unconfirmedInjectionMessage());
+    };
+    /**
+     * In serve the HTML is sent BEFORE the browser requests the entry module, so asserting at html
+     * time would fire on every healthy start. Deferred here rather than at the call site, so that
+     * every "when may this speak" rule in the plugin sits in the one file that argues about them.
+     */
+    const armDesktopCheck = () => {
+        (deps.schedule ?? defaultSchedule)(checkInjected, DEV_INJECTION_GRACE_MS);
+    };
+    return { noteHtmlRequest, isDocumentRequest, checkHtmlHookRan, checkInjected, armDesktopCheck };
+}

package/dist/installed.d.ts CHANGED Viewed

@@ -56,7 +56,7 @@ export declare const OPTIMIZER_OPTIONS_KEY: {
     readonly ESBUILD: "esbuildOptions";
     readonly ROLLDOWN: "rolldownOptions";
 };
-export type OptimizerOptionsKey = (typeof OPTIMIZER_OPTIONS_KEY)[keyof typeof OPTIMIZER_OPTIONS_KEY];
+type OptimizerOptionsKey = (typeof OPTIMIZER_OPTIONS_KEY)[keyof typeof OPTIMIZER_OPTIONS_KEY];
 /**
  * Which key carries optimizer options on this Vite.
  *
@@ -84,3 +84,4 @@ export declare function optimizerOptionsKey(major: number | null): OptimizerOpti
  * app's own, it meant something, and passing it through unchanged is what produced the warning.
  */
 export declare function optimizerOptions(key: OptimizerOptionsKey, inherited: Record<string, unknown>, add: Record<string, string>): Record<string, unknown>;
+export {};

package/dist/plugin-name.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * The name Vite shows for this plugin, and the prefix on every message it prints.
+ *
+ * It lives in its own file so the message builders can use it without importing the plugin itself,
+ * which would be a circular import.
+ */
+export declare const RETICLE_VITE_PLUGIN_NAME = "reticle";

package/dist/plugin-name.js ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * The name Vite shows for this plugin, and the prefix on every message it prints.
+ *
+ * It lives in its own file so the message builders can use it without importing the plugin itself,
+ * which would be a circular import.
+ */
+export const RETICLE_VITE_PLUGIN_NAME = 'reticle';