@reticlehq/vite-plugin 2.12.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

@@ -44,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) {
@@ -78,8 +78,8 @@ 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
@@ -243,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",
   /**
@@ -4453,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");
@@ -4490,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);
@@ -4500,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 {
@@ -4512,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 {
@@ -4521,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";
@@ -4552,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;
@@ -4606,25 +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) {
-  const absoluteFrom = (0, import_node_path5.isAbsolute)(from) ? from : (0, import_node_path5.resolve)(process.cwd(), from);
-  return (0, import_node_module2.createRequire)((0, import_node_path5.join)(absoluteFrom, "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;
     }
@@ -4649,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;
     }
@@ -4667,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";
@@ -4753,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"] },
@@ -4769,7 +4853,7 @@ function stamp(code, id) {
 }
 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;
@@ -4796,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;
   }
@@ -4815,9 +4902,9 @@ function findDevModule(root, exists) {
 }
 function installedSdk(appRoot, canResolve = (dep) => null !== resolvableChain([dep], appRoot)) {
   try {
-    const pkgPath = (0, import_node_path6.join)(appRoot, "package.json");
-    if ((0, import_node_fs5.existsSync)(pkgPath)) {
-      const pkg = JSON.parse((0, import_node_fs5.readFileSync)(pkgPath, "utf8"));
+    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 };
@@ -4870,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;
@@ -5036,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) {

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;

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;

package/dist/index.js

@@ -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';
@@ -206,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 ||
@@ -375,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.
      *
@@ -572,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/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.12.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.12.0",
-    "@reticlehq/core": "2.12.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"