@reticlehq/vite-plugin 3.4.0 → 3.6.0

package/dist/connect-args.js

@@ -6,6 +6,7 @@
  * of the plugin's options the PAGE needs to be told about.
  */
 import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
+const PRESENT_OPTION = 'present';
 /** Build the `reticle.connect` argument literal — only includes keys the user set. */
 export function connectArgs(options) {
     const args = {};
@@ -18,6 +19,9 @@ export function connectArgs(options) {
         args['projectId'] = options.projectId;
     if (options.token !== undefined)
         args['token'] = options.token;
+    // Only the opt-out is needed; the SDK defaults to showing its presenter.
+    if (false === options.present)
+        args[PRESENT_OPTION] = false;
     // Passed as connect ARGUMENTS, not as a `define`. A define substitutes a bare identifier in the
     // source it transforms; the SDK reads these as `globalThis[NAME]`, a dynamic lookup no define can
     // ever reach — so defining them looked right, shipped, and did nothing. Baking them into the
@@ -67,5 +71,8 @@ export function connectArgs(options) {
         '1' === process.env['VITE_RETICLE_ALLOW_NON_LOCALHOST']) {
         args['allowNonLocalhost'] = true;
     }
+    if (options.testIdAttribute !== undefined && options.testIdAttribute.length > 0) {
+        args['testIdAttribute'] = options.testIdAttribute;
+    }
     return Object.keys(args).length > 0 ? JSON.stringify(args) : '';
 }

package/dist/discover-port.d.ts

@@ -34,4 +34,4 @@ export interface DaemonPortChoice {
  */
 export declare function chooseDaemonPort(sources: DaemonPortSources): DaemonPortChoice;
 /** {@link chooseDaemonPort} over the real registry and the real `.reticle.json` above `cwd`. */
-export declare function resolveDaemonPort(explicit: number | undefined, projectId: string | undefined, cwd: string): DaemonPortChoice;
+export declare function resolveDaemonPort(explicit: number | undefined, projectId: string | undefined, cwd: string, env?: NodeJS.ProcessEnv): DaemonPortChoice;

package/dist/discover-port.js

@@ -7,10 +7,11 @@
  */
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, } from '@reticlehq/core';
+import { daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, ReticleEnv, } from '@reticlehq/core';
 import { stateHome } from './state-home.js';
 import { readConfiguredPort } from './project-id.js';
 import { RETICLE_VITE_PLUGIN_NAME } from './plugin-name.js';
+const MAX_TCP_PORT = 65_535;
 /** process.kill(pid, 0) throws iff the process is gone — the same liveness probe the daemon uses. */
 function isAlive(pid) {
     try {
@@ -77,10 +78,18 @@ export function chooseDaemonPort(sources) {
     };
 }
 /** {@link chooseDaemonPort} over the real registry and the real `.reticle.json` above `cwd`. */
-export function resolveDaemonPort(explicit, projectId, cwd) {
+export function resolveDaemonPort(explicit, projectId, cwd, env = process.env) {
+    // The CLI treats RETICLE_PORT as an override across projects. A page must follow the same
+    // daemon even when an older instance is still registered or init wrote a different port.
+    const raw = env[ReticleEnv.PORT];
+    if (raw !== undefined && /^\d+$/.test(raw)) {
+        const port = Number(raw);
+        if (0 < port && port <= MAX_TCP_PORT)
+            return { port, warning: undefined };
+    }
     const configured = readConfiguredPort(cwd);
     return chooseDaemonPort({
-        discovered: discoverDaemonPort(projectId, stateHome(), isAlive, configured),
+        discovered: discoverDaemonPort(projectId, stateHome(env), isAlive, configured),
         configured,
         explicit,
     });

package/dist/index.cjs

@@ -4243,6 +4243,9 @@ function bridgeWsUrl(port = RETICLE_DEFAULT_PORT, host = RETICLE_CLIENT_HOST) {
   return `ws://${host}:${String(port)}${RETICLE_WS_PATH}`;
 }
 var ReticleEnv = {
+  /** "0"/"false"/"off" turns off telemetry and every optional outbound call; DO_NOT_TRACK too. */
+  TELEMETRY: "RETICLE_TELEMETRY",
+  DO_NOT_TRACK: "DO_NOT_TRACK",
   /** Shared-secret the browser SDK must present in HELLO; absent ⇒ loopback-trust only. */
   TOKEN: "RETICLE_TOKEN",
   /** Bridge bind host. Defaults to loopback; setting anything else is opt-in remote exposure. */
@@ -4257,6 +4260,8 @@ var ReticleEnv = {
   STATE_DIR: "RETICLE_STATE_DIR",
   /** Attach to an already-running browser over CDP instead of launching one. */
   CDP_URL: "RETICLE_CDP_URL",
+  /** The Chromium executable to launch, in place of Playwright's own build or an installed Chrome. */
+  CHROMIUM_PATH: "RETICLE_CHROMIUM_PATH",
   /** Max simultaneous leased headless contexts in the browser pool (resource cap). */
   MAX_CONTEXTS: "RETICLE_MAX_CONTEXTS",
   /**
@@ -4437,8 +4442,9 @@ var ReticleDir = {
   /**
    * the user's own record of what Reticle has done for them — .reticle/impact.json.
    *
-   * Local only, never uploaded, and deliberately NOT part of telemetry: telemetry answers questions
-   * about the product; this answers the user's question about their own work.
+   * NOT telemetry: telemetry answers questions about the product; this answers the user's question
+   * about their own work. A linked project's copy syncs to the user's own dashboard (the sync cycle's
+   * `impact` kind); the machine-wide copy in `~/.reticle` never leaves the machine.
    */
   IMPACT_FILE: "impact.json",
   /** what changes were SUPPOSED to make true —.reticle/intent.json (git-checked, reviewed) */
@@ -4453,14 +4459,6 @@ var ReticleDir = {
    * classified nor ignored.
    */
   INTENT_SUBDIR: "intent",
-  /**
-   * what a drive types into a field, keyed by the field's label —.reticle/fill-values.json.
-   *
-   * Git-checked on purpose. A generated value is paid for once and then belongs to the project: the
-   * next drive reuses it for free, a replay sends exactly what the recording sent, and a human who
-   * dislikes one can edit the file rather than argue with a model.
-   */
-  FILL_VALUES_FILE: "fill-values.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). */
@@ -4475,6 +4473,8 @@ var ReticleDir = {
    * in three separate files, so the guard could not see it and nobody was ever asked.
    */
   FEEDBACK_SUBDIR: "feedback",
+  /** Every Harness drive plan, and how each journey went — .reticle/plans/<when>-<planId>.json. */
+  PLANS_SUBDIR: "plans",
   /** durable causal journal —.reticle/sessions/<id>/{events,actions}.jsonl (the substrate). */
   SESSIONS_SUBDIR: "sessions",
   /** append-only event ledger inside a session dir (one ReticleEvent per line). */
@@ -4498,6 +4498,12 @@ var ReticleDir = {
   FLAKE_FILE: "flake.json",
   /** The app-wide coverage ledger — see server features/exhaust/ledger.ts. */
   COVERAGE_FILE: "coverage.json",
+  /** Human review marks (HUD notes), pending and resolved — see server portal/session/human. */
+  NOTES_FILE: "notes.json",
+  /** The user's latest request, as the agent relayed it. Local: it is the user's own words. */
+  REQUEST_FILE: "request.json",
+  PLATFORM_MOMENTS_FILE: "platform-moments.json",
+  // moments already said, so each is said once
   /**
    * 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
@@ -4557,6 +4563,9 @@ var RETICLE_ROOT_GLOBAL = "__RETICLE_ROOT__";
 var RETICLE_SDK_VERSION_GLOBAL = "__RETICLE_SDK_VERSION__";
 var RETICLE_IGNORE_MARKER = "@reticle-ignore";
 
+// ../../../core/dist/identity/testid-attribute.js
+var TESTID_ATTR_PATTERN = /^[a-zA-Z_][\w-]*$/;
+
 // ../../../core/dist/identity/project-id.js
 var PROJECT_ID_HASH_LENGTH = 8;
 var FALLBACK_PROJECT_BASE = "app";
@@ -4707,6 +4716,16 @@ function readConfiguredPort(startDir, readFile = readFileOrThrow) {
     tcpPort
   );
 }
+function readConfiguredTestIdAttribute(startDir, readFile = readFileOrThrow) {
+  return readNearestField(
+    startDir,
+    RETICLE_CONFIG_BASENAME,
+    "testIdAttribute",
+    readFile,
+    MAX_CONFIG_SEARCH_DEPTH,
+    (value) => "string" === typeof value && TESTID_ATTR_PATTERN.test(value) ? value : void 0
+  );
+}
 function resolveProjectId(explicit, cwd, readPkgName = readNearestPackageName, readConfiguredId = readConfiguredProjectId) {
   if (explicit !== void 0 && explicit.length > 0) return explicit;
   const configured = readConfiguredId(cwd);
@@ -4730,6 +4749,7 @@ function stateHome(env = process.env) {
 var RETICLE_VITE_PLUGIN_NAME = "reticle";
 
 // src/discover-port.ts
+var MAX_TCP_PORT2 = 65535;
 function isAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -4770,10 +4790,15 @@ function chooseDaemonPort(sources) {
     warning: explicit === configured ? void 0 : portConflictWarning(explicit, configured, port)
   };
 }
-function resolveDaemonPort(explicit, projectId, cwd) {
+function resolveDaemonPort(explicit, projectId, cwd, env = process.env) {
+  const raw = env[ReticleEnv.PORT];
+  if (raw !== void 0 && /^\d+$/.test(raw)) {
+    const port = Number(raw);
+    if (0 < port && port <= MAX_TCP_PORT2) return { port, warning: void 0 };
+  }
   const configured = readConfiguredPort(cwd);
   return chooseDaemonPort({
-    discovered: discoverDaemonPort(projectId, stateHome(), isAlive, configured),
+    discovered: discoverDaemonPort(projectId, stateHome(env), isAlive, configured),
     configured,
     explicit
   });
@@ -5224,6 +5249,7 @@ export function resolveMarkAnchor() {
 `;
 
 // src/connect-args.ts
+var PRESENT_OPTION = "present";
 function connectArgs(options) {
   const args = {};
   const port = options.port ?? RETICLE_DEFAULT_PORT;
@@ -5231,6 +5257,7 @@ function connectArgs(options) {
   if (options.session !== void 0) args["session"] = options.session;
   if (options.projectId !== void 0) args["projectId"] = options.projectId;
   if (options.token !== void 0) args["token"] = options.token;
+  if (false === options.present) args[PRESENT_OPTION] = false;
   if (options.root !== void 0 && options.root.length > 0) args["root"] = options.root;
   if (options.sdkVersion !== void 0 && options.sdkVersion.length > 0) {
     args["sdkVersion"] = options.sdkVersion;
@@ -5254,6 +5281,9 @@ function connectArgs(options) {
   if (true === options.allowNonLocalhost || "1" === process.env["VITE_RETICLE_ALLOW_NON_LOCALHOST"]) {
     args["allowNonLocalhost"] = true;
   }
+  if (options.testIdAttribute !== void 0 && options.testIdAttribute.length > 0) {
+    args["testIdAttribute"] = options.testIdAttribute;
+  }
   return Object.keys(args).length > 0 ? JSON.stringify(args) : "";
 }
 
@@ -5439,7 +5469,13 @@ function reticle(options = {}) {
     const withToken = token !== void 0 ? { ...withPort, token } : withPort;
     const appRoot = withToken.root ?? root ?? process.cwd();
     const sdkVersion = withToken.sdkVersion ?? sdkPackageVersion(appRoot);
-    return { ...withToken, root: appRoot, sdkVersion };
+    const testIdAttribute = withToken.testIdAttribute ?? readConfiguredTestIdAttribute(appRoot);
+    return {
+      ...withToken,
+      root: appRoot,
+      sdkVersion,
+      ...testIdAttribute === void 0 ? {} : { testIdAttribute }
+    };
   };
   const currentConnectSource = () => connectModuleSource(resolveLazy(), root === void 0 ? null : findDevModule(root, import_node_fs6.existsSync));
   let lastServedConnectSource;

package/dist/index.d.cts

@@ -64,6 +64,8 @@ export interface ReticleVitePluginOptions {
     projectId?: string;
     /** Auth token forwarded to connect when the bridge requires one. */
     token?: string;
+    /** Show Reticle's presenter. Defaults to true; set false to keep the agent connection without the panel. */
+    present?: boolean;
     /** Stamp data-reticle-source for React 19 source mapping. Default true (harmless on React <=18). */
     sourceMapping?: boolean;
     /** Auto-inject the dev-gated reticle.connect call. Default true. */
@@ -109,6 +111,8 @@ export interface ReticleVitePluginOptions {
      * vite.config.
      */
     networkBodyMaxChars?: number;
+    /** Attribute this app marks controls with instead of `data-testid`. Defaults to `.reticle.json`'s `testIdAttribute`. */
+    testIdAttribute?: string;
     /**
      * Retain a FAILED request's response body even with `captureNetworkBodies` off. Default true.
      *

package/dist/index.d.ts

@@ -64,6 +64,8 @@ export interface ReticleVitePluginOptions {
     projectId?: string;
     /** Auth token forwarded to connect when the bridge requires one. */
     token?: string;
+    /** Show Reticle's presenter. Defaults to true; set false to keep the agent connection without the panel. */
+    present?: boolean;
     /** Stamp data-reticle-source for React 19 source mapping. Default true (harmless on React <=18). */
     sourceMapping?: boolean;
     /** Auto-inject the dev-gated reticle.connect call. Default true. */
@@ -109,6 +111,8 @@ export interface ReticleVitePluginOptions {
      * vite.config.
      */
     networkBodyMaxChars?: number;
+    /** Attribute this app marks controls with instead of `data-testid`. Defaults to `.reticle.json`'s `testIdAttribute`. */
+    testIdAttribute?: string;
     /**
      * Retain a FAILED request's response body even with `captureNetworkBodies` off. Default true.
      *

package/dist/index.js

@@ -4,7 +4,7 @@ import { ensurePairingToken } from './token/ensure-token.js';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { RETICLE_RENDER_PREHOOK, ReticleDir, ReticleEnv, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, } from '@reticlehq/core';
-import { resolveProjectId } from './project-id.js';
+import { readConfiguredTestIdAttribute, resolveProjectId } from './project-id.js';
 import { resolveDaemonPort } from './discover-port.js';
 import { announceDevServer } from './announce.js';
 import { stampSvelte } from './svelte-source.js';
@@ -327,7 +327,15 @@ export function reticle(options = {}) {
         // tree, and they travel in the generated connect call rather than through a `define`.
         const appRoot = withToken.root ?? root ?? process.cwd();
         const sdkVersion = withToken.sdkVersion ?? sdkPackageVersion(appRoot);
-        return { ...withToken, root: appRoot, sdkVersion };
+        // `.reticle.json` is where a project names its test-id attribute, read per call like the port so
+        // an edit takes effect on the next page load; the option, when given, wins.
+        const testIdAttribute = withToken.testIdAttribute ?? readConfiguredTestIdAttribute(appRoot);
+        return {
+            ...withToken,
+            root: appRoot,
+            sdkVersion,
+            ...(testIdAttribute === undefined ? {} : { testIdAttribute }),
+        };
     };
     /**
      * The connect module's source as it would be served RIGHT NOW. Recomputed rather than cached: the

package/dist/project-id.d.ts

@@ -34,6 +34,13 @@ export declare function readConfiguredProjectId(startDir: string, readFile?: Rea
  * project's daemon — and the bridge refused it.
  */
 export declare function readConfiguredPort(startDir: string, readFile?: ReadFile): number | undefined;
+/**
+ * Read `testIdAttribute` from the nearest `.reticle.json`, or undefined: the attribute this project
+ * marks controls with when it is not `data-testid` (`data-test-subj`, `data-cy`, ...). The page needs
+ * it to resolve `{ testid }`, and the file is the one place the CLI, the daemon and the plugin
+ * already agree on, so the plugin forwards it to `connect()` rather than asking for it twice.
+ */
+export declare function readConfiguredTestIdAttribute(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.

package/dist/project-id.js

@@ -9,7 +9,7 @@
 import { createHash } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import { readFileSync } from 'node:fs';
-import { PROJECT_ID_HASH_LENGTH, projectIdFrom } from '@reticlehq/core';
+import { PROJECT_ID_HASH_LENGTH, TESTID_ATTR_PATTERN, 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';
@@ -99,6 +99,15 @@ export function readConfiguredProjectId(startDir, readFile = readFileOrThrow) {
 export function readConfiguredPort(startDir, readFile = readFileOrThrow) {
     return readNearestField(startDir, RETICLE_CONFIG_BASENAME, 'port', readFile, MAX_CONFIG_SEARCH_DEPTH, tcpPort);
 }
+/**
+ * Read `testIdAttribute` from the nearest `.reticle.json`, or undefined: the attribute this project
+ * marks controls with when it is not `data-testid` (`data-test-subj`, `data-cy`, ...). The page needs
+ * it to resolve `{ testid }`, and the file is the one place the CLI, the daemon and the plugin
+ * already agree on, so the plugin forwards it to `connect()` rather than asking for it twice.
+ */
+export function readConfiguredTestIdAttribute(startDir, readFile = readFileOrThrow) {
+    return readNearestField(startDir, RETICLE_CONFIG_BASENAME, 'testIdAttribute', readFile, MAX_CONFIG_SEARCH_DEPTH, (value) => ('string' === typeof value && TESTID_ATTR_PATTERN.test(value) ? value : 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "3.4.0",
+  "version": "3.6.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,15 +41,15 @@
   ],
   "dependencies": {
     "@babel/core": "^7.26.0",
-    "@reticlehq/babel-plugin": "3.4.0",
-    "@reticlehq/core": "3.4.0"
+    "@reticlehq/babel-plugin": "3.6.0",
+    "@reticlehq/core": "3.6.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
     "esbuild": "^0.28.2",
     "svelte": "^5.57.1",
     "vite": "^8",
-    "@reticlehq/react": "3.4.0"
+    "@reticlehq/react": "3.6.0"
   },
   "peerDependencies": {
     "vite": ">=4"