@reticlehq/vite-plugin 2.14.0 → 3.1.0

package/dist/injection-postcondition.js

@@ -0,0 +1,123 @@
+/**
+ * The check that says whether `reticle.connect()` actually made it into the page, and what to say
+ * when it did not.
+ *
+ * These three messages live together because choosing between them is the whole subtlety. Each says
+ * exactly as much as the plugin actually knows and no more, and getting that wrong in either
+ * direction has cost real users:
+ *
+ *  - Claim "this is broken" when it is not, and the tool whose entire pitch is that it does not
+ *    raise false alarms has just raised one.
+ *  - Say nothing when it IS broken, and someone waits twenty minutes for a session that can never
+ *    arrive.
+ */
+import { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
+/**
+ * How long to wait before concluding that the connect script never made it in.
+ *
+ * Generous on purpose: the browser has to request the entry, and a cold dev server transforming a
+ * large app can take a moment. A false warning would train people to ignore a real one.
+ */
+export const DEV_INJECTION_GRACE_MS = 10_000;
+/**
+ * The BUILD message. A build always runs every transform, so "my transform never ran" and "the
+ * bundle has no connect()" are the same statement there, and stating it as a certainty is correct.
+ */
+export const notInjectedMessage = () => `[${RETICLE_VITE_PLUGIN_NAME}] could not inject reticle.connect(): the HTML entry module was ` +
+    'never matched, so this app carries no instrumentation and will never connect. Check that ' +
+    'index.html references your entry with a <script type="module" src="...">, or pass ' +
+    '`inject: false` and call reticle.connect({ token: __RETICLE_TOKEN__ }) yourself. The plugin ' +
+    'still inlines that define; a connect without it is refused.';
+/**
+ * The DEV message, which must be weaker — and this is the whole reason the two are separate.
+ *
+ * In serve, `injected` records "my transform ran THIS session", which is not the same as "the app
+ * has no connect()". Vite serves an unchanged module straight from its transform cache, so on a
+ * warm cache the transform never runs and the flag stays false, so wording that announces the app
+ * "will never connect" is a false alarm raised over a served entry that does contain the injection.
+ *
+ * So dev reports what it actually knows: unconfirmed, with the benign explanation first.
+ */
+export const unconfirmedInjectionMessage = () => `[${RETICLE_VITE_PLUGIN_NAME}] could not confirm reticle.connect() was injected: the HTML entry ` +
+    'module was not transformed this session. That is expected when Vite served it from its ' +
+    'transform cache. If the app does not appear in `reticle status`, restart the dev server with ' +
+    '`--force` to bypass the cache, then check that index.html references your entry with a ' +
+    '<script type="module" src="...">.';
+/**
+ * The web message.
+ *
+ * On the web the connect script is added by `transformIndexHtml`. A framework that renders its own
+ * HTML never calls that hook, so the script is never added and the app never appears in
+ * `reticle status`. Known examples: SvelteKit, Nuxt, Astro, React Router in framework mode and
+ * TanStack Start. Each was found the same way — a user waiting on a session that could never
+ * arrive — so the plain-language cause comes first and the fix comes second.
+ */
+export const htmlHookNeverRanMessage = () => `[${RETICLE_VITE_PLUGIN_NAME}] this app will never connect: the dev server never asked this ` +
+    'plugin to transform any HTML, so reticle.connect() was never added to the page. That usually ' +
+    'means your framework renders its own HTML instead of serving index.html — SvelteKit, Nuxt, ' +
+    'Astro, React Router (framework mode) and TanStack Start all do. Fix: import ' +
+    "'@reticlehq/browser' and call reticle.connect({ token: __RETICLE_TOKEN__ }) yourself from your " +
+    'app entry file, and pass `inject: false` to this plugin so the two do not both try.';
+const defaultSchedule = (run, ms) => {
+    const timer = setTimeout(run, ms);
+    // Never hold a dev server open on account of a warning it may not even need to print.
+    timer.unref?.();
+};
+export function createInjectionWatch(deps) {
+    /**
+     * Has a browser actually asked this dev server for a PAGE?
+     *
+     * The fact that makes "the HTML hook never ran" mean anything. `transformIndexHtml` only runs when
+     * a document is requested, so on a dev server nobody has opened it has correctly never run — and
+     * a check that cannot tell that apart from a framework owning its own HTML will call a perfectly
+     * healthy app permanently broken. That is what it did: the timer was armed at server boot, so ten
+     * seconds after startup an unopened dev server was told its app would never connect.
+     */
+    let htmlRequested = false;
+    const isDocumentRequest = (req) => true === req.headers?.accept?.includes('text/html');
+    /**
+     * Warn when the HTML hook never ran. NOT scheduled from `transformIndexHtml` — a hook that never
+     * runs would never arm its own check, and it would be unreachable in exactly the case it exists
+     * for. It hangs off the first request instead: independent of the hook, but still evidence-based.
+     *
+     * `htmlRequested` is re-checked here rather than only at the arming site. The timer is one caller;
+     * this states the precondition where the claim is actually made, which is where somebody reading
+     * `warn(htmlHookNeverRanMessage())` needs to see it.
+     */
+    const checkHtmlHookRan = () => {
+        if (deps.desktop || !deps.inject || deps.htmlTransformed())
+            return;
+        // Nobody has opened the app. That says nothing about whether it can connect.
+        if (!htmlRequested)
+            return;
+        deps.warn(htmlHookNeverRanMessage());
+    };
+    /**
+     * Note a document request, and start the clock from THERE.
+     *
+     * The grace period is meant to cover "the browser asked, so the transform should have happened by
+     * now". Measured from server start it was covering "the server booted", which is a question about
+     * the developer's attention rather than about the app.
+     */
+    const noteHtmlRequest = () => {
+        if (htmlRequested)
+            return;
+        htmlRequested = true;
+        (deps.schedule ?? defaultSchedule)(checkHtmlHookRan, DEV_INJECTION_GRACE_MS);
+    };
+    /** Warn (never throw) in dev — a running dev server should report the doubt, not die of it. */
+    const checkInjected = () => {
+        if (!deps.desktop || !deps.inject || deps.injected())
+            return;
+        deps.warn(unconfirmedInjectionMessage());
+    };
+    /**
+     * In serve the HTML is sent BEFORE the browser requests the entry module, so asserting at html
+     * time would fire on every healthy start. Deferred here rather than at the call site, so that
+     * every "when may this speak" rule in the plugin sits in the one file that argues about them.
+     */
+    const armDesktopCheck = () => {
+        (deps.schedule ?? defaultSchedule)(checkInjected, DEV_INJECTION_GRACE_MS);
+    };
+    return { noteHtmlRequest, isDocumentRequest, checkHtmlHookRan, checkInjected, armDesktopCheck };
+}

package/dist/plugin-name.d.ts

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

package/dist/plugin-name.js

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

package/dist/project-id.d.ts

@@ -13,13 +13,31 @@ export declare function shortHash(input: string): string;
  * Derive the stable projectId from the package name (may be undefined) and the absolute root path.
  *
  * The rule itself is core's `projectIdFrom`, shared with `reticle init`: this id is what scopes a
- * session to an app, so what the plugin stamps and what init records must be the same string. They
- * used to be two identical copies kept in step by a comment.
+ * session to an app, so what the plugin stamps and what init records must be the same string — ONE
+ * implementation, not two copies kept in step by hand.
  */
 export declare function deriveProjectId(pkgName: string | undefined, rootPath: string): string;
+/** Reads a file, or throws — the one filesystem touch these walkers make, injectable for tests. */
+type ReadFile = (path: string) => string;
 /**
- * Resolve the projectId for a plugin instance: an explicit option wins; otherwise derive from the
- * app's package.json name + root. `cwd` and `readPkgName` are injectable so the resolution is
- * unit-tested without touching the real filesystem.
+ * Read the `projectId` `reticle init` recorded in the nearest `.reticle.json`, or undefined.
+ *
+ * This is the id of RECORD. The derivation below is a fallback for a project that has never been
+ * 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;
+/**
+ * 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.
+ *
+ * The config step is what makes the id survive a dev server that does not share a filesystem with
+ * the CLI. Derivation hashes the ABSOLUTE ROOT, so a containerised Vite (`/app`) and the host `init`
+ * that wired it produce different ids for one project — the page announces one, the daemon expects
+ * the other, and the bridge refuses the connection with `authentication failed`, which names
+ * neither. Reading the file `init` already wrote costs one `readFileSync` at config time and makes
+ * the two halves agree by construction rather than by coincidence of working directory.
+ *
+ * `cwd`, `readPkgName` and `readConfiguredId` are injectable so resolution is unit-tested without
+ * touching the real filesystem.
  */
-export declare function resolveProjectId(explicit: string | undefined, cwd: string, readPkgName?: (dir: string) => string | undefined): string;
+export declare function resolveProjectId(explicit: string | undefined, cwd: string, readPkgName?: (dir: string) => string | undefined, readConfiguredId?: (dir: string) => string | undefined): string;

package/dist/project-id.js

@@ -8,8 +8,10 @@
  */
 import { createHash } from 'node:crypto';
 import { dirname, join } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { PROJECT_ID_HASH_LENGTH, projectIdFrom } from '@reticlehq/core';
+/** The project config `reticle init` writes, and the id of record it carries. */
+const RETICLE_CONFIG_BASENAME = '.reticle.json';
 export { slugifyPackageName } from '@reticlehq/core';
 /** A short, stable hex fingerprint of the absolute project root (disambiguates same-named checkouts). */
 export function shortHash(input) {
@@ -19,30 +21,48 @@ export function shortHash(input) {
  * Derive the stable projectId from the package name (may be undefined) and the absolute root path.
  *
  * The rule itself is core's `projectIdFrom`, shared with `reticle init`: this id is what scopes a
- * session to an app, so what the plugin stamps and what init records must be the same string. They
- * used to be two identical copies kept in step by a comment.
+ * session to an app, so what the plugin stamps and what init records must be the same string — ONE
+ * implementation, not two copies kept in step by hand.
  */
 export function deriveProjectId(pkgName, rootPath) {
     return projectIdFrom(pkgName, rootPath, shortHash);
 }
-/** Read the `name` from the nearest package.json at or above `startDir`, or undefined if none. */
-function readNearestPackageName(startDir) {
+const readFileOrThrow = (path) => readFileSync(path, 'utf8');
+/**
+ * How far up to look for `.reticle.json`, and WHY it is not the package.json depth below.
+ *
+ * The same number, for the same reason, as the server's `MAX_CONFIG_SEARCH_DEPTH`: deep enough for
+ * an app in `frontend/` or `apps/web/`, a worktree beside its main checkout, and a package inside a
+ * monorepo — and shallow enough that a dev server started somewhere unrelated cannot silently adopt
+ * a distant ancestor's config and announce another app's identity. The two walkers have to agree,
+ * because the whole point of reading this file is that the plugin and the CLI stop disagreeing.
+ */
+const MAX_CONFIG_SEARCH_DEPTH = 6;
+/**
+ * How far up to look for `package.json`, which is a different question with a different answer.
+ *
+ * A package name is only ever used to BUILD an id, never to adopt one, so an over-eager walk here
+ * costs a less specific name rather than the wrong app's identity. Left as it was.
+ */
+const MAX_PACKAGE_SEARCH_DEPTH = 50;
+/**
+ * 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.
+ */
+function readNearestField(startDir, basename, field, readFile, maxDepth) {
     let dir = startDir;
-    for (let depth = 0; depth < 50; depth++) {
-        const pkgPath = join(dir, 'package.json');
-        if (existsSync(pkgPath)) {
-            try {
-                const parsed = JSON.parse(readFileSync(pkgPath, 'utf8'));
-                if ('object' === typeof parsed && parsed !== null) {
-                    const name = parsed['name'];
-                    if ('string' === typeof name && name.length > 0)
-                        return name;
-                }
-            }
-            catch {
-                // unreadable package.json → keep walking up
+    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)
+                    return value;
             }
         }
+        catch {
+            // missing, unreadable or unparseable → keep walking up
+        }
         const parent = dirname(dir);
         if (parent === dir)
             break; // reached filesystem root
@@ -50,13 +70,38 @@ function readNearestPackageName(startDir) {
     }
     return undefined;
 }
+/** 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);
+}
 /**
- * Resolve the projectId for a plugin instance: an explicit option wins; otherwise derive from the
- * app's package.json name + root. `cwd` and `readPkgName` are injectable so the resolution is
- * unit-tested without touching the real filesystem.
+ * Read the `projectId` `reticle init` recorded in the nearest `.reticle.json`, or undefined.
+ *
+ * This is the id of RECORD. The derivation below is a fallback for a project that has never been
+ * 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);
+}
+/**
+ * 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.
+ *
+ * The config step is what makes the id survive a dev server that does not share a filesystem with
+ * the CLI. Derivation hashes the ABSOLUTE ROOT, so a containerised Vite (`/app`) and the host `init`
+ * that wired it produce different ids for one project — the page announces one, the daemon expects
+ * the other, and the bridge refuses the connection with `authentication failed`, which names
+ * neither. Reading the file `init` already wrote costs one `readFileSync` at config time and makes
+ * the two halves agree by construction rather than by coincidence of working directory.
+ *
+ * `cwd`, `readPkgName` and `readConfiguredId` are injectable so resolution is unit-tested without
+ * touching the real filesystem.
  */
-export function resolveProjectId(explicit, cwd, readPkgName = readNearestPackageName) {
+export function resolveProjectId(explicit, cwd, readPkgName = readNearestPackageName, readConfiguredId = readConfiguredProjectId) {
     if (explicit !== undefined && explicit.length > 0)
         return explicit;
+    const configured = readConfiguredId(cwd);
+    if (configured !== undefined && configured.length > 0)
+        return configured;
     return deriveProjectId(readPkgName(cwd), cwd);
 }

package/dist/vitest-browser.d.ts

@@ -1,8 +1,8 @@
 /**
  * Telling Vitest's browser-mode runner apart from every other Vite server.
  *
- * Split out of index.ts at the file cap. Small, but it is the discriminator a wrong first cut got
- * wrong in production, so it earns its own file and its own name.
+ * Small, but it is the discriminator a wrong cut gets wrong in production, so it earns its own file
+ * and its own name.
  */
 /**
  * Is THIS server Vitest's browser-mode runner?

package/dist/vitest-browser.js

@@ -1,8 +1,8 @@
 /**
  * Telling Vitest's browser-mode runner apart from every other Vite server.
  *
- * Split out of index.ts at the file cap. Small, but it is the discriminator a wrong first cut got
- * wrong in production, so it earns its own file and its own name.
+ * Small, but it is the discriminator a wrong cut gets wrong in production, so it earns its own file
+ * and its own name.
  */
 /**
  * Is THIS server Vitest's browser-mode runner?

package/dist/watch-ignore.d.ts

@@ -1,11 +1,11 @@
 /**
  * Normalising Vite's watcher `ignored` list, which is not a list.
  *
- * Split out of index.ts at the file cap. Small but cohesive: one third-party type shape, one
- * runtime hazard it hides, and the guard that makes the plugin's return assignable without a cast.
+ * Small but cohesive: one third-party type shape, one runtime hazard it hides, and the guard that
+ * makes the plugin's return assignable without a cast.
  */
 /**
- * Append our journal pattern to whatever the app already ignored, without assuming it is an array.
+ * Append Reticle's journal pattern to whatever the app already ignored, without assuming it is an array.
  *
  * Vite's `ignored` is `AnymatchMatcher`, so `watch: { ignored: '**\/fixtures/**' }` is a legal
  * config. Spreading that string would explode it into one pattern PER CHARACTER — every one of

package/dist/watch-ignore.js

@@ -1,11 +1,11 @@
 /**
  * Normalising Vite's watcher `ignored` list, which is not a list.
  *
- * Split out of index.ts at the file cap. Small but cohesive: one third-party type shape, one
- * runtime hazard it hides, and the guard that makes the plugin's return assignable without a cast.
+ * Small but cohesive: one third-party type shape, one runtime hazard it hides, and the guard that
+ * makes the plugin's return assignable without a cast.
  */
 /**
- * Append our journal pattern to whatever the app already ignored, without assuming it is an array.
+ * Append Reticle's journal pattern to whatever the app already ignored, without assuming it is an array.
  *
  * Vite's `ignored` is `AnymatchMatcher`, so `watch: { ignored: '**\/fixtures/**' }` is a legal
  * config. Spreading that string would explode it into one pattern PER CHARACTER — every one of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "2.14.0",
+  "version": "3.1.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",
@@ -8,7 +8,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reticlehq/reticle.git",
-    "directory": "packages/vite-plugin"
+    "directory": "adapters/build/vite"
   },
   "homepage": "https://github.com/reticlehq/reticle#readme",
   "bugs": "https://github.com/reticlehq/reticle/issues",
@@ -41,14 +41,15 @@
   ],
   "dependencies": {
     "@babel/core": "^7.26.0",
-    "@reticlehq/babel-plugin": "2.14.0",
-    "@reticlehq/core": "2.14.0"
+    "@reticlehq/babel-plugin": "3.1.0",
+    "@reticlehq/core": "3.1.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
+    "esbuild": "^0.28.2",
     "svelte": "^5.56.10",
     "vite": "^8",
-    "esbuild": "^0.28.2"
+    "@reticlehq/react": "3.1.0"
   },
   "peerDependencies": {
     "vite": ">=4"
@@ -65,7 +66,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsc -b && node scripts/build-cjs.mjs",
+    "build": "tsc -b && node ../../../scripts/alias-dist.mjs && node scripts/build-cjs.mjs",
     "typecheck": "tsc -b",
     "lint": "eslint src",
     "test:unit": "vitest run src --passWithNoTests",