@reticlehq/vite-plugin 3.2.0 → 3.4.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,6 +56,21 @@ 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
+
+A file whose **first non-empty line** is a comment carrying `@reticle-ignore` is not stamped, and its elements will have no `file:line`:
+
+```tsx
+// @reticle-ignore
+export function Generated() { … }
+```
+
+`/* @reticle-ignore */` works the same way, and a `.svelte` component uses `<!-- @reticle-ignore -->` because it has no line for a `//` before its markup.
+
+Whole file, first line, on purpose. The reasons to opt out are file-shaped — a generated component, a snapshot test the stamp would break — and a marker that worked from line 40 would be a marker nobody can find. `include`/`exclude` globs still exist for whole directories; this is for the one file whose reason sits with the file.
+
+It is not silent. The plugin reports each opted-out file once, by name, in the dev-server output, so an opt-out is something a reader sees rather than something they discover months later from a pointer that never resolves.
 
 Apache-2.0.

package/dist/connect-args.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `reticle.connect` argument literal the plugin bakes into the generated connect call.
+ *
+ * Split out of index.ts, which sits six lines under its 1000-line cap on main -- this option could
+ * not be added inline. Cohesive on its own terms: one function, whose whole job is deciding which
+ * of the plugin's options the PAGE needs to be told about.
+ */
+import type { ReticleVitePluginOptions } from './index.js';
+/** Build the `reticle.connect` argument literal — only includes keys the user set. */
+export declare function connectArgs(options: ReticleVitePluginOptions): string;

package/dist/connect-args.js

@@ -0,0 +1,71 @@
+/**
+ * The `reticle.connect` argument literal the plugin bakes into the generated connect call.
+ *
+ * Split out of index.ts, which sits six lines under its 1000-line cap on main -- this option could
+ * not be added inline. Cohesive on its own terms: one function, whose whole job is deciding which
+ * of the plugin's options the PAGE needs to be told about.
+ */
+import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
+/** Build the `reticle.connect` argument literal — only includes keys the user set. */
+export 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 -- except this one carries a VALUE, so the env var is parsed rather
+    // than tested for '1'. A non-numeric env var is ignored rather than fatal: it must not take down
+    // an app's dev server, and the SDK clamps whatever does arrive.
+    const envBodyChars = Number(process.env['VITE_RETICLE_BODY_MAX_CHARS']);
+    const bodyChars = options.networkBodyMaxChars ??
+        (Number.isFinite(envBodyChars) && envBodyChars > 0 ? envBodyChars : undefined);
+    if (bodyChars !== undefined) {
+        args['networkBodyMaxChars'] = bodyChars;
+    }
+    // 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) : '';
+}

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

@@ -0,0 +1,15 @@
+export declare const RETICLE_DISABLED_STUB = "\0reticle-disabled-stub";
+/**
+ * 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

@@ -0,0 +1,200 @@
+export const RETICLE_DISABLED_STUB = '\0reticle-disabled-stub';
+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() {}
+  signal() {}
+  state() {}
+  renderCommit() {}
+  describe() {}
+  endSession() {}
+  observeHotUpdates() {}
+  disconnect() {}
+
+  get connected() {
+    return false;
+  }
+}
+
+export const reticle = new Reticle();
+
+export const SESSION_AUTO = 'auto';
+
+export function setIgnoreSelectors() {}
+
+export function registerAdapter() {}
+export function identifyComponent() {
+  return null;
+}
+export function readComponentState() {
+  return undefined;
+}
+export function elementHasHoverHandlers() {
+  return false;
+}
+export function adapterNames() {
+  return [];
+}
+
+export function registerStore() {}
+export function unregisterStore() {}
+export function storeNames() {
+  return [];
+}
+export function readStores() {
+  return {};
+}
+export function readStoresWithTruncation() {
+  return { stores: {} };
+}
+export function sourceOwner() {
+  return undefined;
+}
+export function markAdapterSource() {}
+
+export function tanstackQueryStore() {
+  return undefined;
+}
+export function jotaiStore() {
+  return undefined;
+}
+export function xstateStore() {
+  return undefined;
+}
+export function valtioStore() {
+  return undefined;
+}
+export function mobxStore() {
+  return undefined;
+}
+export function recoilStore() {
+  return undefined;
+}
+export function svelteStore() {
+  return undefined;
+}
+export function piniaStore() {
+  return undefined;
+}
+export function pushStore() {
+  return undefined;
+}
+
+export function registerCapabilities() {}
+export function getCapabilities() {
+  return {};
+}
+export function hasCapabilities() {
+  return false;
+}
+export function setCapabilitiesListener() {}
+
+export function createReticleEmitter() {
+  return {
+    signal() {},
+    state() {},
+  };
+}
+
+export function commitAndSignal() {}
+export function registerReticleDomain() {}
+
+export function buildSnapshot() {
+  return {};
+}
+
+export function inspectChart() {
+  return {};
+}
+export function canvasChartData() {
+  return {};
+}
+
+export function matchQuery() {
+  return false;
+}
+export function runQuery() {
+  return undefined;
+}
+
+export function executeAction() {
+  return undefined;
+}
+export function executeSequence() {
+  return undefined;
+}
+
+export function describe() {
+  return undefined;
+}
+export function getRole() {
+  return undefined;
+}
+export function getAccessibleName() {
+  return undefined;
+}
+export function getStates() {
+  return {};
+}
+export function isVisible() {
+  return false;
+}
+
+export class RefRegistry {
+  get size() {
+    return 0;
+  }
+
+  markEdited() {}
+
+  mintedBeforeLastEdit() {
+    return false;
+  }
+
+  refFor() {
+    return undefined;
+  }
+
+  resolve() {
+    return null;
+  }
+}
+
+export const refs = new RefRegistry();
+
+export class Annotator {
+  constructor() {}
+
+  get active() {
+    return false;
+  }
+
+  get markCount() {
+    return 0;
+  }
+
+  mount() {}
+  unmount() {}
+}
+
+export function installAnnotator() {}
+
+export function resolveMarkAnchor() {
+  return undefined;
+}
+`;

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): DaemonPortChoice;

package/dist/discover-port.js

@@ -1,6 +1,7 @@
 /**
- * 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.
  */
@@ -8,6 +9,8 @@ import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, } from '@reticlehq/core';
 import { stateHome } from './state-home.js';
+import { readConfiguredPort } from './project-id.js';
+import { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
 /** process.kill(pid, 0) throws iff the process is gone — the same liveness probe the daemon uses. */
 function isAlive(pid) {
     try {
@@ -23,7 +26,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 +49,39 @@ 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) {
+    const configured = readConfiguredPort(cwd);
+    return chooseDaemonPort({
+        discovered: discoverDaemonPort(projectId, stateHome(), isAlive, configured),
+        configured,
+        explicit,
+    });
 }