@reticlehq/vite-plugin 2.6.0 → 2.8.0

package/README.md

@@ -2,39 +2,57 @@
 
 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.
-- **Auto-connect** — injects a dev-only `install(); reticle.connect()` so you don't touch your entry file.
-- **Production-safe by construction** — `apply: 'serve'` means Vite drops the plugin entirely from `vite build`. There is no env gate to forget; instrumentation cannot reach a production bundle.
+- **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.
+- **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.
+- **Production-safe by construction**: `apply: 'serve'` means Vite drops the plugin entirely from `vite build`. There is no env gate to forget; instrumentation cannot reach a production web bundle.
 
-Usually installed via the umbrella package and imported from its `/vite` subpath:
+## Install
 
 ```bash
-npm i -D @reticlehq/core
+npm i -D @reticlehq/react @reticlehq/vite-plugin
 ```
 
+`@reticlehq/react` is the runtime kit the injected `connect()` imports (it re-exports the browser SDK). `vite >= 4` is a peer dependency.
+
+## Use
+
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
-import { reticle } from '@reticlehq/core/vite';
+import { reticle } from '@reticlehq/vite-plugin';
 
 export default defineConfig({
-  plugins: [react(), reticle()],
+  plugins: [reticle(), react()],
 });
 ```
 
-That is the entire integration — no entry-file edit, no Babel-plugin wiring, no env gating. `npx @reticlehq/core init` adds this line for you automatically in a Vite project.
+That is the entire integration: no entry-file edit, no Babel-plugin wiring, no env gating. `npx @reticlehq/server init` writes this line for you in a Vite project, inserting `reticle()` right after the opening `[`, which is why that is the order shown here.
+
+Array order does not actually matter: the plugin declares `enforce: 'pre'`, so Vite runs it before `@vitejs/plugin-react` wherever you put it.
 
 ## Options
 
 ```ts
 reticle({
   port, // bridge WebSocket port; baked into connect() only when non-default
-  session, // stable session label (defaults to the SDK's auto id)
+  session, // stable session label; defaults to a fresh per-tab id
+  projectId, // stable project identity; defaults to one derived from package.json name + root
   token, // auth token forwarded to connect() when the bridge requires one
-  sourceMapping, // default true — stamp data-reticle-source (harmless on React <=18)
-  inject, // default true — auto-inject reticle.connect()
+  root, // project root, so reported source paths are repo-relative
+  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
+  desktop, // default false; also apply to `vite build`, for an Electron/Tauri renderer
+  onWarn, // where a diagnostic goes; defaults to the console
 });
 ```
 
-MIT.
+`captureNetworkBodies` is off by default because a body is the one part of a request that routinely carries a card number, a token, or a customer's address. It is also settable as `VITE_RETICLE_CAPTURE_BODIES=1` for a single debugging 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.
+
+Apache-2.0.

package/dist/index.d.ts

@@ -136,13 +136,13 @@ export interface ReticleVitePlugin {
  */
 export interface ViteDevServerLike {
     middlewares: {
-        use: (handler: (req: {
-            url?: string;
-        }, res: unknown, next: () => void) => void) => void;
+        use(handler: (req: {
+            url?: string | undefined;
+        }, res: unknown, next: () => void) => void): void;
     };
     moduleGraph: {
-        getModuleById: (id: string) => object | undefined;
-        invalidateModule: (mod: object) => void;
+        getModuleById(id: string): object | undefined;
+        invalidateModule(mod: object): void;
     };
 }
 interface HtmlTag {
@@ -190,6 +190,27 @@ export declare function readPairingToken(): string | undefined;
 export declare const RETICLE_DEV_MODULE_CANDIDATES: readonly ["src/reticle-dev.ts", "src/reticle-dev.js", "src/reticle-dev.tsx", "src/reticle-dev.jsx"];
 /** The app's dev module, as an importable path — or null when the app has none. */
 export declare function findDevModule(root: string, exists: (p: string) => boolean): string | null;
+/**
+ * Which SDK package this app actually has, and whether `install()` applies.
+ *
+ * The injected connect used to name `@reticlehq/react` unconditionally. That is right for a React
+ * app and fatal for any other: `reticle init` gives a Vue or Svelte codebase the framework-neutral
+ * `@reticlehq/browser` — deliberately, because a package named `@reticlehq/react` with `react` in
+ * its peers has no business in a Vue app — and the injected import then names a package that is not
+ * installed, so nothing connects and the page reports no session with no obvious cause.
+ *
+ * Measured end to end on a pristine `npm create vite --template vue` app: init wrote every file
+ * correctly and the tab never dialled the daemon, because of this one specifier.
+ *
+ * The React kit WINS when both resolve: it is a superset (it re-exports the sensor and adds the
+ * adapter), so an app that has it wants component identity. `install()` is the adapter's alone and
+ * the sensor does not export it — naming it against the sensor would trade a missing module for a
+ * missing export.
+ */
+export declare function installedSdk(appRoot: string, canResolve?: (dep: string) => boolean): {
+    specifier: string;
+    usesInstall: boolean;
+};
 export declare function connectModuleSource(options: ReticleVitePluginOptions, devModule?: string | null): string;
 /**
  * Reticle Vite plugin. Add to your `plugins` array and the entire integration is done:

package/dist/index.js

@@ -15,6 +15,8 @@ export const RETICLE_VITE_PLUGIN_NAME = 'reticle';
 // specifier yields both `reticle` (connect) and `install` (the React adapter). NOT `@reticlehq/core`
 // — that is the isomorphic foundation and exports neither.
 const RETICLE_PACKAGE = '@reticlehq/react';
+/** The framework-neutral sensor, which a Vue or Svelte app gets instead. See installedSdk. */
+const RETICLE_SENSOR = '@reticlehq/browser';
 /**
  * Compile-time global carrying the daemon's pairing token, for connects the plugin does not write
  * itself. The bridge requires the token even on localhost, and nothing in a browser can read the
@@ -245,9 +247,38 @@ export function findDevModule(root, exists) {
     }
     return null;
 }
+/**
+ * Which SDK package this app actually has, and whether `install()` applies.
+ *
+ * The injected connect used to name `@reticlehq/react` unconditionally. That is right for a React
+ * app and fatal for any other: `reticle init` gives a Vue or Svelte codebase the framework-neutral
+ * `@reticlehq/browser` — deliberately, because a package named `@reticlehq/react` with `react` in
+ * its peers has no business in a Vue app — and the injected import then names a package that is not
+ * installed, so nothing connects and the page reports no session with no obvious cause.
+ *
+ * Measured end to end on a pristine `npm create vite --template vue` app: init wrote every file
+ * correctly and the tab never dialled the daemon, because of this one specifier.
+ *
+ * The React kit WINS when both resolve: it is a superset (it re-exports the sensor and adds the
+ * adapter), so an app that has it wants component identity. `install()` is the adapter's alone and
+ * the sensor does not export it — naming it against the sensor would trade a missing module for a
+ * missing export.
+ */
+export function installedSdk(appRoot, canResolve = (dep) => null !== resolvableChain([dep], appRoot)) {
+    if (canResolve(RETICLE_PACKAGE))
+        return { specifier: RETICLE_PACKAGE, usesInstall: true };
+    if (canResolve(RETICLE_SENSOR))
+        return { specifier: RETICLE_SENSOR, usesInstall: false };
+    // Neither resolves: keep the historical name so the failure reads as "the SDK is not installed"
+    // rather than as a package nobody recognises.
+    return { specifier: RETICLE_PACKAGE, usesInstall: true };
+}
 export function connectModuleSource(options, devModule = null) {
     const args = connectArgs(options);
-    const base = `import { reticle, install } from '${RETICLE_PACKAGE}';\ninstall();\nreticle.connect(${args});\n`;
+    const sdk = installedSdk(options.root ?? process.cwd());
+    const named = sdk.usesInstall ? 'reticle, install' : 'reticle';
+    const call = sdk.usesInstall ? 'install();\n' : '';
+    const base = `import { ${named} } from '${sdk.specifier}';\n${call}reticle.connect(${args});\n`;
     // AFTER connect: registerStore subscribes through the live SDK, and registering before there is a
     // session to report into drops the first diffs.
     return null === devModule ? base : `${base}import('${devModule}');\n`;
@@ -406,7 +437,11 @@ export function reticle(options = {}) {
                         // no WebSocket, no session, no console message. The FIRST load after `reticle init` —
                         // the one the whole product is judged on — silently did nothing, and it worked on the
                         // next refresh, which is the worst possible shape for a bug like this.
-                        RETICLE_PACKAGE,
+                        //
+                        // Whichever SDK this app actually has: naming `@reticlehq/react` in a Vue app that was
+                        // given the sensor produces the exact boot warning the note below is about, for a
+                        // package that is correctly absent.
+                        installedSdk(appRoot).specifier,
                         // Only in a form that resolves — see above; a name Vite cannot resolve produces a boot
                         // warning that blames Reticle, and a forced re-optimization on every cold start.
                         ...cjsDepIncludes(appRoot),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "2.6.0",
+  "version": "2.8.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",
@@ -35,8 +35,8 @@
   ],
   "dependencies": {
     "@babel/core": "^7.26.0",
-    "@reticlehq/babel-plugin": "2.6.0",
-    "@reticlehq/core": "2.6.0"
+    "@reticlehq/babel-plugin": "2.8.0",
+    "@reticlehq/core": "2.8.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",