@reticlehq/vite-plugin 3.2.0 → 3.4.0

package/dist/index.d.cts

@@ -72,15 +72,15 @@ export interface ReticleVitePluginOptions {
      * 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 injected into the HTML's entry module rather than as a virtual <script src>,
+     *    so a packaged renderer with no dev server still resolves it — but only for a build run in a
+     *    NON-production mode (`vite build --mode development`). A production-mode build is stubbed
+     *    exactly like a web one, so a release binary never carries the SDK. See
+     *    isReticleDisabledBuild.
      *  - `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.
+     * Off by default and never inferred.
      */
     desktop?: boolean;
     /**
@@ -95,6 +95,20 @@ export interface ReticleVitePluginOptions {
      * Also settable as `VITE_RETICLE_CAPTURE_BODIES=1`.
      */
     captureNetworkBodies?: boolean;
+    /**
+     * Per-body character cap for captured bodies. Default 8192; clamped to [256, 262144].
+     *
+     * Reachable here for the 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.
+     *
+     * Raise it to make a NEGATIVE `bodyContains` decidable -- a negation is checked over the whole
+     * payload, so on a list endpoint bigger than the cap it is permanently undecidable, and that is
+     * the class that proves "this dangerous field is absent from every row" (#799).
+     *
+     * Also settable as `VITE_RETICLE_BODY_MAX_CHARS=65536`, so one run can raise it without editing
+     * vite.config.
+     */
+    networkBodyMaxChars?: number;
     /**
      * Retain a FAILED request's response body even with `captureNetworkBodies` off. Default true.
      *
@@ -195,8 +209,6 @@ export interface ReticleVitePlugin {
             };
         };
     };
-    /** Absent in desktop mode, where the plugin must also run for `vite build`. */
-    apply?: 'serve';
     enforce: 'pre';
     transform: (code: string, id: string) => {
         code: string;
@@ -209,6 +221,8 @@ export interface ReticleVitePlugin {
     configResolved?: (config: {
         root?: string;
         command?: string;
+        /** 'production' unless `--mode` says otherwise. See isReticleDisabledBuild. */
+        mode?: string;
         base?: string;
         /** Vitest's block, read only to spot browser mode. See isVitestBrowserServer. */
         test?: unknown;
@@ -313,14 +327,12 @@ export declare function connectModuleSource(options: ReticleVitePluginOptions, d
  * 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.
+ * The web plugin also builds, replacing the browser SDK with an inert stub so a default
+ * production bundle ships no Reticle runtime code at all.
  *
- * `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.
+ * `desktop: true` keeps that guarantee for a production-mode build. It instruments `serve`, and a
+ * build only when it runs in another mode (`vite build --mode development`), which is how a packaged
+ * smoke renderer with no dev server still gets its connect(). See isReticleDisabledBuild.
  */
 /**
  * The daemon's journal directory, as a matcher every chokidar major honours.

package/dist/index.d.ts

@@ -72,15 +72,15 @@ export interface ReticleVitePluginOptions {
      * 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 injected into the HTML's entry module rather than as a virtual <script src>,
+     *    so a packaged renderer with no dev server still resolves it — but only for a build run in a
+     *    NON-production mode (`vite build --mode development`). A production-mode build is stubbed
+     *    exactly like a web one, so a release binary never carries the SDK. See
+     *    isReticleDisabledBuild.
      *  - `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.
+     * Off by default and never inferred.
      */
     desktop?: boolean;
     /**
@@ -95,6 +95,20 @@ export interface ReticleVitePluginOptions {
      * Also settable as `VITE_RETICLE_CAPTURE_BODIES=1`.
      */
     captureNetworkBodies?: boolean;
+    /**
+     * Per-body character cap for captured bodies. Default 8192; clamped to [256, 262144].
+     *
+     * Reachable here for the 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.
+     *
+     * Raise it to make a NEGATIVE `bodyContains` decidable -- a negation is checked over the whole
+     * payload, so on a list endpoint bigger than the cap it is permanently undecidable, and that is
+     * the class that proves "this dangerous field is absent from every row" (#799).
+     *
+     * Also settable as `VITE_RETICLE_BODY_MAX_CHARS=65536`, so one run can raise it without editing
+     * vite.config.
+     */
+    networkBodyMaxChars?: number;
     /**
      * Retain a FAILED request's response body even with `captureNetworkBodies` off. Default true.
      *
@@ -195,8 +209,6 @@ export interface ReticleVitePlugin {
             };
         };
     };
-    /** Absent in desktop mode, where the plugin must also run for `vite build`. */
-    apply?: 'serve';
     enforce: 'pre';
     transform: (code: string, id: string) => {
         code: string;
@@ -209,6 +221,8 @@ export interface ReticleVitePlugin {
     configResolved?: (config: {
         root?: string;
         command?: string;
+        /** 'production' unless `--mode` says otherwise. See isReticleDisabledBuild. */
+        mode?: string;
         base?: string;
         /** Vitest's block, read only to spot browser mode. See isVitestBrowserServer. */
         test?: unknown;
@@ -313,14 +327,12 @@ export declare function connectModuleSource(options: ReticleVitePluginOptions, d
  * 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.
+ * The web plugin also builds, replacing the browser SDK with an inert stub so a default
+ * production bundle ships no Reticle runtime code at all.
  *
- * `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.
+ * `desktop: true` keeps that guarantee for a production-mode build. It instruments `serve`, and a
+ * build only when it runs in another mode (`vite build --mode development`), which is how a packaged
+ * smoke renderer with no dev server still gets its connect(). See isReticleDisabledBuild.
  */
 /**
  * The daemon's journal directory, as a matcher every chokidar major honours.

package/dist/index.js

@@ -3,14 +3,15 @@ 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';
-import reticleSource from '@reticlehq/babel-plugin';
-import { RETICLE_DEFAULT_PORT, RETICLE_RENDER_PREHOOK, bridgeWsUrl, ReticleDir, ReticleEnv, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, } from '@reticlehq/core';
+import { RETICLE_RENDER_PREHOOK, ReticleDir, ReticleEnv, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, } from '@reticlehq/core';
 import { resolveProjectId } from './project-id.js';
-import { discoverDaemonPort } from './discover-port.js';
+import { resolveDaemonPort } from './discover-port.js';
 import { announceDevServer } from './announce.js';
-import { SVELTE_FILE, stampSvelte } from './svelte-source.js';
+import { stampSvelte } from './svelte-source.js';
+import { NODE_MODULES, ignoredFileNotice, optsOutOfStamping, shouldStamp, shouldStampSvelte, stamp, } from './stamping.js';
 import { resolvableChain, sdkPackageVersion, sdkBuildFingerprint, viteMajor, optimizerOptionsKey, optimizerOptions, } from './installed.js';
+import { RETICLE_DISABLED_STUB_CODE, RETICLE_DISABLED_STUB, isReticleDisabledBuild, } from './disabled-browser-stub.js';
+import { connectArgs } from './connect-args.js';
 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';
@@ -26,11 +27,6 @@ const RETICLE_SENSOR = '@reticlehq/browser';
  * file it lives in.
  */
 export const RETICLE_TOKEN_GLOBAL = '__RETICLE_TOKEN__';
-/** Files we stamp with source info — JSX/TSX only. */
-const JSX_FILE = /\.[jt]sx$/;
-/** Rollup virtual-module ids start with a NUL byte; never transform those. */
-const VIRTUAL_PREFIX = '\0';
-const NODE_MODULES = 'node_modules';
 /**
  * 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
@@ -132,40 +128,6 @@ function isHtmlEntry(id, specifier, root) {
     // buildEnd post-condition means a wrong match cannot pass unnoticed as "nothing happened".
     return candidate.endsWith(target.startsWith('/') ? target : `/${target}`);
 }
-/** A module id we may stamp at all: not virtual, not a dependency. Extension decides which stamper. */
-function stampableId(id) {
-    if (id.startsWith(VIRTUAL_PREFIX))
-        return null;
-    if (id.includes(NODE_MODULES))
-        return null;
-    // Strip any query suffix (?worker, ?raw,...) before matching the extension.
-    return id.split('?')[0] ?? id;
-}
-function shouldStamp(id) {
-    const clean = stampableId(id);
-    return clean !== null && JSX_FILE.test(clean);
-}
-/** A `.svelte` single-file component, which needs the Svelte stamper rather than Babel. */
-function shouldStampSvelte(id) {
-    const clean = stampableId(id);
-    return clean !== null && SVELTE_FILE.test(clean);
-}
-function stamp(code, id) {
-    const out = transformSync(code, {
-        filename: id,
-        plugins: [reticleSource],
-        parserOpts: { plugins: ['jsx', 'typescript'] },
-        sourceMaps: true,
-        configFile: false,
-        babelrc: false,
-    });
-    if (out?.code === undefined || null === out.code)
-        return null;
-    return {
-        code: out.code,
-        map: out.map === undefined || null === out.map ? null : JSON.stringify(out.map),
-    };
-}
 /**
  * Read the daemon's auto-provisioned pairing token (~/.reticle/pairing-token, or the
  * RETICLE_PAIRING_TOKEN_DIR override) so the served app can present it. Node-side only — a browser
@@ -196,60 +158,6 @@ function warnIfTokenMissing(token) {
     }
     return token;
 }
-/** Build the `reticle.connect` argument literal — only includes keys the user set. */
-function connectArgs(options) {
-    const args = {};
-    const port = options.port ?? RETICLE_DEFAULT_PORT;
-    if (port !== RETICLE_DEFAULT_PORT)
-        args['url'] = bridgeWsUrl(port);
-    if (options.session !== undefined)
-        args['session'] = options.session;
-    if (options.projectId !== undefined)
-        args['projectId'] = options.projectId;
-    if (options.token !== undefined)
-        args['token'] = options.token;
-    // Passed as connect ARGUMENTS, not as a `define`. A define substitutes a bare identifier in the
-    // source it transforms; the SDK reads these as `globalThis[NAME]`, a dynamic lookup no define can
-    // ever reach — so defining them looked right, shipped, and did nothing. Baking them into the
-    // generated connect call is a literal in generated source: no bundler subtleties, works the same
-    // in dev and in a desktop build.
-    if (options.root !== undefined && options.root.length > 0)
-        args['root'] = options.root;
-    if (options.sdkVersion !== undefined && options.sdkVersion.length > 0) {
-        args['sdkVersion'] = options.sdkVersion;
-    }
-    // A desktop renderer is a production build by construction; without this the SDK's prod backstop
-    // refuses to connect and the app is silently uninstrumented.
-    if (true === options.desktop)
-        args['allowInProduction'] = true;
-    // Env wins nothing — it only turns the flag ON, so a config that never set it can still be
-    // switched on for one debugging session without editing vite.config and restarting the mental
-    // model with it.
-    if (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;
-    }
-    // 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. */
 /**
  * The conventional app-side dev module: `registerStore` / `registerCapabilities` live here.
@@ -333,14 +241,12 @@ export function connectModuleSource(options, devModule = null) {
  * 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.
+ * The web plugin also builds, replacing the browser SDK with an inert stub so a default
+ * production bundle ships no Reticle runtime code at all.
  *
- * `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.
+ * `desktop: true` keeps that guarantee for a production-mode build. It instruments `serve`, and a
+ * build only when it runs in another mode (`vite build --mode development`), which is how a packaged
+ * smoke renderer with no dev server still gets its connect(). See isReticleDisabledBuild.
  */
 /**
  * The daemon's journal directory, as a matcher every chokidar major honours.
@@ -371,6 +277,10 @@ export function reticle(options = {}) {
     let root;
     /** 'serve' | 'build'. The dev check only applies to serve; buildEnd covers the other. */
     let command;
+    /** Vite's resolved mode. Decides whether a desktop build may be instrumented at all. */
+    let mode;
+    /** A build that must carry no Reticle runtime. See isReticleDisabledBuild. */
+    const disabledBuild = () => isReticleDisabledBuild(desktop, command, mode);
     /** 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. */
@@ -378,21 +288,38 @@ 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;
+    /** Files already announced as opted out of stamping: one line each, for the life of the server. */
+    const announcedIgnored = new Set();
     /**
      * 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.
+     * On the web this is the usual way the connect script gets in, but not the only one: see
+     * connectDelivered below, which the web warning reads together with this.
      */
     let htmlTransformed = false;
+    /**
+     * Whether the connect reached the page by a route OTHER than the HTML hook.
+     *
+     * A framework that renders its own HTML never calls `transformIndexHtml`, and still connects when
+     * its client entry imports the module `load` serves (React Router) or calls connect() itself with
+     * the token this plugin inlines (SvelteKit's client hook). Counting only the hook told those apps,
+     * ten seconds after every page load and while they WERE connected, that they would never connect.
+     */
+    let connectDelivered = false;
+    /** The last port warning printed, so a disagreement is said once and not on every request. */
+    let lastPortWarning;
     /**
      * 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
      * would bake in `undefined` and the app would fail auth on every connect.
      */
     const resolveLazy = () => {
-        const port = resolved.port ?? discoverDaemonPort(resolved.projectId);
+        // Wherever the daemon for this project actually is; the order is argued in discover-port.ts.
+        const { port, warning } = resolveDaemonPort(resolved.port, resolved.projectId, process.cwd());
+        if (warning !== undefined && warning !== lastPortWarning) {
+            lastPortWarning = warning;
+            warn(warning);
+        }
         const withPort = port !== undefined ? { ...resolved, port } : resolved;
         const token = withPort.token ?? readPairingToken();
         const withToken = token !== undefined ? { ...withPort, token } : withPort;
@@ -421,15 +348,12 @@ export function reticle(options = {}) {
         desktop,
         inject,
         injected: () => injected,
-        htmlTransformed: () => htmlTransformed,
+        connectDelivered: () => htmlTransformed || connectDelivered,
+        connectModule: () => connectModuleUrl(base),
         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.
-        // Desktop: a packaged renderer IS a production build with no dev server, so the plugin must also
-        // run for `vite build` or the shipped app has no connect() at all.
-        ...(true === options.desktop ? {} : { apply: 'serve' }),
         enforce: 'pre',
         /**
          * Declare the SDK itself and the optimizer cache fingerprint.
@@ -511,6 +435,13 @@ export function reticle(options = {}) {
             };
         },
         transform(code, id) {
+            if (disabledBuild())
+                return null;
+            // A hand-written connect in app code reads the token this plugin inlines; that is the
+            // connect reaching the page without the HTML hook. See connectDelivered.
+            if (!connectDelivered && code.includes(RETICLE_TOKEN_GLOBAL) && !id.includes(NODE_MODULES)) {
+                connectDelivered = true;
+            }
             // Desktop injection: prepend connect() to the HTML's own entry module. It is a REAL module, so
             // its bare `@reticlehq/react` import resolves through the normal pipeline in both dev and
             // build — which a virtual <script src> only ever did in dev.
@@ -522,6 +453,16 @@ export function reticle(options = {}) {
             }
             if (!sourceMapping)
                 return null;
+            // Decided HERE, ahead of both stampers, so the Svelte path honours the marker too and so the
+            // opt-out is announced once regardless of which stamper would have run. The Babel plugin reads
+            // the same marker on its own for the callers that reach it without Vite (#853).
+            if (optsOutOfStamping(code, id)) {
+                if (!announcedIgnored.has(id)) {
+                    announcedIgnored.add(id);
+                    warn(ignoredFileNotice(id));
+                }
+                return null;
+            }
             // `.svelte` runs on the RAW component source, which is only still markup because this plugin
             // declares `enforce: 'pre'` and therefore transforms before @sveltejs/vite-plugin-svelte. No
             // map: the insertions are within a line and never move one, and a wrong map is worse than none.
@@ -534,6 +475,9 @@ export function reticle(options = {}) {
             return stamp(code, id);
         },
         resolveId(id, importer) {
+            if (disabledBuild() && id === RETICLE_SENSOR) {
+                return RETICLE_DISABLED_STUB;
+            }
             // Desktop: remember the module the HTML points at, so `transform` can prepend connect() into
             // it. A packaged build has no dev server, so the serve-time trick below — a <script src> at a
             // virtual URL — would emit a tag pointing at a file that does not exist. That shipped an app
@@ -549,15 +493,20 @@ export function reticle(options = {}) {
             return inject && id === RETICLE_CONNECT_MODULE ? RETICLE_CONNECT_MODULE : null;
         },
         load(id) {
+            if (disabledBuild() && id === RETICLE_DISABLED_STUB) {
+                return RETICLE_DISABLED_STUB_CODE;
+            }
             if (!inject || id !== RETICLE_CONNECT_MODULE)
                 return null;
             const source = currentConnectSource();
             lastServedConnectSource = source;
+            connectDelivered = true;
             return source;
         },
         configResolved(config) {
             root = config.root;
             command = config.command;
+            mode = config.mode;
             base = config.base;
             vitestBrowser = isVitestBrowserServer(config);
         },
@@ -582,8 +531,6 @@ export function reticle(options = {}) {
          * 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
@@ -635,6 +582,12 @@ export function reticle(options = {}) {
             else {
                 announce();
             }
+            // Everything below serves or watches the injected connect, so `inject: false` stops HERE and
+            // not at the top. SvelteKit and TanStack Start are written `inject: false` because they connect
+            // themselves, and returning before the announcement made the dev server `init` started for
+            // them invisible to everything that asks which dev servers are running.
+            if (!inject)
+                return;
             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
@@ -664,7 +617,8 @@ export function reticle(options = {}) {
          * build that could not instrument must fail loudly instead of shipping a binary that lies.
          */
         buildEnd() {
-            if (!desktop || !inject || injected)
+            // A production build injects nothing on purpose; see isReticleDisabledBuild.
+            if (!desktop || !inject || injected || disabledBuild())
                 return;
             throw new Error(notInjectedMessage());
         },
@@ -672,6 +626,8 @@ export function reticle(options = {}) {
         checkHtmlHookForTest: watch.checkHtmlHookRan,
         injectionWatchForTest: watch,
         transformIndexHtml() {
+            if (disabledBuild())
+                return [];
             htmlTransformed = true;
             if (desktop && inject && 'serve' === command)
                 watch.armDesktopCheck();

package/dist/injection-postcondition.d.ts

@@ -42,8 +42,12 @@ export declare const unconfirmedInjectionMessage: () => string;
  * `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.
+ *
+ * The fix it names keeps `inject` ON. It used to say "pass `inject: false`", and on a React Router
+ * app, whose client entry imports the connect module this plugin serves, following that advice
+ * switched the module off and broke a working connect.
  */
-export declare const htmlHookNeverRanMessage: () => string;
+export declare const htmlHookNeverRanMessage: (connectModule: string) => string;
 /**
  * The state behind those three messages, and the rules for reaching each one.
  *
@@ -58,8 +62,13 @@ export interface InjectionWatchDeps {
     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;
+    /**
+     * Whether connect() reached the page by ANY route: the HTML hook, the served connect module, or a
+     * hand-written connect. Read late, for the same reason.
+     */
+    readonly connectDelivered: () => boolean;
+    /** The URL the connect module is served at (base-aware, so read late), for the web message. */
+    readonly connectModule: () => string;
     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;

package/dist/injection-postcondition.js

@@ -51,13 +51,18 @@ export const unconfirmedInjectionMessage = () => `[${RETICLE_VITE_PLUGIN_NAME}]
  * `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.
+ *
+ * The fix it names keeps `inject` ON. It used to say "pass `inject: false`", and on a React Router
+ * app, whose client entry imports the connect module this plugin serves, following that advice
+ * switched the module off and broke a working connect.
  */
-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.';
+export const htmlHookNeverRanMessage = (connectModule) => `[${RETICLE_VITE_PLUGIN_NAME}] this app will never connect: the dev server never asked this ` +
+    'plugin to transform any HTML and nothing loaded its connect module, so reticle.connect() never ' +
+    'reached 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: in dev, dynamically import '${connectModule}' from your client entry file — this plugin ` +
+    "serves that module, so leave `inject` on — or import '@reticlehq/browser' there " +
+    'and call reticle.connect({ token: __RETICLE_TOKEN__ }) yourself.';
 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.
@@ -85,12 +90,12 @@ export function createInjectionWatch(deps) {
      * `warn(htmlHookNeverRanMessage())` needs to see it.
      */
     const checkHtmlHookRan = () => {
-        if (deps.desktop || !deps.inject || deps.htmlTransformed())
+        if (deps.desktop || !deps.inject || deps.connectDelivered())
             return;
         // Nobody has opened the app. That says nothing about whether it can connect.
         if (!htmlRequested)
             return;
-        deps.warn(htmlHookNeverRanMessage());
+        deps.warn(htmlHookNeverRanMessage(deps.connectModule()));
     };
     /**
      * Note a document request, and start the clock from THERE.

package/dist/project-id.d.ts

@@ -26,6 +26,14 @@ type ReadFile = (path: string) => string;
  * through `init` — it is not a second opinion, and where the two disagree the config wins.
  */
 export declare function readConfiguredProjectId(startDir: string, readFile?: ReadFile): string | undefined;
+/**
+ * Read the daemon port `reticle init --port` recorded in the nearest `.reticle.json`, or undefined.
+ *
+ * The CLI already obeys this field, so a plugin that ignored it put the two halves on different
+ * daemons: the page connected to the default port — on a machine running two projects, the other
+ * project's daemon — and the bridge refused it.
+ */
+export declare function readConfiguredPort(startDir: string, readFile?: ReadFile): number | undefined;
 /**
  * Resolve the projectId for a plugin instance, most-local statement of intent first: an explicit
  * option, then the id `reticle init` recorded in `.reticle.json`, then derivation.

package/dist/project-id.js

@@ -45,18 +45,24 @@ const MAX_CONFIG_SEARCH_DEPTH = 6;
  * costs a less specific name rather than the wrong app's identity. Left as it was.
  */
 const MAX_PACKAGE_SEARCH_DEPTH = 50;
+const nonEmptyString = (value) => 'string' === typeof value && value.length > 0 ? value : undefined;
+const MAX_TCP_PORT = 65_535;
+const tcpPort = (value) => Number.isInteger(value) && value > 0 && value <= MAX_TCP_PORT
+    ? value
+    : undefined;
 /**
- * Walk up from `startDir` looking for `basename`, and return the first non-empty string `field`
- * yields. Unreadable and unparseable files are skipped rather than fatal: a dev server must start.
+ * Walk up from `startDir` looking for `basename`, and return the first value of `field` that
+ * `accept` takes. Unreadable and unparseable files are skipped rather than fatal: a dev server must
+ * start.
  */
-function readNearestField(startDir, basename, field, readFile, maxDepth) {
+function readNearestField(startDir, basename, field, readFile, maxDepth, accept) {
     let dir = startDir;
     for (let depth = 0; depth <= maxDepth; depth++) {
         try {
             const parsed = JSON.parse(readFile(join(dir, basename)));
             if ('object' === typeof parsed && parsed !== null) {
-                const value = parsed[field];
-                if ('string' === typeof value && value.length > 0)
+                const value = accept(parsed[field]);
+                if (value !== undefined)
                     return value;
             }
         }
@@ -72,7 +78,7 @@ function readNearestField(startDir, basename, field, readFile, maxDepth) {
 }
 /** Read the `name` from the nearest package.json at or above `startDir`, or undefined if none. */
 function readNearestPackageName(startDir, readFile = readFileOrThrow) {
-    return readNearestField(startDir, 'package.json', 'name', readFile, MAX_PACKAGE_SEARCH_DEPTH);
+    return readNearestField(startDir, 'package.json', 'name', readFile, MAX_PACKAGE_SEARCH_DEPTH, nonEmptyString);
 }
 /**
  * Read the `projectId` `reticle init` recorded in the nearest `.reticle.json`, or undefined.
@@ -81,7 +87,17 @@ function readNearestPackageName(startDir, readFile = readFileOrThrow) {
  * through `init` — it is not a second opinion, and where the two disagree the config wins.
  */
 export function readConfiguredProjectId(startDir, readFile = readFileOrThrow) {
-    return readNearestField(startDir, RETICLE_CONFIG_BASENAME, 'projectId', readFile, MAX_CONFIG_SEARCH_DEPTH);
+    return readNearestField(startDir, RETICLE_CONFIG_BASENAME, 'projectId', readFile, MAX_CONFIG_SEARCH_DEPTH, nonEmptyString);
+}
+/**
+ * Read the daemon port `reticle init --port` recorded in the nearest `.reticle.json`, or undefined.
+ *
+ * The CLI already obeys this field, so a plugin that ignored it put the two halves on different
+ * daemons: the page connected to the default port — on a machine running two projects, the other
+ * project's daemon — and the bridge refused it.
+ */
+export function readConfiguredPort(startDir, readFile = readFileOrThrow) {
+    return readNearestField(startDir, RETICLE_CONFIG_BASENAME, 'port', readFile, MAX_CONFIG_SEARCH_DEPTH, tcpPort);
 }
 /**
  * Resolve the projectId for a plugin instance, most-local statement of intent first: an explicit