@reticlehq/vite-plugin 3.3.0 → 3.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 One-line Vite integration for [Reticle](https://github.com/reticlehq/reticle). The plugin does the whole dev-time wiring for you:
 
-- **Source mapping**: stamps `data-reticle-source="file:line:col"` on JSX host elements (via [`@reticlehq/babel-plugin`](https://www.npmjs.com/package/@reticlehq/babel-plugin)) so `reticle_inspect` can report the component's source file. Needed on React 19.
+- **Source mapping**: stamps `data-reticle-source="file:line:col"` on JSX host elements (via [`@reticlehq/babel-plugin`](https://www.npmjs.com/package/@reticlehq/babel-plugin)) so `reticle_look { action: "element" }` can report the component's source file. Needed on React 19.
 - **Auto-connect**: injects a dev-only `install(); reticle.connect()` into your entry module, so you never touch the entry file yourself.
 - **Svelte source mapping**: the same stamp on Svelte markup, applied before `@sveltejs/vite-plugin-svelte` compiles it.
 - **Dependency pre-bundling**: declares the SDK's CJS runtime deps in `optimizeDeps` so the SDK loads on linked and monorepo setups.
@@ -45,9 +45,9 @@ reticle({
   sdkVersion, // installed SDK version, so a skewed pair can name itself
   sourceMapping, // default true; stamp data-reticle-source (harmless on React <=18)
   inject, // default true; auto-inject reticle.connect()
-  captureNetworkBodies, // default false; record request/response bodies on reticle_network
+  captureNetworkBodies, // default false; record request/response bodies on reticle_observe { action: "network" }
   allowNonLocalhost, // default false; allow a page/bridge that is not on localhost (needs a token)
-  desktop, // default false; also apply to `vite build`, for an Electron/Tauri renderer
+  desktop, // default false; for an Electron/Tauri renderer (see below)
   onWarn, // where a diagnostic goes; defaults to the console
 });
 ```
@@ -56,7 +56,7 @@ reticle({
 
 `allowNonLocalhost` is for a dev server that cannot be served on localhost — a host-based multi-tenant frontend, or an app with cookie-scoped auth on a custom dev hostname. It is **not sufficient on its own**: the SDK also requires a pairing token outside localhost, and refuses with "a pairing token is required outside localhost" when it is missing. The plugin supplies one automatically from the daemon's `~/.reticle/pairing-token`, so a running daemon is normally all it takes — pass `token` yourself only when that file is unreachable. A bridge that is itself non-local must also use `wss://`. Settable as `VITE_RETICLE_ALLOW_NON_LOCALHOST=1` for a single session.
 
-`desktop: true` makes the plugin apply to `vite build` as well and calls `connect()` with `allowInProduction`, because a packaged desktop renderer is a production build with no dev server. That means an instrumented production bundle, which a web app must never ship. Keep it behind your own dev-only build target.
+`desktop: true` injects `connect()` into the renderer's entry module and calls it with `allowInProduction`, because a desktop renderer reports `NODE_ENV=production`. It instruments the dev server, and a `vite build` only when that build runs in a non-production mode (`vite build --mode development`), for a packaged renderer you drive with no dev server. A production-mode build, which is what `vite build` and `electron-vite build` do by default, ships no Reticle code at all, exactly like a web build.
 
 ### Opting one file out of source stamping
 

package/dist/disabled-browser-stub.d.ts

@@ -1,3 +1,15 @@
 export declare const RETICLE_DISABLED_STUB = "\0reticle-disabled-stub";
-export declare const isReticleDisabledWebBuild: (desktop: boolean, command: string | undefined) => boolean;
+/**
+ * Whether this is a build that must ship no Reticle runtime at all: the SDK swapped for the stub
+ * below, nothing injected.
+ *
+ * Every production build, desktop included. `desktop: true` used to exempt the whole build, and it
+ * is what `reticle init` writes for electron-vite, so a RELEASE renderer carried the full SDK and
+ * dialled `ws://localhost:<port>/reticle`: `electron-vite preview` of a production build connected
+ * to the daemon. A release binary gets the same guarantee a web bundle does. A packaged desktop
+ * build that SHOULD be instrumented (a smoke app driven headless) says so the way Vite already
+ * provides, by building in another mode: `vite build --mode development`. An unknown mode counts as
+ * production, because the cost of guessing wrong the other way is an instrumented release.
+ */
+export declare const isReticleDisabledBuild: (desktop: boolean, command: string | undefined, mode: string | undefined) => boolean;
 export declare const RETICLE_DISABLED_STUB_CODE = "\nexport class Reticle {\n  connect() {}\n  signal() {}\n  state() {}\n  renderCommit() {}\n  describe() {}\n  endSession() {}\n  observeHotUpdates() {}\n  disconnect() {}\n\n  get connected() {\n    return false;\n  }\n}\n\nexport const reticle = new Reticle();\n\nexport const SESSION_AUTO = 'auto';\n\nexport function setIgnoreSelectors() {}\n\nexport function registerAdapter() {}\nexport function identifyComponent() {\n  return null;\n}\nexport function readComponentState() {\n  return undefined;\n}\nexport function elementHasHoverHandlers() {\n  return false;\n}\nexport function adapterNames() {\n  return [];\n}\n\nexport function registerStore() {}\nexport function unregisterStore() {}\nexport function storeNames() {\n  return [];\n}\nexport function readStores() {\n  return {};\n}\nexport function readStoresWithTruncation() {\n  return { stores: {} };\n}\nexport function sourceOwner() {\n  return undefined;\n}\nexport function markAdapterSource() {}\n\nexport function tanstackQueryStore() {\n  return undefined;\n}\nexport function jotaiStore() {\n  return undefined;\n}\nexport function xstateStore() {\n  return undefined;\n}\nexport function valtioStore() {\n  return undefined;\n}\nexport function mobxStore() {\n  return undefined;\n}\nexport function recoilStore() {\n  return undefined;\n}\nexport function svelteStore() {\n  return undefined;\n}\nexport function piniaStore() {\n  return undefined;\n}\nexport function pushStore() {\n  return undefined;\n}\n\nexport function registerCapabilities() {}\nexport function getCapabilities() {\n  return {};\n}\nexport function hasCapabilities() {\n  return false;\n}\nexport function setCapabilitiesListener() {}\n\nexport function createReticleEmitter() {\n  return {\n    signal() {},\n    state() {},\n  };\n}\n\nexport function commitAndSignal() {}\nexport function registerReticleDomain() {}\n\nexport function buildSnapshot() {\n  return {};\n}\n\nexport function inspectChart() {\n  return {};\n}\nexport function canvasChartData() {\n  return {};\n}\n\nexport function matchQuery() {\n  return false;\n}\nexport function runQuery() {\n  return undefined;\n}\n\nexport function executeAction() {\n  return undefined;\n}\nexport function executeSequence() {\n  return undefined;\n}\n\nexport function describe() {\n  return undefined;\n}\nexport function getRole() {\n  return undefined;\n}\nexport function getAccessibleName() {\n  return undefined;\n}\nexport function getStates() {\n  return {};\n}\nexport function isVisible() {\n  return false;\n}\n\nexport class RefRegistry {\n  get size() {\n    return 0;\n  }\n\n  markEdited() {}\n\n  mintedBeforeLastEdit() {\n    return false;\n  }\n\n  refFor() {\n    return undefined;\n  }\n\n  resolve() {\n    return null;\n  }\n}\n\nexport const refs = new RefRegistry();\n\nexport class Annotator {\n  constructor() {}\n\n  get active() {\n    return false;\n  }\n\n  get markCount() {\n    return 0;\n  }\n\n  mount() {}\n  unmount() {}\n}\n\nexport function installAnnotator() {}\n\nexport function resolveMarkAnchor() {\n  return undefined;\n}\n";

package/dist/disabled-browser-stub.js

@@ -1,5 +1,20 @@
 export const RETICLE_DISABLED_STUB = '\0reticle-disabled-stub';
-export const isReticleDisabledWebBuild = (desktop, command) => !desktop && 'build' === command;
+const BUILD_COMMAND = 'build';
+/** The mode `vite build` and `electron-vite build` use unless the command line says otherwise. */
+const PRODUCTION_MODE = 'production';
+/**
+ * Whether this is a build that must ship no Reticle runtime at all: the SDK swapped for the stub
+ * below, nothing injected.
+ *
+ * Every production build, desktop included. `desktop: true` used to exempt the whole build, and it
+ * is what `reticle init` writes for electron-vite, so a RELEASE renderer carried the full SDK and
+ * dialled `ws://localhost:<port>/reticle`: `electron-vite preview` of a production build connected
+ * to the daemon. A release binary gets the same guarantee a web bundle does. A packaged desktop
+ * build that SHOULD be instrumented (a smoke app driven headless) says so the way Vite already
+ * provides, by building in another mode: `vite build --mode development`. An unknown mode counts as
+ * production, because the cost of guessing wrong the other way is an instrumented release.
+ */
+export const isReticleDisabledBuild = (desktop, command, mode) => BUILD_COMMAND === command && (!desktop || mode === undefined || PRODUCTION_MODE === mode);
 export const RETICLE_DISABLED_STUB_CODE = `
 export class Reticle {
   connect() {}

package/dist/discover-port.d.ts

@@ -3,4 +3,35 @@
  * to the default port — never auto-connects to a mismatched daemon). `home` and `alive` are injectable
  * so the selection is unit-tested without a real ~/.reticle or real processes.
  */
-export declare function discoverDaemonPort(projectId: string | undefined, home?: string, alive?: (pid: number) => boolean): number | undefined;
+export declare function discoverDaemonPort(projectId: string | undefined, home?: string, alive?: (pid: number) => boolean, 
+/** `port` in `.reticle.json`: wins whenever a live daemon is registered on it — see pickDaemonPort. */
+configured?: number): number | undefined;
+/** The three places a daemon port can come from, as the plugin sees them at connect time. */
+export interface DaemonPortSources {
+    /** A live daemon registered in ~/.reticle for THIS project. */
+    readonly discovered: number | undefined;
+    /** `port` in the nearest `.reticle.json`: the value the daemon and the CLI follow. */
+    readonly configured: number | undefined;
+    /** The literal `reticle({ port })`, usually written once by `reticle init`. */
+    readonly explicit: number | undefined;
+}
+export interface DaemonPortChoice {
+    /** Where to dial, or undefined for the default port. */
+    readonly port: number | undefined;
+    /** Set only when the option and `.reticle.json` disagree: one line naming both and the winner. */
+    readonly warning: string | undefined;
+}
+/**
+ * The one rule for which port the page dials: wherever the daemon for this project actually is.
+ *
+ * A live registered daemon first, because it is a fact rather than a statement of intent — and when
+ * one is live on the configured port, that one (see pickDaemonPort: a moved port left the old daemon
+ * alive, and discovery used to pick it). Then
+ * `.reticle.json`, because that is what the daemon and the CLI read. The option used to win, and a
+ * user who edited the file moved the daemon while the page kept dialling the literal `init` had
+ * written into vite.config: "never dialled the bridge", with nothing saying why. The option counts
+ * only when nothing else says anything, and undefined leaves the default to the connect.
+ */
+export declare function chooseDaemonPort(sources: DaemonPortSources): DaemonPortChoice;
+/** {@link chooseDaemonPort} over the real registry and the real `.reticle.json` above `cwd`. */
+export declare function resolveDaemonPort(explicit: number | undefined, projectId: string | undefined, cwd: string, env?: NodeJS.ProcessEnv): DaemonPortChoice;

package/dist/discover-port.js

@@ -1,13 +1,17 @@
 /**
- * Build-time daemon discovery: when the app doesn't pin a port, find the daemon serving THIS project
- * by reading the registry entries the daemon drops in ~/.reticle (daemon-<port>.json). Node-only and
+ * Build-time daemon discovery, and the ONE place the plugin decides which port the page dials. Finds
+ * the daemon serving THIS project by reading the registry entries the daemon drops in ~/.reticle
+ * (daemon-<port>.json). Node-only and
  * runs at dev-server request time (the daemon is up by then). The tricky selection rule — match by
  * projectId, drop dead daemons — is the pure `pickDaemonPort` in core; this file is just the fs plumbing.
  */
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, } from '@reticlehq/core';
+import { daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, ReticleEnv, } from '@reticlehq/core';
 import { stateHome } from './state-home.js';
+import { readConfiguredPort } from './project-id.js';
+import { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
+const MAX_TCP_PORT = 65_535;
 /** process.kill(pid, 0) throws iff the process is gone — the same liveness probe the daemon uses. */
 function isAlive(pid) {
     try {
@@ -23,7 +27,9 @@ function isAlive(pid) {
  * to the default port — never auto-connects to a mismatched daemon). `home` and `alive` are injectable
  * so the selection is unit-tested without a real ~/.reticle or real processes.
  */
-export function discoverDaemonPort(projectId, home = stateHome(), alive = isAlive) {
+export function discoverDaemonPort(projectId, home = stateHome(), alive = isAlive, 
+/** `port` in `.reticle.json`: wins whenever a live daemon is registered on it — see pickDaemonPort. */
+configured) {
     const entries = [];
     let files;
     try {
@@ -44,5 +50,47 @@ export function discoverDaemonPort(projectId, home = stateHome(), alive = isAliv
             // corrupt/unreadable entry — skip
         }
     }
-    return pickDaemonPort(entries, projectId, alive) ?? undefined;
+    return pickDaemonPort(entries, projectId, alive, configured) ?? undefined;
+}
+const portConflictWarning = (explicit, configured, used) => `[${RETICLE_VITE_PLUGIN_NAME}] reticle({ port: ${String(explicit)} }) and "port": ` +
+    `${String(configured)} in .reticle.json disagree; connecting to ${String(used)}. The daemon and ` +
+    'the CLI follow .reticle.json, so drop the port option from reticle() or make the two match.';
+/**
+ * The one rule for which port the page dials: wherever the daemon for this project actually is.
+ *
+ * A live registered daemon first, because it is a fact rather than a statement of intent — and when
+ * one is live on the configured port, that one (see pickDaemonPort: a moved port left the old daemon
+ * alive, and discovery used to pick it). Then
+ * `.reticle.json`, because that is what the daemon and the CLI read. The option used to win, and a
+ * user who edited the file moved the daemon while the page kept dialling the literal `init` had
+ * written into vite.config: "never dialled the bridge", with nothing saying why. The option counts
+ * only when nothing else says anything, and undefined leaves the default to the connect.
+ */
+export function chooseDaemonPort(sources) {
+    const { discovered, configured, explicit } = sources;
+    const port = discovered ?? configured ?? explicit;
+    if (explicit === undefined || configured === undefined || port === undefined) {
+        return { port, warning: undefined };
+    }
+    return {
+        port,
+        warning: explicit === configured ? undefined : portConflictWarning(explicit, configured, port),
+    };
+}
+/** {@link chooseDaemonPort} over the real registry and the real `.reticle.json` above `cwd`. */
+export function resolveDaemonPort(explicit, projectId, cwd, env = process.env) {
+    // The CLI treats RETICLE_PORT as an override across projects. A page must follow the same
+    // daemon even when an older instance is still registered or init wrote a different port.
+    const raw = env[ReticleEnv.PORT];
+    if (raw !== undefined && /^\d+$/.test(raw)) {
+        const port = Number(raw);
+        if (0 < port && port <= MAX_TCP_PORT)
+            return { port, warning: undefined };
+    }
+    const configured = readConfiguredPort(cwd);
+    return chooseDaemonPort({
+        discovered: discoverDaemonPort(projectId, stateHome(env), isAlive, configured),
+        configured,
+        explicit,
+    });
 }

package/dist/index.cjs

@@ -4359,7 +4359,14 @@ var ReticleEnv = {
   API_KEY: "RETICLE_API_KEY",
   /** The name this key had until 2026-09. Still honoured; see `apiKeyFrom()`. */
   CLOUD_KEY: "RETICLE_CLOUD_KEY",
-  CLOUD_URL: "RETICLE_CLOUD_URL"
+  /** The platform host. Read through `cloudUrlFrom()`, which also accepts `URL`. */
+  CLOUD_URL: "RETICLE_CLOUD_URL",
+  /** The short name for `CLOUD_URL`, which people type first. `CLOUD_URL` wins when both are set. */
+  URL: "RETICLE_URL"
+};
+var SYNC_BATCH_LIMITS = {
+  MAX_RUNS: 50,
+  MAX_BYTES: 4 * 1024 * 1024
 };
 var TRANSPORT_LIMITS = {
   MAX_MESSAGE_BYTES: 1024 * 1024,
@@ -4489,6 +4496,8 @@ var ReticleDir = {
   AMBIENT_FILE: "ambient.json",
   /** per-flow flake ledger — replay outcomes that decide intermittent-failure quarantine. */
   FLAKE_FILE: "flake.json",
+  /** The app-wide coverage ledger — see server features/exhaust/ledger.ts. */
+  COVERAGE_FILE: "coverage.json",
   /**
    * the project's cloud binding — .reticle/cloud.json, written by `reticle link`. Git-checked and
    * non-secret: the project id, the API origin, and where its dashboard lives. The KEY lives in
@@ -4595,7 +4604,10 @@ var DaemonRegistryEntrySchema = external_exports.object({
   projectId: external_exports.string().optional(),
   startedAt: external_exports.number()
 });
-function pickDaemonPort(entries, projectId, isAlive2) {
+function pickDaemonPort(entries, projectId, isAlive2, configuredPort) {
+  if (void 0 !== configuredPort && entries.some((e) => e.port === configuredPort && isAlive2(e.pid) && (e.projectId === void 0 || projectId === void 0 || e.projectId === projectId))) {
+    return configuredPort;
+  }
   if (projectId === void 0 || 0 === projectId.length)
     return null;
   const matches = entries.filter((e) => e.projectId === projectId && isAlive2(e.pid)).map((e) => e.port).sort((a, b) => a - b);
@@ -4645,14 +4657,17 @@ function deriveProjectId(pkgName, rootPath) {
 var readFileOrThrow = (path) => (0, import_node_fs2.readFileSync)(path, "utf8");
 var MAX_CONFIG_SEARCH_DEPTH = 6;
 var MAX_PACKAGE_SEARCH_DEPTH = 50;
-function readNearestField(startDir, basename, field, readFile, maxDepth) {
+var nonEmptyString = (value) => "string" === typeof value && value.length > 0 ? value : void 0;
+var MAX_TCP_PORT = 65535;
+var tcpPort = (value) => Number.isInteger(value) && value > 0 && value <= MAX_TCP_PORT ? value : void 0;
+function readNearestField(startDir, basename, field, readFile, maxDepth, accept) {
   let dir = startDir;
   for (let depth = 0; depth <= maxDepth; depth++) {
     try {
       const parsed = JSON.parse(readFile((0, import_node_path2.join)(dir, basename)));
       if ("object" === typeof parsed && parsed !== null) {
-        const value = parsed[field];
-        if ("string" === typeof value && value.length > 0) return value;
+        const value = accept(parsed[field]);
+        if (value !== void 0) return value;
       }
     } catch {
     }
@@ -4663,7 +4678,14 @@ function readNearestField(startDir, basename, field, readFile, maxDepth) {
   return void 0;
 }
 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
+  );
 }
 function readConfiguredProjectId(startDir, readFile = readFileOrThrow) {
   return readNearestField(
@@ -4671,7 +4693,18 @@ function readConfiguredProjectId(startDir, readFile = readFileOrThrow) {
     RETICLE_CONFIG_BASENAME,
     "projectId",
     readFile,
-    MAX_CONFIG_SEARCH_DEPTH
+    MAX_CONFIG_SEARCH_DEPTH,
+    nonEmptyString
+  );
+}
+function readConfiguredPort(startDir, readFile = readFileOrThrow) {
+  return readNearestField(
+    startDir,
+    RETICLE_CONFIG_BASENAME,
+    "port",
+    readFile,
+    MAX_CONFIG_SEARCH_DEPTH,
+    tcpPort
   );
 }
 function resolveProjectId(explicit, cwd, readPkgName = readNearestPackageName, readConfiguredId = readConfiguredProjectId) {
@@ -4693,7 +4726,11 @@ function stateHome(env = process.env) {
   return override !== void 0 && override.length > 0 ? override : (0, import_node_path3.join)((0, import_node_os.homedir)(), ReticleDir.ROOT);
 }
 
+// src/plugin-name.ts
+var RETICLE_VITE_PLUGIN_NAME = "reticle";
+
 // src/discover-port.ts
+var MAX_TCP_PORT2 = 65535;
 function isAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -4702,7 +4739,7 @@ function isAlive(pid) {
     return false;
   }
 }
-function discoverDaemonPort(projectId, home = stateHome(), alive = isAlive) {
+function discoverDaemonPort(projectId, home = stateHome(), alive = isAlive, configured) {
   const entries = [];
   let files;
   try {
@@ -4720,7 +4757,32 @@ function discoverDaemonPort(projectId, home = stateHome(), alive = isAlive) {
     } catch {
     }
   }
-  return pickDaemonPort(entries, projectId, alive) ?? void 0;
+  return pickDaemonPort(entries, projectId, alive, configured) ?? void 0;
+}
+var portConflictWarning = (explicit, configured, used) => `[${RETICLE_VITE_PLUGIN_NAME}] reticle({ port: ${String(explicit)} }) and "port": ${String(configured)} in .reticle.json disagree; connecting to ${String(used)}. The daemon and the CLI follow .reticle.json, so drop the port option from reticle() or make the two match.`;
+function chooseDaemonPort(sources) {
+  const { discovered, configured, explicit } = sources;
+  const port = discovered ?? configured ?? explicit;
+  if (explicit === void 0 || configured === void 0 || port === void 0) {
+    return { port, warning: void 0 };
+  }
+  return {
+    port,
+    warning: explicit === configured ? void 0 : portConflictWarning(explicit, configured, port)
+  };
+}
+function resolveDaemonPort(explicit, projectId, cwd, env = process.env) {
+  const raw = env[ReticleEnv.PORT];
+  if (raw !== void 0 && /^\d+$/.test(raw)) {
+    const port = Number(raw);
+    if (0 < port && port <= MAX_TCP_PORT2) return { port, warning: void 0 };
+  }
+  const configured = readConfiguredPort(cwd);
+  return chooseDaemonPort({
+    discovered: discoverDaemonPort(projectId, stateHome(env), isAlive, configured),
+    configured,
+    explicit
+  });
 }
 
 // src/announce.ts
@@ -4980,7 +5042,9 @@ function optimizerOptions(key, inherited, add) {
 
 // src/disabled-browser-stub.ts
 var RETICLE_DISABLED_STUB = "\0reticle-disabled-stub";
-var isReticleDisabledWebBuild = (desktop, command) => !desktop && "build" === command;
+var BUILD_COMMAND = "build";
+var PRODUCTION_MODE = "production";
+var isReticleDisabledBuild = (desktop, command, mode) => BUILD_COMMAND === command && (!desktop || mode === void 0 || PRODUCTION_MODE === mode);
 var RETICLE_DISABLED_STUB_CODE = `
 export class Reticle {
   connect() {}
@@ -5199,14 +5263,11 @@ function connectArgs(options) {
   return Object.keys(args).length > 0 ? JSON.stringify(args) : "";
 }
 
-// src/plugin-name.ts
-var RETICLE_VITE_PLUGIN_NAME = "reticle";
-
 // src/injection-postcondition.ts
 var DEV_INJECTION_GRACE_MS = 1e4;
 var 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.`;
 var 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="...">.`;
-var 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 \u2014 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.`;
+var 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 \u2014 SvelteKit, Nuxt, Astro, React Router (framework mode) and TanStack Start all do. Fix: in dev, dynamically import '${connectModule}' from your client entry file \u2014 this plugin serves that module, so leave \`inject\` on \u2014 or import '@reticlehq/browser' there and call reticle.connect({ token: __RETICLE_TOKEN__ }) yourself.`;
 var defaultSchedule = (run, ms) => {
   const timer = setTimeout(run, ms);
   timer.unref?.();
@@ -5215,9 +5276,9 @@ function createInjectionWatch(deps) {
   let htmlRequested = false;
   const isDocumentRequest = (req) => true === req.headers?.accept?.includes("text/html");
   const checkHtmlHookRan = () => {
-    if (deps.desktop || !deps.inject || deps.htmlTransformed()) return;
+    if (deps.desktop || !deps.inject || deps.connectDelivered()) return;
     if (!htmlRequested) return;
-    deps.warn(htmlHookNeverRanMessage());
+    deps.warn(htmlHookNeverRanMessage(deps.connectModule()));
   };
   const noteHtmlRequest = () => {
     if (htmlRequested) return;
@@ -5363,14 +5424,22 @@ function reticle(options = {}) {
   let htmlEntrySpecifier;
   let root;
   let command;
+  let mode;
+  const disabledBuild = () => isReticleDisabledBuild(desktop, command, mode);
   let base;
   let vitestBrowser = false;
   const warn = options.onWarn ?? ((message) => globalThis.console.warn(message));
   let injected = false;
   const announcedIgnored = /* @__PURE__ */ new Set();
   let htmlTransformed = false;
+  let connectDelivered = false;
+  let lastPortWarning;
   const resolveLazy = () => {
-    const port = resolved.port ?? discoverDaemonPort(resolved.projectId);
+    const { port, warning } = resolveDaemonPort(resolved.port, resolved.projectId, process.cwd());
+    if (warning !== void 0 && warning !== lastPortWarning) {
+      lastPortWarning = warning;
+      warn(warning);
+    }
     const withPort = port !== void 0 ? { ...resolved, port } : resolved;
     const token = withPort.token ?? readPairingToken();
     const withToken = token !== void 0 ? { ...withPort, token } : withPort;
@@ -5385,7 +5454,8 @@ function reticle(options = {}) {
     desktop,
     inject,
     injected: () => injected,
-    htmlTransformed: () => htmlTransformed,
+    connectDelivered: () => htmlTransformed || connectDelivered,
+    connectModule: () => connectModuleUrl(base),
     warn
   });
   return {
@@ -5473,7 +5543,10 @@ function reticle(options = {}) {
       };
     },
     transform(code, id) {
-      if (isReticleDisabledWebBuild(desktop, command)) return null;
+      if (disabledBuild()) return null;
+      if (!connectDelivered && code.includes(RETICLE_TOKEN_GLOBAL) && !id.includes(NODE_MODULES)) {
+        connectDelivered = true;
+      }
       if (desktop && inject && isHtmlEntry(id, htmlEntrySpecifier, root)) {
         injected = true;
         const withConnect = `${connectModuleSource(resolveLazy())}
@@ -5497,7 +5570,7 @@ ${code}`;
       return stamp(code, id);
     },
     resolveId(id, importer) {
-      if (isReticleDisabledWebBuild(desktop, command) && id === RETICLE_SENSOR) {
+      if (disabledBuild() && id === RETICLE_SENSOR) {
         return RETICLE_DISABLED_STUB;
       }
       if (desktop && inject && importer !== void 0 && importer.includes(".html")) {
@@ -5506,17 +5579,19 @@ ${code}`;
       return inject && id === RETICLE_CONNECT_MODULE ? RETICLE_CONNECT_MODULE : null;
     },
     load(id) {
-      if (isReticleDisabledWebBuild(desktop, command) && id === RETICLE_DISABLED_STUB) {
+      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);
     },
@@ -5541,7 +5616,6 @@ ${code}`;
      * appearing IS a change), and makes the module inert once it has settled.
      */
     configureServer(server) {
-      if (!inject) return;
       const announce = () => {
         const address = server.httpServer?.address();
         const port = "object" === typeof address && null !== address && void 0 !== address ? address.port : void 0;
@@ -5566,6 +5640,7 @@ ${code}`;
       } else {
         announce();
       }
+      if (!inject) return;
       server.middlewares.use((req, _res, next) => {
         if (!desktop && watch.isDocumentRequest(req)) watch.noteHtmlRequest();
         const requestPath = (req.url ?? "").split("?")[0];
@@ -5586,14 +5661,14 @@ ${code}`;
      * build that could not instrument must fail loudly instead of shipping a binary that lies.
      */
     buildEnd() {
-      if (!desktop || !inject || injected) return;
+      if (!desktop || !inject || injected || disabledBuild()) return;
       throw new Error(notInjectedMessage());
     },
     checkInjectedForTest: watch.checkInjected,
     checkHtmlHookForTest: watch.checkHtmlHookRan,
     injectionWatchForTest: watch,
     transformIndexHtml() {
-      if (isReticleDisabledWebBuild(desktop, command)) return [];
+      if (disabledBuild()) return [];
       htmlTransformed = true;
       if (desktop && inject && "serve" === command) watch.armDesktopCheck();
       if (!inject || desktop) return [];

package/dist/index.d.cts

@@ -72,14 +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:
      *
-     *  - A packaged desktop renderer IS a production build with no dev server, so it needs the real
-     *    `connect()` wiring during `vite build` — the web default's stub-swap must not apply to it.
+     *  - 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;
     /**
@@ -220,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;
@@ -327,11 +330,9 @@ export declare function connectModuleSource(options: ReticleVitePluginOptions, d
  * 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 the web default's
- * stub-replacement 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,14 +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:
      *
-     *  - A packaged desktop renderer IS a production build with no dev server, so it needs the real
-     *    `connect()` wiring during `vite build` — the web default's stub-swap must not apply to it.
+     *  - 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;
     /**
@@ -220,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;
@@ -327,11 +330,9 @@ export declare function connectModuleSource(options: ReticleVitePluginOptions, d
  * 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 the web default's
- * stub-replacement 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

@@ -5,12 +5,12 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 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 { stampSvelte } from './svelte-source.js';
-import { ignoredFileNotice, optsOutOfStamping, shouldStamp, shouldStampSvelte, stamp, } from './stamping.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, isReticleDisabledWebBuild, } from './disabled-browser-stub.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';
@@ -244,11 +244,9 @@ export function connectModuleSource(options, devModule = null) {
  * 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 the web default's
- * stub-replacement 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.
@@ -279,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. */
@@ -291,18 +293,33 @@ export function reticle(options = {}) {
     /**
      * 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;
@@ -331,7 +348,8 @@ export function reticle(options = {}) {
         desktop,
         inject,
         injected: () => injected,
-        htmlTransformed: () => htmlTransformed,
+        connectDelivered: () => htmlTransformed || connectDelivered,
+        connectModule: () => connectModuleUrl(base),
         warn,
     });
     return {
@@ -417,8 +435,13 @@ export function reticle(options = {}) {
             };
         },
         transform(code, id) {
-            if (isReticleDisabledWebBuild(desktop, command))
+            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.
@@ -452,7 +475,7 @@ export function reticle(options = {}) {
             return stamp(code, id);
         },
         resolveId(id, importer) {
-            if (isReticleDisabledWebBuild(desktop, command) && id === RETICLE_SENSOR) {
+            if (disabledBuild() && id === RETICLE_SENSOR) {
                 return RETICLE_DISABLED_STUB;
             }
             // Desktop: remember the module the HTML points at, so `transform` can prepend connect() into
@@ -470,18 +493,20 @@ export function reticle(options = {}) {
             return inject && id === RETICLE_CONNECT_MODULE ? RETICLE_CONNECT_MODULE : null;
         },
         load(id) {
-            if (isReticleDisabledWebBuild(desktop, command) && id === RETICLE_DISABLED_STUB) {
+            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);
         },
@@ -506,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
@@ -559,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
@@ -588,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());
         },
@@ -596,7 +626,7 @@ export function reticle(options = {}) {
         checkHtmlHookForTest: watch.checkHtmlHookRan,
         injectionWatchForTest: watch,
         transformIndexHtml() {
-            if (isReticleDisabledWebBuild(desktop, command))
+            if (disabledBuild())
                 return [];
             htmlTransformed = true;
             if (desktop && inject && 'serve' === command)

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

package/dist/stamping.d.ts

@@ -8,6 +8,7 @@
  * the JSX one is `@reticlehq/babel-plugin`, which also reads the opt-out on its own for the callers
  * that reach it without Vite.
  */
+export declare const NODE_MODULES = "node_modules";
 /** A module id we may stamp at all: not virtual, not a dependency. Extension decides which stamper. */
 export declare function stampableId(id: string): string | null;
 export declare function shouldStamp(id: string): boolean;

package/dist/stamping.js

@@ -17,7 +17,7 @@ import { SVELTE_FILE } from './svelte-source.js';
 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';
+export const NODE_MODULES = 'node_modules';
 /** A module id we may stamp at all: not virtual, not a dependency. Extension decides which stamper. */
 export function stampableId(id) {
     if (id.startsWith(VIRTUAL_PREFIX))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Vite plugin for Reticle: dev-only source-map stamping plus auto-injected reticle.connect(). apply:'serve' guarantees it never ships to production.",
   "type": "module",
   "license": "Apache-2.0",
@@ -41,15 +41,15 @@
   ],
   "dependencies": {
     "@babel/core": "^7.26.0",
-    "@reticlehq/babel-plugin": "3.3.0",
-    "@reticlehq/core": "3.3.0"
+    "@reticlehq/babel-plugin": "3.5.0",
+    "@reticlehq/core": "3.5.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
     "esbuild": "^0.28.2",
-    "svelte": "^5.56.10",
+    "svelte": "^5.57.1",
     "vite": "^8",
-    "@reticlehq/react": "3.3.0"
+    "@reticlehq/react": "3.5.0"
   },
   "peerDependencies": {
     "vite": ">=4"