@reticlehq/vite-plugin 2.13.1 → 3.1.0

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

@@ -0,0 +1,31 @@
+/**
+ * Telling Vitest's browser-mode runner apart from every other Vite server.
+ *
+ * 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?
+ *
+ * Vitest browser mode renders each component test into its own iframe served by the same Vite dev
+ * server, so `transformIndexHtml` injects into every one of them. The HUD then sits in the test
+ * document's hit-test path and intercepts pointer events, and a user who adds Reticle watches their
+ * unrelated component tests start timing out on clicks.
+ *
+ * The signal is `test.browser.enabled` on the RESOLVED config. The first cut used the `VITEST`
+ * environment variable and was wrong in a way its own unit tests could not show: `VITEST` means
+ * "Vitest is running somewhere in this process", which is ALSO true when a Vitest suite boots an app
+ * in order to test it. `frameworks.integration.test.ts` starts a real Vite dev server per example
+ * app and asserts Reticle connects; under the env check it injected nothing and the suite failed
+ * with "@reticlehq/example-react never connected an Reticle session". CI caught that; three local
+ * battery runs did not, because that suite is not the battery.
+ *
+ * A bare `test` key is wrong the other way — most projects configure Vitest and are not under it.
+ * `test.browser.enabled` is true only for the server actually serving browser-mode test iframes,
+ * which is the one case with a HUD to suppress.
+ *
+ * An explicit `inject: true` still beats it: the check is a default chosen on the user's behalf.
+ */
+export declare function isVitestBrowserServer(config: {
+    test?: unknown;
+}): boolean;

package/dist/vitest-browser.js

@@ -0,0 +1,37 @@
+/**
+ * Telling Vitest's browser-mode runner apart from every other Vite server.
+ *
+ * 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?
+ *
+ * Vitest browser mode renders each component test into its own iframe served by the same Vite dev
+ * server, so `transformIndexHtml` injects into every one of them. The HUD then sits in the test
+ * document's hit-test path and intercepts pointer events, and a user who adds Reticle watches their
+ * unrelated component tests start timing out on clicks.
+ *
+ * The signal is `test.browser.enabled` on the RESOLVED config. The first cut used the `VITEST`
+ * environment variable and was wrong in a way its own unit tests could not show: `VITEST` means
+ * "Vitest is running somewhere in this process", which is ALSO true when a Vitest suite boots an app
+ * in order to test it. `frameworks.integration.test.ts` starts a real Vite dev server per example
+ * app and asserts Reticle connects; under the env check it injected nothing and the suite failed
+ * with "@reticlehq/example-react never connected an Reticle session". CI caught that; three local
+ * battery runs did not, because that suite is not the battery.
+ *
+ * A bare `test` key is wrong the other way — most projects configure Vitest and are not under it.
+ * `test.browser.enabled` is true only for the server actually serving browser-mode test iframes,
+ * which is the one case with a HUD to suppress.
+ *
+ * An explicit `inject: true` still beats it: the check is a default chosen on the user's behalf.
+ */
+export function isVitestBrowserServer(config) {
+    const test = config.test;
+    if (null === test || 'object' !== typeof test)
+        return false;
+    const browser = test.browser;
+    if (null === browser || 'object' !== typeof browser)
+        return false;
+    return true === browser.enabled;
+}

package/dist/watch-ignore.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalising Vite's watcher `ignored` list, which is not a list.
+ *
+ * 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 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
+ * which matches nothing, so the app's own exclusion is silently dropped and no error is raised. A
+ * function matcher is worse: it is not iterable at all, so the spread throws at config time and
+ * takes the dev server down, blaming the last plugin to touch the config.
+ */
+export declare function mergeIgnored(existing: unknown, ours: RegExp): WatchPattern[];
+/** Vite's `AnymatchPattern`, restated so the return type needs no cast. */
+export type WatchPattern = string | RegExp | ((path: string) => boolean);

package/dist/watch-ignore.js

@@ -0,0 +1,26 @@
+/**
+ * Normalising Vite's watcher `ignored` list, which is not a list.
+ *
+ * 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 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
+ * which matches nothing, so the app's own exclusion is silently dropped and no error is raised. A
+ * function matcher is worse: it is not iterable at all, so the spread throws at config time and
+ * takes the dev server down, blaming the last plugin to touch the config.
+ */
+export function mergeIgnored(existing, ours) {
+    if (undefined === existing || null === existing)
+        return [ours];
+    const listed = Array.isArray(existing) ? existing : [existing];
+    // Filtered rather than cast: an entry that is none of the three legal matcher shapes could never
+    // have excluded anything, so dropping it loses nothing and keeps the return honest without `any`.
+    return [...listed.filter(isWatchPattern), ours];
+}
+function isWatchPattern(value) {
+    return 'string' === typeof value || value instanceof RegExp || 'function' === typeof value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "2.13.1",
+  "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.13.1",
-    "@reticlehq/core": "2.13.1"
+    "@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",