@reticlehq/vite-plugin 2.11.0 → 2.13.0

package/dist/announce.d.ts

@@ -0,0 +1,16 @@
+import { type DevServerEntry } from '@reticlehq/core';
+/** The filesystem this needs, injected so the writer is unit-testable without a real home. */
+export interface AnnounceIo {
+    mkdir: (dir: string) => void;
+    writeFile: (path: string, data: string) => void;
+    removeFile: (path: string) => void;
+}
+/**
+ * Publish the entry; returns the cleanup that withdraws it.
+ *
+ * The cleanup is idempotent because it is called from shutdown paths — `close`, `SIGINT`, process
+ * exit — which fire more than once and race each other. A stale entry is handled on the read side
+ * by a liveness check (`liveDevServers`), so a missed cleanup degrades rather than misleads; a
+ * throw inside a signal handler does not degrade, it takes the shutdown with it.
+ */
+export declare function announceDevServer(entry: DevServerEntry, home?: string, io?: AnnounceIo): () => void;

package/dist/announce.js

@@ -0,0 +1,60 @@
+/**
+ * Announce this dev server to `~/.reticle`, so setup can be diagnosed from facts rather than guesses.
+ *
+ * The mirror of `discover-port.ts`: that reads the daemon's `daemon-<port>.json` to find a bridge,
+ * this writes `devserver-<port>.json` so the bridge — and `reticle init` — can see that an
+ * instrumented dev server exists at all.
+ *
+ * Why this is the right half to add, rather than teaching `init` to run the dev command: the script
+ * name, the package manager, the port and the framework are all things a user or their agent can
+ * change, and a setup step that hardcodes any of them breaks on exactly the project that needed it.
+ * This plugin is ALREADY inside the dev server when it boots. It knows the port because it is being
+ * served on it, and it knows the URL because Vite reports it. Nothing here is assumed.
+ *
+ * Writing this file proves one specific thing and no more: the plugin is loaded in the process that
+ * is actually running. That is the fact nobody could observe, and the commonest setup failure — a
+ * plugin added to a config the running dev server already read — is precisely its absence.
+ *
+ * Best-effort throughout. This is a diagnostic, and a diagnostic that can break the dev server it
+ * reports on is worse than no diagnostic at all.
+ */
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { devServerRegistryFileName } from '@reticlehq/core';
+import { stateHome } from './state-home.js';
+const JSON_INDENT = 2;
+const nodeIo = {
+    mkdir: (dir) => void mkdirSync(dir, { recursive: true }),
+    writeFile: (path, data) => void writeFileSync(path, data),
+    removeFile: (path) => void rmSync(path, { force: true }),
+};
+/**
+ * Publish the entry; returns the cleanup that withdraws it.
+ *
+ * The cleanup is idempotent because it is called from shutdown paths — `close`, `SIGINT`, process
+ * exit — which fire more than once and race each other. A stale entry is handled on the read side
+ * by a liveness check (`liveDevServers`), so a missed cleanup degrades rather than misleads; a
+ * throw inside a signal handler does not degrade, it takes the shutdown with it.
+ */
+export function announceDevServer(entry, home = stateHome(), io = nodeIo) {
+    const path = join(home, devServerRegistryFileName(entry.port));
+    try {
+        io.mkdir(home);
+        io.writeFile(path, `${JSON.stringify(entry, null, JSON_INDENT)}\n`);
+    }
+    catch {
+        // No home directory, a read-only filesystem, a sandbox. The app still serves; we just cannot say so.
+    }
+    let withdrawn = false;
+    return () => {
+        if (withdrawn)
+            return;
+        withdrawn = true;
+        try {
+            io.removeFile(path);
+        }
+        catch {
+            // Already gone, or never written. The reader's liveness check covers what we cannot remove.
+        }
+    };
+}

package/dist/discover-port.js

@@ -5,9 +5,9 @@
  * projectId, drop dead daemons — is the pure `pickDaemonPort` in core; this file is just the fs plumbing.
  */
 import { readdirSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, ReticleDir, } from '@reticlehq/core';
+import { daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, } from '@reticlehq/core';
+import { stateHome } from './state-home.js';
 /** process.kill(pid, 0) throws iff the process is gone — the same liveness probe the daemon uses. */
 function isAlive(pid) {
     try {
@@ -23,7 +23,7 @@ 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 = join(homedir(), ReticleDir.ROOT), alive = isAlive) {
+export function discoverDaemonPort(projectId, home = stateHome(), alive = isAlive) {
     const entries = [];
     let files;
     try {

package/dist/index.cjs

@@ -36,7 +36,6 @@ __export(index_exports, {
   RETICLE_DEV_MODULE_CANDIDATES: () => RETICLE_DEV_MODULE_CANDIDATES,
   RETICLE_TOKEN_GLOBAL: () => RETICLE_TOKEN_GLOBAL,
   RETICLE_VITE_PLUGIN_NAME: () => RETICLE_VITE_PLUGIN_NAME,
-  cjsDepIncludes: () => cjsDepIncludes,
   connectChurnWarning: () => connectChurnWarning,
   connectModuleSource: () => connectModuleSource,
   findDevModule: () => findDevModule,
@@ -45,7 +44,7 @@ __export(index_exports, {
   reticle: () => reticle
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_fs5 = require("node:fs");
+var import_node_fs6 = require("node:fs");
 
 // src/missing-token.ts
 function missingTokenWarning(token) {
@@ -79,14 +78,15 @@ function ensurePairingToken(dir) {
 
 // src/index.ts
 var import_node_os2 = require("node:os");
-var import_node_path6 = require("node:path");
-var import_core4 = require("@babel/core");
+var import_node_path8 = require("node:path");
+var import_core6 = require("@babel/core");
 var import_babel_plugin = __toESM(require("@reticlehq/babel-plugin"), 1);
 
 // ../core/dist/constants.js
 var RETICLE_DEFAULT_PORT = 4400;
 var RETICLE_WS_PATH = "/reticle";
-function bridgeWsUrl(port = RETICLE_DEFAULT_PORT, host = "localhost") {
+var RETICLE_CLIENT_HOST = "localhost";
+function bridgeWsUrl(port = RETICLE_DEFAULT_PORT, host = RETICLE_CLIENT_HOST) {
   return `ws://${host}:${String(port)}${RETICLE_WS_PATH}`;
 }
 var ReticleEnv = {
@@ -223,6 +223,8 @@ var ReticleDir = {
    * questions about the product; this answers the user's question about their own work.
    */
   IMPACT_FILE: "impact.json",
+  /** what changes were SUPPOSED to make true —.reticle/intent.json (git-checked, reviewed) */
+  INTENT_FILE: "intent.json",
   /** opt-in pixel baselines —.reticle/visual/<name>.png + <name>.diff.png. */
   VISUAL_SUBDIR: "visual",
   /** verification-run artifacts —.reticle/runs/<runId>.json (the OEM/CI-consumable verdict). */
@@ -241,6 +243,24 @@ var ReticleDir = {
   AMBIENT_FILE: "ambient.json",
   /** per-flow flake ledger — replay outcomes that decide intermittent-failure quarantine. */
   FLAKE_FILE: "flake.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
+   * ~/.reticle/credentials.json instead, because that one must never reach a repository.
+   */
+  CLOUD_LINK_FILE: "cloud.json",
+  /**
+   * local sync bookkeeping — .reticle/cloud-state.json. The pull cursor, when each half last ran,
+   * and the last error. NOT git-checked: it describes this machine's conversation with the server,
+   * and committing one machine's cursor would make every other machine skip what it had not seen.
+   */
+  CLOUD_STATE_FILE: "cloud-state.json",
+  /**
+   * triage decisions pulled BACK from the dashboard — .reticle/issues.json. What a human said about
+   * a defect ("resolved", "not a bug"), so the HUD stops showing it and the next run does not
+   * re-report it as though nobody had looked.
+   */
+  ISSUES_FILE: "issues.json",
   /** Per-flow assertion tiers recorded on each PASSING replay — the gate's anti-downgrade baseline. */
   TIERS_FILE: "assertion-tiers.json",
   /**
@@ -285,6 +305,12 @@ var EventType = {
   STORAGE_CHANGE: "storage.change",
   /** page-level visibility/focus health (distinct from element-level VISIBLE_*). */
   PAGE_HEALTH: "page.health",
+  /**
+   * synthetic: the page called window.open, so the consequence of what was just clicked may live in
+   * another browsing context this one cannot observe (an OAuth popup is the archetype).
+   * `data: { href }` — the URL the page asked to open, when it named one.
+   */
+  CONTEXT_OPENED: "context.opened",
   /** aggregated React commits over a throttle window (dev builds) — `data: { commits }`. Commit storms /
    * wasted re-renders show up here without a per-render flood. */
   RENDER_COMMIT: "render.commit",
@@ -4445,6 +4471,35 @@ function pickDaemonPort(entries, projectId, isAlive2) {
   return matches[0] ?? null;
 }
 
+// ../core/dist/dev-server-registry.js
+var DEV_SERVER_PREFIX = "devserver-";
+var DEV_SERVER_SUFFIX = ".json";
+function devServerRegistryFileName(port) {
+  return `${DEV_SERVER_PREFIX}${String(port)}${DEV_SERVER_SUFFIX}`;
+}
+var DevServerEntrySchema = external_exports.object({
+  port: external_exports.number(),
+  pid: external_exports.number(),
+  /** The project directory the dev server is serving — how a monorepo tells its apps apart. */
+  root: external_exports.string(),
+  /** Where the app is actually served, as the dev server itself reports it. Never assembled here. */
+  url: external_exports.string(),
+  /**
+   * The SDK version in the bundle, so a skew can be named rather than guessed at.
+   *
+   * Optional, and ABSENT rather than empty when it cannot be resolved. `""` reads as "the version is
+   * empty"; a missing field reads as "not known", which is the true statement — and the difference
+   * matters to the one reader who exists for this field, a skew diagnosis.
+   */
+  sdkVersion: external_exports.string().min(1).optional(),
+  startedAt: external_exports.number(),
+  /**
+   * Optional because an app can be running before `init` has ever named it — which is exactly the
+   * state this signal has to be able to describe.
+   */
+  projectId: external_exports.string().optional()
+});
+
 // src/project-id.ts
 var import_node_crypto2 = require("node:crypto");
 var import_node_path2 = require("node:path");
@@ -4482,8 +4537,17 @@ function resolveProjectId(explicit, cwd, readPkgName = readNearestPackageName) {
 
 // src/discover-port.ts
 var import_node_fs3 = require("node:fs");
+var import_node_path4 = require("node:path");
+
+// src/state-home.ts
 var import_node_os = require("node:os");
 var import_node_path3 = require("node:path");
+function stateHome(env = process.env) {
+  const override = env[ReticleEnv.STATE_DIR];
+  return override !== void 0 && override.length > 0 ? override : (0, import_node_path3.join)((0, import_node_os.homedir)(), ReticleDir.ROOT);
+}
+
+// src/discover-port.ts
 function isAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -4492,7 +4556,7 @@ function isAlive(pid) {
     return false;
   }
 }
-function discoverDaemonPort(projectId, home = (0, import_node_path3.join)((0, import_node_os.homedir)(), ReticleDir.ROOT), alive = isAlive) {
+function discoverDaemonPort(projectId, home = stateHome(), alive = isAlive) {
   const entries = [];
   let files;
   try {
@@ -4504,7 +4568,7 @@ function discoverDaemonPort(projectId, home = (0, import_node_path3.join)((0, im
     if (null === daemonRegistryPort(file)) continue;
     try {
       const parsed = DaemonRegistryEntrySchema.safeParse(
-        JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path3.join)(home, file), "utf8"))
+        JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path4.join)(home, file), "utf8"))
       );
       if (parsed.success) entries.push(parsed.data);
     } catch {
@@ -4513,9 +4577,37 @@ function discoverDaemonPort(projectId, home = (0, import_node_path3.join)((0, im
   return pickDaemonPort(entries, projectId, alive) ?? void 0;
 }
 
+// src/announce.ts
+var import_node_fs4 = require("node:fs");
+var import_node_path5 = require("node:path");
+var JSON_INDENT = 2;
+var nodeIo = {
+  mkdir: (dir) => void (0, import_node_fs4.mkdirSync)(dir, { recursive: true }),
+  writeFile: (path, data) => void (0, import_node_fs4.writeFileSync)(path, data),
+  removeFile: (path) => void (0, import_node_fs4.rmSync)(path, { force: true })
+};
+function announceDevServer(entry, home = stateHome(), io = nodeIo) {
+  const path = (0, import_node_path5.join)(home, devServerRegistryFileName(entry.port));
+  try {
+    io.mkdir(home);
+    io.writeFile(path, `${JSON.stringify(entry, null, JSON_INDENT)}
+`);
+  } catch {
+  }
+  let withdrawn = false;
+  return () => {
+    if (withdrawn) return;
+    withdrawn = true;
+    try {
+      io.removeFile(path);
+    } catch {
+    }
+  };
+}
+
 // src/svelte-source.ts
 var import_node_module = require("node:module");
-var import_node_path4 = require("node:path");
+var import_node_path6 = require("node:path");
 var SVELTE_FILE = /\.svelte$/;
 var HOST_ELEMENT_TYPES = /* @__PURE__ */ new Set(["RegularElement", "Element"]);
 var PARENT_KEY = "parent";
@@ -4544,7 +4636,7 @@ function offsetToLineColumn(source, offset) {
   return { line, column: offset - lineStart };
 }
 function sourcePathFor(id, cwd = process.cwd()) {
-  return (0, import_node_path4.relative)(cwd, id).replace(/\\/g, "/");
+  return (0, import_node_path6.relative)(cwd, id).replace(/\\/g, "/");
 }
 function isElementNode(value) {
   if (null === value || typeof value !== "object") return false;
@@ -4598,24 +4690,25 @@ function stampSvelte(code, id, load = defaultLoadCompiler) {
 }
 
 // src/installed.ts
-var import_node_fs4 = require("node:fs");
-var import_node_path5 = require("node:path");
+var import_node_fs5 = require("node:fs");
+var import_node_path7 = require("node:path");
 var import_node_module2 = require("node:module");
 var RETICLE_PACKAGE = "@reticlehq/react";
 var MANIFEST_SEARCH_DEPTH = 5;
 function requireFromApp(from) {
-  return (0, import_node_module2.createRequire)((0, import_node_path5.join)(from, "package.json"));
+  const absoluteFrom = (0, import_node_path7.isAbsolute)(from) ? from : (0, import_node_path7.resolve)(process.cwd(), from);
+  return (0, import_node_module2.createRequire)((0, import_node_path7.join)(absoluteFrom, "package.json"));
 }
 function packageDirOf(specifier, from) {
   try {
-    let dir = (0, import_node_path5.dirname)(requireFromApp(from).resolve(specifier));
+    let dir = (0, import_node_path7.dirname)(requireFromApp(from).resolve(specifier));
     for (let up = 0; up < MANIFEST_SEARCH_DEPTH; up++) {
-      const candidate = (0, import_node_path5.join)(dir, "package.json");
-      if ((0, import_node_fs4.existsSync)(candidate)) {
-        const parsed = JSON.parse((0, import_node_fs4.readFileSync)(candidate, "utf8"));
+      const candidate = (0, import_node_path7.join)(dir, "package.json");
+      if ((0, import_node_fs5.existsSync)(candidate)) {
+        const parsed = JSON.parse((0, import_node_fs5.readFileSync)(candidate, "utf8"));
         if (parsed.name === specifier) return dir;
       }
-      const parent = (0, import_node_path5.dirname)(dir);
+      const parent = (0, import_node_path7.dirname)(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -4640,14 +4733,14 @@ function sdkPackageVersion(from = process.cwd()) {
   } catch {
   }
   try {
-    let dir = (0, import_node_path5.dirname)(require_.resolve(RETICLE_PACKAGE));
+    let dir = (0, import_node_path7.dirname)(require_.resolve(RETICLE_PACKAGE));
     for (let up = 0; up < MANIFEST_SEARCH_DEPTH; up++) {
-      const candidate = (0, import_node_path5.join)(dir, "package.json");
-      if ((0, import_node_fs4.existsSync)(candidate)) {
-        const parsed = JSON.parse((0, import_node_fs4.readFileSync)(candidate, "utf8"));
+      const candidate = (0, import_node_path7.join)(dir, "package.json");
+      if ((0, import_node_fs5.existsSync)(candidate)) {
+        const parsed = JSON.parse((0, import_node_fs5.readFileSync)(candidate, "utf8"));
         if ("string" === typeof parsed.version) return parsed.version;
       }
-      const parent = (0, import_node_path5.dirname)(dir);
+      const parent = (0, import_node_path7.dirname)(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -4658,7 +4751,7 @@ function sdkPackageVersion(from = process.cwd()) {
 function sdkBuildFingerprint(from = process.cwd()) {
   try {
     const entry = requireFromApp(from).resolve(RETICLE_PACKAGE);
-    const { size, mtimeMs } = (0, import_node_fs4.statSync)(entry);
+    const { size, mtimeMs } = (0, import_node_fs5.statSync)(entry);
     return `${String(size)}-${String(Math.trunc(mtimeMs))}`;
   } catch {
     return "unknown";
@@ -4744,7 +4837,7 @@ function shouldStampSvelte(id) {
   return clean !== null && SVELTE_FILE.test(clean);
 }
 function stamp(code, id) {
-  const out = (0, import_core4.transformSync)(code, {
+  const out = (0, import_core6.transformSync)(code, {
     filename: id,
     plugins: [import_babel_plugin.default],
     parserOpts: { plugins: ["jsx", "typescript"] },
@@ -4758,16 +4851,9 @@ function stamp(code, id) {
     map: out.map === void 0 || null === out.map ? null : JSON.stringify(out.map)
   };
 }
-var SDK_CJS_DEPS = {
-  TESTING_LIBRARY: "@testing-library/dom",
-  ARIA_QUERY: "aria-query"
-};
-function cjsDepIncludes(appRoot, canResolve = (dep) => null !== resolvableChain([dep], appRoot)) {
-  return [SDK_CJS_DEPS.TESTING_LIBRARY, SDK_CJS_DEPS.ARIA_QUERY].filter(canResolve);
-}
 function readPairingToken() {
   const override = process.env[ReticleEnv.PAIRING_TOKEN_DIR];
-  const dir = override !== void 0 && override.length > 0 ? override : (0, import_node_path6.join)((0, import_node_os2.homedir)(), ReticleDir.ROOT);
+  const dir = override !== void 0 && override.length > 0 ? override : (0, import_node_path8.join)((0, import_node_os2.homedir)(), ReticleDir.ROOT);
   return ensurePairingToken(dir);
 }
 var tokenWarned = false;
@@ -4794,6 +4880,9 @@ function connectArgs(options) {
   if (true === options.captureNetworkBodies || "1" === process.env["VITE_RETICLE_CAPTURE_BODIES"]) {
     args["captureNetworkBodies"] = true;
   }
+  if (true === options.exposePresenter || "1" === process.env["VITE_RETICLE_EXPOSE_PRESENTER"]) {
+    args["exposePresenter"] = true;
+  }
   if (true === options.allowNonLocalhost || "1" === process.env["VITE_RETICLE_ALLOW_NON_LOCALHOST"]) {
     args["allowNonLocalhost"] = true;
   }
@@ -4812,6 +4901,20 @@ function findDevModule(root, exists) {
   return null;
 }
 function installedSdk(appRoot, canResolve = (dep) => null !== resolvableChain([dep], appRoot)) {
+  try {
+    const pkgPath = (0, import_node_path8.join)(appRoot, "package.json");
+    if ((0, import_node_fs6.existsSync)(pkgPath)) {
+      const pkg = JSON.parse((0, import_node_fs6.readFileSync)(pkgPath, "utf8"));
+      const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+      if (deps[RETICLE_SENSOR] !== void 0 && deps[RETICLE_PACKAGE2] === void 0) {
+        return { specifier: RETICLE_SENSOR, usesInstall: false };
+      }
+      if (deps[RETICLE_PACKAGE2] !== void 0) {
+        return { specifier: RETICLE_PACKAGE2, usesInstall: true };
+      }
+    }
+  } catch {
+  }
   if (canResolve(RETICLE_PACKAGE2)) return { specifier: RETICLE_PACKAGE2, usesInstall: true };
   if (canResolve(RETICLE_SENSOR)) return { specifier: RETICLE_SENSOR, usesInstall: false };
   return { specifier: RETICLE_PACKAGE2, usesInstall: true };
@@ -4821,9 +4924,11 @@ function connectModuleSource(options, devModule = null) {
   const sdk = installedSdk(options.root ?? process.cwd());
   const named = sdk.usesInstall ? "reticle, install" : "reticle";
   const call = sdk.usesInstall ? "install();\n" : "";
+  const hot = `if (import.meta.hot) reticle.observeHotUpdates(import.meta.hot);
+`;
   const base = `import { ${named} } from '${sdk.specifier}';
 ${call}reticle.connect(${args});
-`;
+${hot}`;
   return null === devModule ? base : `${base}import('${devModule}');
 `;
 }
@@ -4852,10 +4957,10 @@ function reticle(options = {}) {
     const sdkVersion = withToken.sdkVersion ?? sdkPackageVersion(appRoot);
     return { ...withToken, root: appRoot, sdkVersion };
   };
-  const currentConnectSource = () => connectModuleSource(resolveLazy(), root === void 0 ? null : findDevModule(root, import_node_fs5.existsSync));
+  const currentConnectSource = () => connectModuleSource(resolveLazy(), root === void 0 ? null : findDevModule(root, import_node_fs6.existsSync));
   let lastServedConnectSource;
   let connectChanges = 0;
-  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() yourself.`;
+  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.`;
   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="...">.`;
   const checkInjected = () => {
     if (!desktop || !inject || injected) return;
@@ -4869,21 +4974,11 @@ function reticle(options = {}) {
     ...true === options.desktop ? {} : { apply: "serve" },
     enforce: "pre",
     /**
-     * Declare the SDK's CJS runtime deps so Vite pre-bundles them.
+     * Declare the SDK itself and the optimizer cache fingerprint.
      *
-     * `@testing-library/dom` is what `by: role` matching runs on, and it pulls CJS `aria-query`. When
-     * the SDK resolves from OUTSIDE the app's root — a linked package, a pnpm workspace, `npm link`,
-     * a monorepo alias — Vite skips pre-bundling and the named import dies with "does not provide an
-     * export named 'elementRoles'". That takes the WHOLE SDK down before connect() runs, so there is
-     * no session, no Reticle-side error, and only a console SyntaxError naming a package the
-     * developer has never heard of. Measured on the react-admin demo with the SDK aliased to a local
-     * checkout: zero sessions, and it looked like the app was failing to render.
-     *
-     * Declaring them is free when Vite would have found them anyway — but only when they are
-     * actually installed. Naming a package that is not there makes Vite log `Failed to resolve
-     * dependency: …, present in optimizeDeps.include` on every boot, which is a scary line pointing
-     * at Reticle for a problem that does not exist. SvelteKit apps hit exactly that: nothing in that
-     * tree depends on @testing-library/dom.
+     * The browser SDK used to need extra CJS query-engine deps here. It no longer imports that
+     * second accessibility engine, so keeping those names would make Vite pre-bundle packages the
+     * app may not have and blame Reticle for a false `Failed to resolve dependency` warning.
      */
     config(config) {
       const appRoot = config.root ?? process.cwd();
@@ -4965,10 +5060,7 @@ function reticle(options = {}) {
             // 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)
+            installedSdk(appRoot).specifier
           ]
         }
       };
@@ -5031,6 +5123,30 @@ ${code}`;
      */
     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;
+        if (void 0 === port) return;
+        const opts = resolveLazy();
+        const withdraw = announceDevServer({
+          port,
+          pid: process.pid,
+          root: opts.root ?? process.cwd(),
+          url: server.resolvedUrls?.local[0] ?? `http://localhost:${String(port)}/`,
+          ...opts.sdkVersion === void 0 || 0 === opts.sdkVersion.length ? {} : { sdkVersion: opts.sdkVersion },
+          startedAt: Date.now(),
+          ...opts.projectId === void 0 ? {} : { projectId: opts.projectId }
+        });
+        server.httpServer?.once("close", withdraw);
+        process.once("exit", withdraw);
+        process.once("SIGINT", withdraw);
+        process.once("SIGTERM", withdraw);
+      };
+      if (null === server.httpServer?.address() || void 0 === server.httpServer?.address()) {
+        server.httpServer?.once("listening", announce);
+      } else {
+        announce();
+      }
       server.middlewares.use((req, _res, next) => {
         if ((req.url ?? "").split("?")[0] === RETICLE_CONNECT_MODULE) {
           if (currentConnectSource() !== lastServedConnectSource) {
@@ -5082,7 +5198,6 @@ ${code}`;
   RETICLE_DEV_MODULE_CANDIDATES,
   RETICLE_TOKEN_GLOBAL,
   RETICLE_VITE_PLUGIN_NAME,
-  cjsDepIncludes,
   connectChurnWarning,
   connectModuleSource,
   findDevModule,

package/dist/index.d.cts

@@ -84,6 +84,20 @@ export interface ReticleVitePluginOptions {
      * session without editing vite.config.
      */
     captureNetworkBodies?: boolean;
+    /**
+     * Make Reticle's OWN presenter visible to snapshots and queries. CONTRIBUTORS ONLY.
+     *
+     * Reachable here for the same reason `captureNetworkBodies` is: the plugin is the only `connect()`
+     * most apps ever have, so an SDK option the plugin cannot pass is an option that does not exist.
+     *
+     * The presenter is hidden from every tool by design — an agent that can drive Reticle's own
+     * interface can fabricate its own impact report. The cost is that a HUD change is the only kind of
+     * change Reticle cannot be used to check. This is the hatch for that one case, and the app reports
+     * it in its capabilities so a verdict drawn with it open is never mistaken for an ordinary one.
+     *
+     * Also settable as `VITE_RETICLE_EXPOSE_PRESENTER=1`.
+     */
+    exposePresenter?: boolean;
     /**
      * Let Reticle run when the page or the bridge is not on localhost.
      *
@@ -171,6 +185,26 @@ export interface ReticleVitePlugin {
  * plugin never imports, the same way the Svelte compiler and Playwright are handled elsewhere.
  */
 export interface ViteDevServerLike {
+    /**
+     * Vite's own HTTP server, for the port it ACTUALLY bound and the moment it bound it. Optional and
+     * nullable because middleware mode has none — and because a structural stand-in that demands more
+     * than Vite guarantees stops being assignable, which red-builds every typechecked config.
+     */
+    httpServer?: {
+        once(event: string, listener: () => void): unknown;
+        address(): string | {
+            port: number;
+        } | null;
+    } | null;
+    /**
+     * The URLs Vite prints on boot. Read rather than assembled: host, protocol and base are all
+     * configurable, so composing a URL here would be a guess about the one thing the dev server can
+     * simply be asked.
+     */
+    resolvedUrls?: {
+        local: string[];
+        network: string[];
+    } | null;
     middlewares: {
         use(handler: (req: {
             url?: string | undefined;
@@ -191,28 +225,11 @@ interface HtmlTag {
     injectTo: 'body' | 'head-prepend';
 }
 /**
- * Name each CJS dep ONLY in the bare form, and only when the app root can resolve it.
- *
- * This used to try three layouts and emit Vite's nested `a > b > c` form when a hoisted lookup
- * failed. The guard asked the wrong question: it tested NODE resolvability, walking the chain
- * segment by segment, and under pnpm that succeeds exactly where Vite fails. Measured on the
- * sveltekit fixture:
- *
- *   ['@testing-library/dom']                                           -> null
- *   ['@reticlehq/browser', '@testing-library/dom']                     -> null
- *   ['@reticlehq/react', '@reticlehq/browser', '@testing-library/dom'] -> emitted
- *
- * So we emitted the three-segment chain, Vite could not follow it, and the boot warning this
- * function exists to prevent appeared anyway — `Failed to resolve dependency: …, present in
- * optimizeDeps.include`, pointing at Reticle, naming a package the developer has never heard of,
- * and forcing a full re-optimization on every cold start. The comment stated the rule correctly and
- * the code broke it.
- *
- * Dropping the nested form loses nothing that matters: the SDK itself is still pre-bundled, and Vite
- * follows its imports when it does that, so these deps are handled as part of it. Naming them
- * separately was belt-and-braces for a locally-aliased SDK, where the bare form resolves anyway.
+ * Read the daemon's auto-provisioned pairing token (~/.reticle/pairing-token, or the
+ * RETICLE_PAIRING_TOKEN_DIR override) so the served app can present it. Node-side only — a browser
+ * sandbox can't read the file, which is exactly why a rogue localhost app can't forge it. Best-effort:
+ * undefined if the daemon hasn't started yet (the page reloads once it has). Exported for testing.
  */
-export declare function cjsDepIncludes(appRoot: string, canResolve?: (dep: string) => boolean): string[];
 export declare function readPairingToken(): string | undefined;
 /** The body of the connect module — real imports, resolved by Vite when the module is served. */
 /**

package/dist/index.d.ts

@@ -84,6 +84,20 @@ export interface ReticleVitePluginOptions {
      * session without editing vite.config.
      */
     captureNetworkBodies?: boolean;
+    /**
+     * Make Reticle's OWN presenter visible to snapshots and queries. CONTRIBUTORS ONLY.
+     *
+     * Reachable here for the same reason `captureNetworkBodies` is: the plugin is the only `connect()`
+     * most apps ever have, so an SDK option the plugin cannot pass is an option that does not exist.
+     *
+     * The presenter is hidden from every tool by design — an agent that can drive Reticle's own
+     * interface can fabricate its own impact report. The cost is that a HUD change is the only kind of
+     * change Reticle cannot be used to check. This is the hatch for that one case, and the app reports
+     * it in its capabilities so a verdict drawn with it open is never mistaken for an ordinary one.
+     *
+     * Also settable as `VITE_RETICLE_EXPOSE_PRESENTER=1`.
+     */
+    exposePresenter?: boolean;
     /**
      * Let Reticle run when the page or the bridge is not on localhost.
      *
@@ -171,6 +185,26 @@ export interface ReticleVitePlugin {
  * plugin never imports, the same way the Svelte compiler and Playwright are handled elsewhere.
  */
 export interface ViteDevServerLike {
+    /**
+     * Vite's own HTTP server, for the port it ACTUALLY bound and the moment it bound it. Optional and
+     * nullable because middleware mode has none — and because a structural stand-in that demands more
+     * than Vite guarantees stops being assignable, which red-builds every typechecked config.
+     */
+    httpServer?: {
+        once(event: string, listener: () => void): unknown;
+        address(): string | {
+            port: number;
+        } | null;
+    } | null;
+    /**
+     * The URLs Vite prints on boot. Read rather than assembled: host, protocol and base are all
+     * configurable, so composing a URL here would be a guess about the one thing the dev server can
+     * simply be asked.
+     */
+    resolvedUrls?: {
+        local: string[];
+        network: string[];
+    } | null;
     middlewares: {
         use(handler: (req: {
             url?: string | undefined;
@@ -191,28 +225,11 @@ interface HtmlTag {
     injectTo: 'body' | 'head-prepend';
 }
 /**
- * Name each CJS dep ONLY in the bare form, and only when the app root can resolve it.
- *
- * This used to try three layouts and emit Vite's nested `a > b > c` form when a hoisted lookup
- * failed. The guard asked the wrong question: it tested NODE resolvability, walking the chain
- * segment by segment, and under pnpm that succeeds exactly where Vite fails. Measured on the
- * sveltekit fixture:
- *
- *   ['@testing-library/dom']                                           -> null
- *   ['@reticlehq/browser', '@testing-library/dom']                     -> null
- *   ['@reticlehq/react', '@reticlehq/browser', '@testing-library/dom'] -> emitted
- *
- * So we emitted the three-segment chain, Vite could not follow it, and the boot warning this
- * function exists to prevent appeared anyway — `Failed to resolve dependency: …, present in
- * optimizeDeps.include`, pointing at Reticle, naming a package the developer has never heard of,
- * and forcing a full re-optimization on every cold start. The comment stated the rule correctly and
- * the code broke it.
- *
- * Dropping the nested form loses nothing that matters: the SDK itself is still pre-bundled, and Vite
- * follows its imports when it does that, so these deps are handled as part of it. Naming them
- * separately was belt-and-braces for a locally-aliased SDK, where the bare form resolves anyway.
+ * Read the daemon's auto-provisioned pairing token (~/.reticle/pairing-token, or the
+ * RETICLE_PAIRING_TOKEN_DIR override) so the served app can present it. Node-side only — a browser
+ * sandbox can't read the file, which is exactly why a rogue localhost app can't forge it. Best-effort:
+ * undefined if the daemon hasn't started yet (the page reloads once it has). Exported for testing.
  */
-export declare function cjsDepIncludes(appRoot: string, canResolve?: (dep: string) => boolean): string[];
 export declare function readPairingToken(): string | undefined;
 /** The body of the connect module — real imports, resolved by Vite when the module is served. */
 /**

package/dist/index.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { missingTokenWarning } from './missing-token.js';
 import { ensurePairingToken } from './ensure-token.js';
 import { homedir } from 'node:os';
@@ -8,6 +8,7 @@ import reticleSource from '@reticlehq/babel-plugin';
 import { RETICLE_DEFAULT_PORT, RETICLE_RENDER_PREHOOK, bridgeWsUrl, 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 { announceDevServer } from './announce.js';
 import { SVELTE_FILE, stampSvelte } from './svelte-source.js';
 import { resolvableChain, sdkPackageVersion, sdkBuildFingerprint, viteMajor, optimizerOptionsKey, optimizerOptions, } from './installed.js';
 export const RETICLE_VITE_PLUGIN_NAME = 'reticle';
@@ -150,43 +151,6 @@ function stamp(code, id) {
  * sandbox can't read the file, which is exactly why a rogue localhost app can't forge it. Best-effort:
  * undefined if the daemon hasn't started yet (the page reloads once it has). Exported for testing.
  */
-/**
- * CJS packages the browser SDK needs at runtime. Named, because a bare string here is exactly the
- * kind of thing that silently rots when a dependency is renamed.
- */
-const SDK_CJS_DEPS = {
-    TESTING_LIBRARY: '@testing-library/dom',
-    ARIA_QUERY: 'aria-query',
-};
-/**
- * Name each CJS dep ONLY in the bare form, and only when the app root can resolve it.
- *
- * This used to try three layouts and emit Vite's nested `a > b > c` form when a hoisted lookup
- * failed. The guard asked the wrong question: it tested NODE resolvability, walking the chain
- * segment by segment, and under pnpm that succeeds exactly where Vite fails. Measured on the
- * sveltekit fixture:
- *
- *   ['@testing-library/dom']                                           -> null
- *   ['@reticlehq/browser', '@testing-library/dom']                     -> null
- *   ['@reticlehq/react', '@reticlehq/browser', '@testing-library/dom'] -> emitted
- *
- * So we emitted the three-segment chain, Vite could not follow it, and the boot warning this
- * function exists to prevent appeared anyway — `Failed to resolve dependency: …, present in
- * optimizeDeps.include`, pointing at Reticle, naming a package the developer has never heard of,
- * and forcing a full re-optimization on every cold start. The comment stated the rule correctly and
- * the code broke it.
- *
- * Dropping the nested form loses nothing that matters: the SDK itself is still pre-bundled, and Vite
- * follows its imports when it does that, so these deps are handled as part of it. Naming them
- * separately was belt-and-braces for a locally-aliased SDK, where the bare form resolves anyway.
- */
-export function cjsDepIncludes(appRoot, 
-// Injected so the rule can be tested hermetically. Real module resolution is not: under vitest,
-// `createRequire` from a directory that does not exist still resolves packages out of the runner's
-// own graph, so a filesystem-based test of "nothing is reachable here" silently asserts nothing.
-canResolve = (dep) => null !== resolvableChain([dep], appRoot)) {
-    return [SDK_CJS_DEPS.TESTING_LIBRARY, SDK_CJS_DEPS.ARIA_QUERY].filter(canResolve);
-}
 export function readPairingToken() {
     const override = process.env[ReticleEnv.PAIRING_TOKEN_DIR];
     const dir = override !== undefined && override.length > 0 ? override : join(homedir(), ReticleDir.ROOT);
@@ -243,6 +207,10 @@ function connectArgs(options) {
     if (true === options.captureNetworkBodies || '1' === process.env['VITE_RETICLE_CAPTURE_BODIES']) {
         args['captureNetworkBodies'] = true;
     }
+    // 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 ||
@@ -292,6 +260,22 @@ export function findDevModule(root, exists) {
  * missing export.
  */
 export function installedSdk(appRoot, canResolve = (dep) => null !== resolvableChain([dep], appRoot)) {
+    try {
+        const pkgPath = join(appRoot, 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+            if (deps[RETICLE_SENSOR] !== undefined && deps[RETICLE_PACKAGE] === undefined) {
+                return { specifier: RETICLE_SENSOR, usesInstall: false };
+            }
+            if (deps[RETICLE_PACKAGE] !== undefined) {
+                return { specifier: RETICLE_PACKAGE, usesInstall: true };
+            }
+        }
+    }
+    catch {
+        // Ignore read or parse failures when checking dependencies
+    }
     if (canResolve(RETICLE_PACKAGE))
         return { specifier: RETICLE_PACKAGE, usesInstall: true };
     if (canResolve(RETICLE_SENSOR))
@@ -305,7 +289,13 @@ export function connectModuleSource(options, devModule = null) {
     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`;
+    // The only place in a Vite app that can see hot updates. `import.meta.hot` exists per module and
+    // only for modules Vite serves through its own transform; the SDK is a dependency, pre-bundled by
+    // the optimizer, and gets no hot context however it is written — so the channel is handed to it
+    // from here and the SDK owns everything after that (including which events it cares about).
+    // Guarded, because a desktop build has no dev server and therefore no hot context at all.
+    const hot = `if (import.meta.hot) reticle.observeHotUpdates(import.meta.hot);\n`;
+    const base = `import { ${named} } from '${sdk.specifier}';\n${call}reticle.connect(${args});\n${hot}`;
     // 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`;
@@ -390,7 +380,8 @@ export function reticle(options = {}) {
     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() yourself.';
+        '`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.
      *
@@ -422,21 +413,11 @@ export function reticle(options = {}) {
         ...(true === options.desktop ? {} : { apply: 'serve' }),
         enforce: 'pre',
         /**
-         * Declare the SDK's CJS runtime deps so Vite pre-bundles them.
+         * Declare the SDK itself and the optimizer cache fingerprint.
          *
-         * `@testing-library/dom` is what `by: role` matching runs on, and it pulls CJS `aria-query`. When
-         * the SDK resolves from OUTSIDE the app's root — a linked package, a pnpm workspace, `npm link`,
-         * a monorepo alias — Vite skips pre-bundling and the named import dies with "does not provide an
-         * export named 'elementRoles'". That takes the WHOLE SDK down before connect() runs, so there is
-         * no session, no Reticle-side error, and only a console SyntaxError naming a package the
-         * developer has never heard of. Measured on the react-admin demo with the SDK aliased to a local
-         * checkout: zero sessions, and it looked like the app was failing to render.
-         *
-         * Declaring them is free when Vite would have found them anyway — but only when they are
-         * actually installed. Naming a package that is not there makes Vite log `Failed to resolve
-         * dependency: …, present in optimizeDeps.include` on every boot, which is a scary line pointing
-         * at Reticle for a problem that does not exist. SvelteKit apps hit exactly that: nothing in that
-         * tree depends on @testing-library/dom.
+         * The browser SDK used to need extra CJS query-engine deps here. It no longer imports that
+         * second accessibility engine, so keeping those names would make Vite pre-bundle packages the
+         * app may not have and blame Reticle for a false `Failed to resolve dependency` warning.
          */
         config(config) {
             // Everything below asks what the APP has installed, so every lookup is rooted here and never
@@ -517,9 +498,6 @@ export function reticle(options = {}) {
                         // 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),
                     ],
                 },
             };
@@ -600,6 +578,50 @@ export function reticle(options = {}) {
         configureServer(server) {
             if (!inject)
                 return;
+            // Tell `~/.reticle` this dev server exists, the moment it is actually listening.
+            //
+            // This is the one fact nobody outside this process could observe: the plugin is loaded in the
+            // dev server that is RUNNING, not merely present in a config file on disk. Its absence is the
+            // commonest setup failure there is — a plugin added to a config the running server already
+            // read — and until now that failure was indistinguishable from every other one.
+            //
+            // Deliberately reads the port and URL off the server rather than composing them. The port may
+            // be `strictPort: false` and have moved, the host and base are configurable, and every one of
+            // those is something the user can change under us.
+            const announce = () => {
+                const address = server.httpServer?.address();
+                const port = 'object' === typeof address && null !== address && undefined !== address
+                    ? address.port
+                    : undefined;
+                if (undefined === port)
+                    return;
+                const opts = resolveLazy();
+                const withdraw = announceDevServer({
+                    port,
+                    pid: process.pid,
+                    root: opts.root ?? process.cwd(),
+                    url: server.resolvedUrls?.local[0] ?? `http://localhost:${String(port)}/`,
+                    ...(opts.sdkVersion === undefined || 0 === opts.sdkVersion.length
+                        ? {}
+                        : { sdkVersion: opts.sdkVersion }),
+                    startedAt: Date.now(),
+                    ...(opts.projectId === undefined ? {} : { projectId: opts.projectId }),
+                });
+                server.httpServer?.once('close', withdraw);
+                // `close` does not fire on Ctrl-C, which is how a dev server usually dies. The read side
+                // checks liveness anyway, so a missed withdrawal degrades rather than lies — these just
+                // keep the directory tidy in the cases we can catch.
+                process.once('exit', withdraw);
+                process.once('SIGINT', withdraw);
+                process.once('SIGTERM', withdraw);
+            };
+            // Already bound in some setups (middleware mode, a restart), not yet in the common one.
+            if (null === server.httpServer?.address() || undefined === server.httpServer?.address()) {
+                server.httpServer?.once('listening', announce);
+            }
+            else {
+                announce();
+            }
             server.middlewares.use((req, _res, next) => {
                 if ((req.url ?? '').split('?')[0] === RETICLE_CONNECT_MODULE) {
                     if (currentConnectSource() !== lastServedConnectSource) {

package/dist/installed.d.ts

@@ -24,10 +24,8 @@ export declare function isResolvable(specifier: string, from?: string): boolean;
  *
  * A single-segment chain is just the bare specifier, so this also answers "can the app see it
  * itself". Each further segment is resolved from the PREVIOUS package's directory, which is what
- * Vite does with the `>` form and the only way to name a dependency the app root cannot see: under
- * pnpm (and npm's nested layout) `@testing-library/dom` belongs to `@reticlehq/browser`, not to the
- * user's app. Naming it bare made Vite fail to resolve it and force a re-optimization on every cold
- * boot. SvelteKit ships `svelte > clsx` for the same reason.
+ * Vite does with the `>` form and the only way to name a dependency the app root cannot see under
+ * pnpm or npm's nested layout. SvelteKit ships `svelte > clsx` for the same reason.
  */
 export declare function resolvableChain(chain: readonly string[], from: string): string | null;
 /** The installed SDK's package version, for the HELLO's `sdkVersion`. Node-side only. */

package/dist/installed.js

@@ -15,7 +15,7 @@
  * Silently, for every pnpm user, with no error anywhere.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, isAbsolute, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 /** The React kit the host app imports the SDK from. Mirrors the constant in index.ts. */
 const RETICLE_PACKAGE = '@reticlehq/react';
@@ -26,7 +26,8 @@ const MANIFEST_SEARCH_DEPTH = 5;
  * `process.cwd()` default matches how Vite itself defaults the root when the config omits it.
  */
 function requireFromApp(from) {
-    return createRequire(join(from, 'package.json'));
+    const absoluteFrom = isAbsolute(from) ? from : resolve(process.cwd(), from);
+    return createRequire(join(absoluteFrom, 'package.json'));
 }
 /**
  * Whether a package can be resolved from the app. Used to avoid declaring an optimizeDeps entry for
@@ -74,10 +75,8 @@ function packageDirOf(specifier, from) {
  *
  * A single-segment chain is just the bare specifier, so this also answers "can the app see it
  * itself". Each further segment is resolved from the PREVIOUS package's directory, which is what
- * Vite does with the `>` form and the only way to name a dependency the app root cannot see: under
- * pnpm (and npm's nested layout) `@testing-library/dom` belongs to `@reticlehq/browser`, not to the
- * user's app. Naming it bare made Vite fail to resolve it and force a re-optimization on every cold
- * boot. SvelteKit ships `svelte > clsx` for the same reason.
+ * Vite does with the `>` form and the only way to name a dependency the app root cannot see under
+ * pnpm or npm's nested layout. SvelteKit ships `svelte > clsx` for the same reason.
  */
 export function resolvableChain(chain, from) {
     let base = from;

package/dist/state-home.d.ts

@@ -0,0 +1 @@
+export declare function stateHome(env?: NodeJS.ProcessEnv): string;

package/dist/state-home.js

@@ -0,0 +1,19 @@
+/**
+ * Where Reticle keeps machine state — the one answer, for both halves of discovery.
+ *
+ * `RETICLE_STATE_DIR` already exists and already relocates the daemon's pidfiles, logs and discovery
+ * registry (a read-only `$HOME` — sandboxed agent, locked-down Windows profile, container — makes
+ * the default unwritable). The plugin's reader did not honour it: with the variable set, the daemon
+ * wrote its registry to one directory while `discoverDaemonPort` looked in another, so discovery
+ * silently found nothing and every app fell back to the default port. Exactly the class of split
+ * this file exists to prevent — two halves of one mechanism with two ideas of where it lives.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ReticleDir, ReticleEnv } from '@reticlehq/core';
+export function stateHome(env = process.env) {
+    const override = env[ReticleEnv.STATE_DIR];
+    return override !== undefined && override.length > 0
+        ? override
+        : join(homedir(), ReticleDir.ROOT);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "2.11.0",
+  "version": "2.13.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,14 +41,14 @@
   ],
   "dependencies": {
     "@babel/core": "^7.26.0",
-    "@reticlehq/babel-plugin": "2.11.0",
-    "@reticlehq/core": "2.11.0"
+    "@reticlehq/core": "2.13.0",
+    "@reticlehq/babel-plugin": "2.13.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
-    "svelte": "^5.56.8",
+    "svelte": "^5.56.10",
     "vite": "^8",
-    "esbuild": "^0.28.1"
+    "esbuild": "^0.28.2"
   },
   "peerDependencies": {
     "vite": ">=4"