@reticlehq/vite-plugin 3.1.0 → 3.3.0

package/README.md

@@ -58,4 +58,19 @@ reticle({
 
 `desktop: true` makes the plugin apply to `vite build` as well and calls `connect()` with `allowInProduction`, because a packaged desktop renderer is a production build with no dev server. That means an instrumented production bundle, which a web app must never ship. Keep it behind your own dev-only build target.
 
+### Opting one file out of source stamping
+
+A file whose **first non-empty line** is a comment carrying `@reticle-ignore` is not stamped, and its elements will have no `file:line`:
+
+```tsx
+// @reticle-ignore
+export function Generated() { … }
+```
+
+`/* @reticle-ignore */` works the same way, and a `.svelte` component uses `<!-- @reticle-ignore -->` because it has no line for a `//` before its markup.
+
+Whole file, first line, on purpose. The reasons to opt out are file-shaped — a generated component, a snapshot test the stamp would break — and a marker that worked from line 40 would be a marker nobody can find. `include`/`exclude` globs still exist for whole directories; this is for the one file whose reason sits with the file.
+
+It is not silent. The plugin reports each opted-out file once, by name, in the dev-server output, so an opt-out is something a reader sees rather than something they discover months later from a pointer that never resolves.
+
 Apache-2.0.

package/dist/connect-args.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `reticle.connect` argument literal the plugin bakes into the generated connect call.
+ *
+ * Split out of index.ts, which sits six lines under its 1000-line cap on main -- this option could
+ * not be added inline. Cohesive on its own terms: one function, whose whole job is deciding which
+ * of the plugin's options the PAGE needs to be told about.
+ */
+import type { ReticleVitePluginOptions } from './index.js';
+/** Build the `reticle.connect` argument literal — only includes keys the user set. */
+export declare function connectArgs(options: ReticleVitePluginOptions): string;

package/dist/connect-args.js

@@ -0,0 +1,71 @@
+/**
+ * The `reticle.connect` argument literal the plugin bakes into the generated connect call.
+ *
+ * Split out of index.ts, which sits six lines under its 1000-line cap on main -- this option could
+ * not be added inline. Cohesive on its own terms: one function, whose whole job is deciding which
+ * of the plugin's options the PAGE needs to be told about.
+ */
+import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
+/** Build the `reticle.connect` argument literal — only includes keys the user set. */
+export function connectArgs(options) {
+    const args = {};
+    const port = options.port ?? RETICLE_DEFAULT_PORT;
+    if (port !== RETICLE_DEFAULT_PORT)
+        args['url'] = bridgeWsUrl(port);
+    if (options.session !== undefined)
+        args['session'] = options.session;
+    if (options.projectId !== undefined)
+        args['projectId'] = options.projectId;
+    if (options.token !== undefined)
+        args['token'] = options.token;
+    // 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
+    // generated connect call is a literal in generated source: no bundler subtleties, works the same
+    // in dev and in a desktop build.
+    if (options.root !== undefined && options.root.length > 0)
+        args['root'] = options.root;
+    if (options.sdkVersion !== undefined && options.sdkVersion.length > 0) {
+        args['sdkVersion'] = options.sdkVersion;
+    }
+    // A desktop renderer is a production build by construction; without this the SDK's prod backstop
+    // refuses to connect and the app is silently uninstrumented.
+    if (true === options.desktop)
+        args['allowInProduction'] = true;
+    // Env wins nothing — it only turns the flag ON, so a config that never set it can still be
+    // switched on for one debugging session without editing vite.config and restarting the mental
+    // model with it.
+    if (true === options.captureNetworkBodies || '1' === process.env['VITE_RETICLE_CAPTURE_BODIES']) {
+        args['captureNetworkBodies'] = true;
+    }
+    // Only the OPT-OUT is announced, never the default. The daemon reads absence as "unknown", so
+    // sending `true` here would say nothing it does not already assume — while sending `false` is the
+    // one fact a red verdict needs to stop prescribing a plugin this project has deliberately muted.
+    if (false === options.sourceMapping)
+        args['sourceMapping'] = false;
+    // The one option that defaults ON, so the env var and the config flag both DISABLE rather than
+    // enable. Emitted only when switched off; the default stays implicit in the SDK.
+    if (false === options.captureErrorBodies || '1' === process.env['VITE_RETICLE_NO_ERROR_BODIES']) {
+        args['captureErrorBodies'] = false;
+    }
+    // Same shape, same reason -- except this one carries a VALUE, so the env var is parsed rather
+    // than tested for '1'. A non-numeric env var is ignored rather than fatal: it must not take down
+    // an app's dev server, and the SDK clamps whatever does arrive.
+    const envBodyChars = Number(process.env['VITE_RETICLE_BODY_MAX_CHARS']);
+    const bodyChars = options.networkBodyMaxChars ??
+        (Number.isFinite(envBodyChars) && envBodyChars > 0 ? envBodyChars : undefined);
+    if (bodyChars !== undefined) {
+        args['networkBodyMaxChars'] = bodyChars;
+    }
+    // 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 ||
+        '1' === process.env['VITE_RETICLE_ALLOW_NON_LOCALHOST']) {
+        args['allowNonLocalhost'] = true;
+    }
+    return Object.keys(args).length > 0 ? JSON.stringify(args) : '';
+}

package/dist/disabled-browser-stub.d.ts

@@ -0,0 +1,3 @@
+export declare const RETICLE_DISABLED_STUB = "\0reticle-disabled-stub";
+export declare const isReticleDisabledWebBuild: (desktop: boolean, command: string | undefined) => boolean;
+export declare const RETICLE_DISABLED_STUB_CODE = "\nexport class Reticle {\n  connect() {}\n  signal() {}\n  state() {}\n  renderCommit() {}\n  describe() {}\n  endSession() {}\n  observeHotUpdates() {}\n  disconnect() {}\n\n  get connected() {\n    return false;\n  }\n}\n\nexport const reticle = new Reticle();\n\nexport const SESSION_AUTO = 'auto';\n\nexport function setIgnoreSelectors() {}\n\nexport function registerAdapter() {}\nexport function identifyComponent() {\n  return null;\n}\nexport function readComponentState() {\n  return undefined;\n}\nexport function elementHasHoverHandlers() {\n  return false;\n}\nexport function adapterNames() {\n  return [];\n}\n\nexport function registerStore() {}\nexport function unregisterStore() {}\nexport function storeNames() {\n  return [];\n}\nexport function readStores() {\n  return {};\n}\nexport function readStoresWithTruncation() {\n  return { stores: {} };\n}\nexport function sourceOwner() {\n  return undefined;\n}\nexport function markAdapterSource() {}\n\nexport function tanstackQueryStore() {\n  return undefined;\n}\nexport function jotaiStore() {\n  return undefined;\n}\nexport function xstateStore() {\n  return undefined;\n}\nexport function valtioStore() {\n  return undefined;\n}\nexport function mobxStore() {\n  return undefined;\n}\nexport function recoilStore() {\n  return undefined;\n}\nexport function svelteStore() {\n  return undefined;\n}\nexport function piniaStore() {\n  return undefined;\n}\nexport function pushStore() {\n  return undefined;\n}\n\nexport function registerCapabilities() {}\nexport function getCapabilities() {\n  return {};\n}\nexport function hasCapabilities() {\n  return false;\n}\nexport function setCapabilitiesListener() {}\n\nexport function createReticleEmitter() {\n  return {\n    signal() {},\n    state() {},\n  };\n}\n\nexport function commitAndSignal() {}\nexport function registerReticleDomain() {}\n\nexport function buildSnapshot() {\n  return {};\n}\n\nexport function inspectChart() {\n  return {};\n}\nexport function canvasChartData() {\n  return {};\n}\n\nexport function matchQuery() {\n  return false;\n}\nexport function runQuery() {\n  return undefined;\n}\n\nexport function executeAction() {\n  return undefined;\n}\nexport function executeSequence() {\n  return undefined;\n}\n\nexport function describe() {\n  return undefined;\n}\nexport function getRole() {\n  return undefined;\n}\nexport function getAccessibleName() {\n  return undefined;\n}\nexport function getStates() {\n  return {};\n}\nexport function isVisible() {\n  return false;\n}\n\nexport class RefRegistry {\n  get size() {\n    return 0;\n  }\n\n  markEdited() {}\n\n  mintedBeforeLastEdit() {\n    return false;\n  }\n\n  refFor() {\n    return undefined;\n  }\n\n  resolve() {\n    return null;\n  }\n}\n\nexport const refs = new RefRegistry();\n\nexport class Annotator {\n  constructor() {}\n\n  get active() {\n    return false;\n  }\n\n  get markCount() {\n    return 0;\n  }\n\n  mount() {}\n  unmount() {}\n}\n\nexport function installAnnotator() {}\n\nexport function resolveMarkAnchor() {\n  return undefined;\n}\n";

package/dist/disabled-browser-stub.js

@@ -0,0 +1,185 @@
+export const RETICLE_DISABLED_STUB = '\0reticle-disabled-stub';
+export const isReticleDisabledWebBuild = (desktop, command) => !desktop && 'build' === command;
+export const RETICLE_DISABLED_STUB_CODE = `
+export class Reticle {
+  connect() {}
+  signal() {}
+  state() {}
+  renderCommit() {}
+  describe() {}
+  endSession() {}
+  observeHotUpdates() {}
+  disconnect() {}
+
+  get connected() {
+    return false;
+  }
+}
+
+export const reticle = new Reticle();
+
+export const SESSION_AUTO = 'auto';
+
+export function setIgnoreSelectors() {}
+
+export function registerAdapter() {}
+export function identifyComponent() {
+  return null;
+}
+export function readComponentState() {
+  return undefined;
+}
+export function elementHasHoverHandlers() {
+  return false;
+}
+export function adapterNames() {
+  return [];
+}
+
+export function registerStore() {}
+export function unregisterStore() {}
+export function storeNames() {
+  return [];
+}
+export function readStores() {
+  return {};
+}
+export function readStoresWithTruncation() {
+  return { stores: {} };
+}
+export function sourceOwner() {
+  return undefined;
+}
+export function markAdapterSource() {}
+
+export function tanstackQueryStore() {
+  return undefined;
+}
+export function jotaiStore() {
+  return undefined;
+}
+export function xstateStore() {
+  return undefined;
+}
+export function valtioStore() {
+  return undefined;
+}
+export function mobxStore() {
+  return undefined;
+}
+export function recoilStore() {
+  return undefined;
+}
+export function svelteStore() {
+  return undefined;
+}
+export function piniaStore() {
+  return undefined;
+}
+export function pushStore() {
+  return undefined;
+}
+
+export function registerCapabilities() {}
+export function getCapabilities() {
+  return {};
+}
+export function hasCapabilities() {
+  return false;
+}
+export function setCapabilitiesListener() {}
+
+export function createReticleEmitter() {
+  return {
+    signal() {},
+    state() {},
+  };
+}
+
+export function commitAndSignal() {}
+export function registerReticleDomain() {}
+
+export function buildSnapshot() {
+  return {};
+}
+
+export function inspectChart() {
+  return {};
+}
+export function canvasChartData() {
+  return {};
+}
+
+export function matchQuery() {
+  return false;
+}
+export function runQuery() {
+  return undefined;
+}
+
+export function executeAction() {
+  return undefined;
+}
+export function executeSequence() {
+  return undefined;
+}
+
+export function describe() {
+  return undefined;
+}
+export function getRole() {
+  return undefined;
+}
+export function getAccessibleName() {
+  return undefined;
+}
+export function getStates() {
+  return {};
+}
+export function isVisible() {
+  return false;
+}
+
+export class RefRegistry {
+  get size() {
+    return 0;
+  }
+
+  markEdited() {}
+
+  mintedBeforeLastEdit() {
+    return false;
+  }
+
+  refFor() {
+    return undefined;
+  }
+
+  resolve() {
+    return null;
+  }
+}
+
+export const refs = new RefRegistry();
+
+export class Annotator {
+  constructor() {}
+
+  get active() {
+    return false;
+  }
+
+  get markCount() {
+    return 0;
+  }
+
+  mount() {}
+  unmount() {}
+}
+
+export function installAnnotator() {}
+
+export function resolveMarkAnchor() {
+  return undefined;
+}
+`;