@reticlehq/browser 2.13.1 → 3.1.0

package/dist/registry/store-adapters.js

@@ -1,22 +1,6 @@
-import { nativeWarn } from '../timers/native-console.js';
+import { nativeWarn } from '../timers/console/native-console.js';
 import { markAdapterSource } from './stores.js';
-/**
- * Expose a TanStack Query cache as a Reticle store, keyed by query key.
- *
- * `isStale` / `fetchStatus` / `dataUpdatedAt` are carried deliberately: they are what let an agent
- * assert the stronger property — not merely "the value rendered is X" but "the cache the UI rendered
- * from was actually fresh". A screenshot cannot distinguish a correct number from a correct-looking
- * stale one, and neither can a network log when the request never fired.
- *
- * ```ts
- * registerStore('queries', tanstackQueryStore(queryClient));
- * ```
- */
 export function tanstackQueryStore(client) {
-    // Resolved per call, not captured once. A QueryClient can be rebuilt — React Strict Mode double
-    // effects, a provider remount, HMR — and an adapter holding the old cache would keep answering
-    // from a store the app no longer reads, which is a stale-data bug inside the tool whose job is
-    // catching stale data.
     const store = {
         getState: () => {
             const out = {};
@@ -35,22 +19,9 @@ export function tanstackQueryStore(client) {
         },
         subscribe: (listener) => client.getQueryCache().subscribe(listener),
     };
-    // Registering this adapter claims the CLIENT too, so fiber-tree discovery can tell that the app
-    // already wired this exact QueryClient and must not add a second entry for it.
     markAdapterSource(store, client);
     return store;
 }
-/**
- * Expose a chosen set of Jotai atoms as one Reticle store.
- *
- * The atom map is not an ergonomic shortcut, it is forced by the design: Jotai has no registry of live
- * atoms to enumerate, so "the whole store" is not a thing that exists. Naming the atoms you care about
- * is the only way to snapshot them, and it doubles as a declaration of what matters.
- *
- * ```ts
- * registerStore('app', jotaiStore(getDefaultStore(), { cart: cartAtom, user: userAtom }));
- * ```
- */
 export function jotaiStore(store, atoms) {
     return {
         getState: () => {
@@ -68,10 +39,6 @@ export function jotaiStore(store, atoms) {
         },
     };
 }
-/**
- * Expose an XState actor as a Reticle store. Its `subscribe` returns a subscription OBJECT rather than
- * an unsubscribe function, which is the single reason it does not satisfy `StoreLike` already.
- */
 export function xstateStore(actor) {
     return {
         getState: () => actor.getSnapshot(),
@@ -81,41 +48,18 @@ export function xstateStore(actor) {
         },
     };
 }
-/**
- * Expose a Valtio proxy as a Reticle store. Valtio ships `snapshot`/`subscribe` as free functions
- * rather than methods, so the caller passes them in — importing them here would make every consumer
- * of this file depend on valtio.
- *
- * ```ts
- * import { snapshot, subscribe } from 'valtio/vanilla';
- * registerStore('app', valtioStore(state, snapshot, subscribe));
- * ```
- */
 export function valtioStore(proxy, snapshot, subscribe) {
     return {
         getState: () => snapshot(proxy),
         subscribe: (listener) => subscribe(proxy, listener),
     };
 }
-/**
- * Expose a MobX observable as a Reticle store. `toJS` and `reaction` are passed in for the same
- * dependency reason as valtio above.
- *
- * ```ts
- * import { reaction, toJS } from 'mobx';
- * registerStore('app', mobxStore(store, toJS, reaction));
- * ```
- */
 export function mobxStore(observable, toJS, reaction) {
     return {
         getState: () => toJS(observable),
         subscribe: (listener) => reaction(() => toJS(observable), () => listener()),
     };
 }
-/**
- * The load states a Recoil `Loadable` reports. Named because the projection below branches on them
- * and a bare 'hasValue' in three places is exactly the free string the rules forbid.
- */
 const RecoilLoadState = {
     HAS_VALUE: 'hasValue',
     LOADING: 'loading',
@@ -130,50 +74,13 @@ function projectLoadable(loadable) {
             error: contents instanceof Error ? contents.message : String(contents),
         };
     }
-    // A LOADING loadable's `contents` is the pending promise. Sending it would serialize to `{}` and
-    // read as an empty value — so the value stays null and the status carries the truth.
     if (loadable.state !== RecoilLoadState.HAS_VALUE) {
         return { status: loadable.state, value: null, error: null };
     }
     return { status: loadable.state, value: loadable.contents, error: null };
 }
-/**
- * Expose a chosen set of Recoil atoms as one Reticle store.
- *
- * Three things about Recoil's API shape this adapter is built around, none of them optional:
- *
- *  - **The atom map is forced, not an ergonomic choice.** Recoil has no enumerable registry of live
- *    atoms, so "the whole store" is not a thing that exists. Naming the atoms is the only way to
- *    snapshot them, and it doubles as a declaration of what matters — the same reason `jotaiStore`
- *    takes one.
- *  - **`.state`/`.contents`, never `.getValue()`.** On a pending async selector `getValue()` THROWS
- *    the pending promise, and on a failed one it throws the error. Either would take down the whole
- *    state read over one slow atom — so a loading atom reports `status: 'loading'` with a null value
- *    rather than silently becoming an empty object or an exception.
- *  - **One subscription, not one per atom.** Recoil exposes no per-atom subscription outside React
- *    (`jotaiStore` gets `store.sub(atom, …)`; there is no equivalent here). The transaction stream is
- *    the only public change signal, so the caller passes it in — the same "the library ships free
- *    functions, so hand them over" shape as `valtioStore` and `mobxStore`.
- *
- * Wire it from a bridge component, which is where `useRecoilTransactionObserver_UNSTABLE` lives:
- *
- * ```tsx
- * const latest = useRef(snapshot_UNSTABLE());
- * const listeners = useRef(new Set<() => void>()).current;
- * useRecoilTransactionObserver_UNSTABLE(({ snapshot }) => {
- *   latest.current = snapshot;
- *   for (const l of listeners) l();
- * });
- * registerStore('recoil', recoilStore({ cart: cartAtom }, () => latest.current, (l) => {
- *   listeners.add(l);
- *   return () => listeners.delete(l);
- * }));
- * ```
- */
 export function recoilStore(atoms, snapshot, subscribe) {
     return {
-        // Resolved per call, not captured once: a Recoil snapshot is IMMUTABLE, so an adapter holding
-        // one would keep answering from the transaction it was built in and never see another write.
         getState: () => {
             const current = snapshot();
             const out = {};
@@ -192,25 +99,6 @@ function stopSubscription(handle) {
     }
     handle.unsubscribe();
 }
-/**
- * Expose a Svelte store as a Reticle store.
- *
- * Structurally unlike every other adapter in this file: they all wrap something that can be PULLED
- * (`getState`, `getSnapshot`, `snapshot(proxy)`, `toJS`). A Svelte store has no pull side at all —
- * `{ subscribe }` is the entire contract. What makes a pull possible anyway is the part of that
- * contract which says `subscribe` must call back **immediately and synchronously** with the current
- * value: subscribe, catch the value, unsubscribe, return it. That is precisely how `svelte/store`'s
- * own `get()` is implemented, so it is a blessed read rather than a trick.
- *
- * Doing it that way is what keeps this adapter free of the `dispose` the obvious implementation
- * needs. Caching the latest value would mean holding a permanent subscription, which means a
- * teardown the other five adapters don't have, which means a leak the moment a caller forgets it.
- * A transient subscription per read owns nothing and leaks nothing.
- *
- * ```ts
- * registerStore('cart', svelteStore(cartStore));
- * ```
- */
 export function svelteStore(readable, warn = nativeWarn) {
     let warnedAboutLazyStore = false;
     return {
@@ -221,10 +109,6 @@ export function svelteStore(readable, warn = nativeWarn) {
                 value = next;
                 called = true;
             }));
-            // A store that did NOT call back synchronously (an RxJS Observable that is not a
-            // BehaviorSubject, a hand-rolled store that breaks the contract) leaves `value` undefined —
-            // indistinguishable from a store legitimately holding undefined. Reading empty when the answer
-            // is "unknown" is the false green this project exists to prevent, so say it once, out loud.
             if (!called && !warnedAboutLazyStore) {
                 warnedAboutLazyStore = true;
                 warn('[reticle] a store passed to svelteStore did not call its subscriber synchronously, so ' +
@@ -235,17 +119,6 @@ export function svelteStore(readable, warn = nativeWarn) {
             return value;
         },
         subscribe: (listener) => {
-            // Swallow whatever arrives DURING the subscribe call. Forwarding it would emit a STATE_CHANGE
-            // at REGISTRATION time for a change that never happened — a diff of nothing that shows up in
-            // causal summaries and that a {kind:'state'} predicate could satisfy without the app doing
-            // anything at all.
-            //
-            // The window is what makes this correct, rather than "swallow the first callback whenever it
-            // arrives". A store that does NOT call back synchronously (an RxJS Observable that is not a
-            // BehaviorSubject — the exact store `getState` warns about) has no registration callback to
-            // drop, so counting callbacks ate its first REAL change: no STATE_CHANGE, and a
-            // {kind:'state'} assertion with nothing to match. A silently missed state change is the false
-            // green this project exists to prevent, so the rule is positional, not ordinal.
             let inSubscribeCall = true;
             const handle = readable.subscribe(() => {
                 if (!inSubscribeCall)
@@ -256,49 +129,13 @@ export function svelteStore(readable, warn = nativeWarn) {
         },
     };
 }
-/** Pinia `$subscribe` options. `sync` and `detached` are library option values, not free strings. */
 const PINIA_SUBSCRIBE_OPTIONS = { detached: true, flush: 'sync' };
-/**
- * Expose a Pinia store as a Reticle store. `$state` / `$subscribe` are close to `{getState,
- * subscribe}` but not close enough for `registerStore`'s duck-type, which is the whole reason a Vue
- * app currently connects and then reports no state at all.
- *
- * Both `$subscribe` options are load-bearing:
- *
- *  - **`detached`** keeps the subscription alive past the component that happened to register the
- *    store. Without it Pinia tears the listener down on unmount, so a store registered from inside a
- *    component goes permanently silent after the first route change — readable, but never again
- *    emitting a STATE_CHANGE, which reads exactly like an app that stopped changing.
- *  - **`flush: 'sync'`** puts the notification inside the action's attribution window. The default
- *    (`'post'`) defers it past the Vue update tick, and a state change that lands after the window
- *    closed is no longer linked to the click that caused it in the causal summary.
- *
- * `$state` carries state, not getters — a Pinia getter is derived, so asserting on the state it
- * derives from is the stronger assertion anyway.
- *
- * ```ts
- * registerStore('cart', piniaStore(useCartStore()));
- * ```
- */
 export function piniaStore(store) {
     return {
-        // `$state` is a live reactive proxy, so this reads through to the current value rather than
-        // snapshotting at registration. The transport serializer walks it like any object and guards
-        // each key, which is what keeps a throwing reactive trap from costing the whole read.
         getState: () => store.$state,
         subscribe: (listener) => store.$subscribe(() => listener(), { ...PINIA_SUBSCRIBE_OPTIONS }),
     };
 }
-/**
- * Build a store whose value is PUSHED in rather than pulled — for state that has no object to read.
- *
- * React Context and `useState`/`useReducer` keep their value inside the fiber tree; there is no store
- * instance and no subscription point outside React, so no adapter over a public API is possible. The
- * only way in is to invert the direction: the component holding the value tells Reticle when it
- * changes. `@reticlehq/react`'s `useReticleStore` hook is the ergonomic wrapper over this.
- *
- * Returns the store plus the `push` that updates it, so the caller owns the write side.
- */
 export function pushStore(initial) {
     let current = initial;
     const listeners = new Set();

package/dist/registry/{adapters.d.ts → stores/adapters.d.ts}

@@ -1,4 +1,3 @@
-/** Framework adapter registry — enriches elements with component identity + source. */
 export interface ComponentSource {
     file: string;
     line: number;
@@ -11,20 +10,11 @@ export interface ComponentInfo {
 export interface ReticleAdapter {
     name: string;
     identify: (el: Element) => ComponentInfo | null;
-    /** Best-effort: read a component's hook state for a DOM element. */
     readState?: (el: Element) => unknown;
-    /** Best-effort: does the element declare framework enter/leave handlers synthetic hover may not fire? */
     hasHoverHandlers?: (el: Element) => boolean;
 }
-/** Called by @reticlehq/react (and future adapters) to register themselves. */
 export declare function registerAdapter(adapter: ReticleAdapter): void;
-/** First adapter that can identify the element wins. */
 export declare function identifyComponent(el: Element): ComponentInfo | null;
-/** First adapter that returns non-undefined component state for the element wins. */
 export declare function readComponentState(el: Element): unknown;
-/**
- * True if any installed adapter reports framework enter/leave hover handlers on the element.
- * No-op-safe: returns false when no adapter is installed or none implements the probe.
- */
 export declare function elementHasHoverHandlers(el: Element): boolean;
 export declare function adapterNames(): string[];

package/dist/registry/{adapters.js → stores/adapters.js}

@@ -1,14 +1,9 @@
-/** Framework adapter registry — enriches elements with component identity + source. */
-// Persist on a global so the registry survives HMR module re-evaluation (otherwise the
-// adapter silently drops after a hot reload and source mapping degrades). See feedback #7.
 const globalStore = globalThis;
 const adapters = (globalStore.__reticleAdapters ??= []);
-/** Called by @reticlehq/react (and future adapters) to register themselves. */
 export function registerAdapter(adapter) {
     if (!adapters.some((a) => a.name === adapter.name))
         adapters.push(adapter);
 }
-/** First adapter that can identify the element wins. */
 export function identifyComponent(el) {
     for (const adapter of adapters) {
         const info = adapter.identify(el);
@@ -17,7 +12,6 @@ export function identifyComponent(el) {
     }
     return null;
 }
-/** First adapter that returns non-undefined component state for the element wins. */
 export function readComponentState(el) {
     for (const adapter of adapters) {
         if (adapter.readState === undefined)
@@ -28,10 +22,6 @@ export function readComponentState(el) {
     }
     return undefined;
 }
-/**
- * True if any installed adapter reports framework enter/leave hover handlers on the element.
- * No-op-safe: returns false when no adapter is installed or none implements the probe.
- */
 export function elementHasHoverHandlers(el) {
     for (const adapter of adapters) {
         if (adapter.hasHoverHandlers === undefined)

package/dist/registry/stores.d.ts

@@ -1,54 +1,21 @@
 import { type TruncationReport } from '../security/serialization.js';
-/** Store registry — lets the agent pull live framework/store state on demand. */
 export type StoreGetter = () => unknown;
-/** A store's subscribe method (Zustand/Redux shape): register a listener, get back an unsubscribe. */
 export type StoreSubscribe = (listener: () => void) => () => void;
-/** Notified when a SUBSCRIBABLE store is registered, so a late registration is still observed. */
 export type StoreRegisteredListener = (entry: [string, StoreGetter, StoreSubscribe]) => void;
-/**
- * Observe FUTURE subscribable-store registrations. The SDK installs its observers during connect, but
- * apps call registerStore afterwards — so enumerating once at install time subscribes to nothing and
- * STATE_CHANGE never fires. Observers use this to pick up stores registered after they installed.
- */
 export declare function onStoreRegistered(listener: StoreRegisteredListener): () => void;
-/** A Zustand/Redux-shaped store: exposes both current state and a subscribe. */
 export interface StoreLike {
     getState: () => unknown;
     subscribe: StoreSubscribe;
 }
-/**
- * App calls this once per store. PREFER passing the store itself — `registerStore('app', useApp)` —
- * which wires `getState` AND `subscribe`, so every mutation emits a STATE_CHANGE path diff automatically
- * (the before→after the causal summary reports). Passing a bare getter still works for back-compat, but
- * leaves the store on pull-only reads: no change events, and an empty `stateDiffs` in every act summary.
- */
 export declare function registerStore(name: string, source: StoreGetter | StoreLike, subscribe?: StoreSubscribe): void;
 export declare function unregisterStore(name: string): void;
 export declare function storeNames(): string[];
-/** Registered stores that exposed a subscribe method, as [name, getter, subscribe] tuples. */
 export declare function subscribableStores(): Array<[string, StoreGetter, StoreSubscribe]>;
-/**
- * Read one store (by name) or all of them WITHOUT transport sanitization. For scoped reads that
- * select a sub-tree first, so a deep/large path (e.g. row 250 of a 500-row array) isn't truncated
- * before selection. Each getter is isolated: a throw becomes an error object.
- */
 export declare function readStoresRaw(only?: string): Record<string, unknown>;
-/** Read one store (by name) or all of them, each capped for transport. */
 export declare function readStores(only?: string): Record<string, unknown>;
-/**
- * As `readStores`, plus which stores came back INCOMPLETE.
- *
- * The whole-store read is the one path where the transport caps could silently hand back a fraction
- * of a large store — ~142 of 1,000 entities, with the remainder simply absent. A caller comparing
- * that against expected data reads it as "the app lost the rest", which is a false failure; a caller
- * asserting something is absent reads it as proof, which is a false green. Neither is recoverable
- * from the payload, so the fact of truncation travels beside it.
- */
 export declare function readStoresWithTruncation(only?: string): {
     stores: Record<string, unknown>;
     truncation?: Record<string, TruncationReport>;
 };
-/** Called by an adapter to record what it was built from. See `sourceOwner`. */
 export declare function markAdapterSource(store: object, source: object): void;
-/** The name this store source is registered under, or undefined if nothing has claimed it. */
 export declare function sourceOwner(value: unknown): string | undefined;

package/dist/registry/stores.js

@@ -1,25 +1,16 @@
 import { RETICLE_RENDERS_STORE } from '@reticlehq/core';
-import { nativeWarn } from '../timers/native-console.js';
+import { nativeWarn } from '../timers/console/native-console.js';
 import { sanitizeWithReport } from '../security/serialization.js';
 const globalStore = globalThis;
 const stores = (globalStore.__reticleStores ??= new Map());
-// Parallel map: stores that also provided a subscribe method, for automatic STATE_CHANGE diffs.
 const subscribers = (globalStore.__reticleStoreSubs ??= new Map());
 const registrationListeners = (globalStore.__reticleStoreListeners ??=
     new Set());
-/**
- * Observe FUTURE subscribable-store registrations. The SDK installs its observers during connect, but
- * apps call registerStore afterwards — so enumerating once at install time subscribes to nothing and
- * STATE_CHANGE never fires. Observers use this to pick up stores registered after they installed.
- */
 export function onStoreRegistered(listener) {
     registrationListeners.add(listener);
     return () => registrationListeners.delete(listener);
 }
 function isStoreLike(source) {
-    // Zustand's `create` returns a CALLABLE hook that also carries getState/subscribe, so a store can be
-    // typeof 'function' as well as 'object'. What distinguishes it from a plain getter is those two members
-    // — never the typeof. (Checking only for 'object' left every Zustand app on pull-only reads.)
     if (null === source)
         return false;
     if (typeof source !== 'object' && typeof source !== 'function')
@@ -27,12 +18,6 @@ function isStoreLike(source) {
     const candidate = source;
     return 'function' === typeof candidate.getState && 'function' === typeof candidate.subscribe;
 }
-/**
- * App calls this once per store. PREFER passing the store itself — `registerStore('app', useApp)` —
- * which wires `getState` AND `subscribe`, so every mutation emits a STATE_CHANGE path diff automatically
- * (the before→after the causal summary reports). Passing a bare getter still works for back-compat, but
- * leaves the store on pull-only reads: no change events, and an empty `stateDiffs` in every act summary.
- */
 export function registerStore(name, source, subscribe) {
     claimSource(name, source);
     if (isStoreLike(source)) {
@@ -57,11 +42,6 @@ export function registerStore(name, source, subscribe) {
         notifyRegistered(name, source, subscribe);
         return;
     }
-    // Readable but SILENT: reticle_state can read this store on demand, yet nothing will ever emit a
-    // STATE_CHANGE for it, so causal summaries show no state diff and a {kind:"state"} predicate can
-    // never observe it changing. That reads exactly like "the app did not change anything" — a false
-    // negative with no error attached. Say so once, at registration, where the developer can fix it by
-    // passing the store itself (or a subscribe function) instead of a bare getter.
     warnSilentStoreOnce(name);
 }
 function notifyRegistered(name, getter, subscribe) {
@@ -70,7 +50,6 @@ function notifyRegistered(name, getter, subscribe) {
             listener([name, getter, subscribe]);
         }
         catch {
-            // a broken observer must never break the app's registerStore call
         }
     }
 }
@@ -81,7 +60,6 @@ export function unregisterStore(name) {
 export function storeNames() {
     return [...stores.keys()];
 }
-/** Registered stores that exposed a subscribe method, as [name, getter, subscribe] tuples. */
 export function subscribableStores() {
     const out = [];
     for (const [name, subscribe] of subscribers) {
@@ -91,11 +69,6 @@ export function subscribableStores() {
     }
     return out;
 }
-/**
- * Read one store (by name) or all of them WITHOUT transport sanitization. For scoped reads that
- * select a sub-tree first, so a deep/large path (e.g. row 250 of a 500-row array) isn't truncated
- * before selection. Each getter is isolated: a throw becomes an error object.
- */
 export function readStoresRaw(only) {
     const out = {};
     for (const [name, getter] of stores) {
@@ -110,19 +83,9 @@ export function readStoresRaw(only) {
     }
     return out;
 }
-/** Read one store (by name) or all of them, each capped for transport. */
 export function readStores(only) {
     return readStoresWithTruncation(only).stores;
 }
-/**
- * As `readStores`, plus which stores came back INCOMPLETE.
- *
- * The whole-store read is the one path where the transport caps could silently hand back a fraction
- * of a large store — ~142 of 1,000 entities, with the remainder simply absent. A caller comparing
- * that against expected data reads it as "the app lost the rest", which is a false failure; a caller
- * asserting something is absent reads it as proof, which is a false green. Neither is recoverable
- * from the payload, so the fact of truncation travels beside it.
- */
 export function readStoresWithTruncation(only) {
     const stores = {};
     const truncation = {};
@@ -134,13 +97,7 @@ export function readStoresWithTruncation(only) {
     }
     return Object.keys(truncation).length > 0 ? { stores, truncation } : { stores };
 }
-/** Stores already warned about — a warning that repeats on every HMR cycle or remount becomes noise. */
 const warnedSilent = new Set();
-/**
- * Reticle's OWN read-only stores. `@reticlehq/react` registers a render-stats getter that the app
- * developer never wrote and cannot change, so warning about it would be Reticle telling the user to fix
- * Reticle — the same self-contradiction as a tool description naming a tool the profile does not expose.
- */
 const RETICLE_OWNED_STORES = new Set([RETICLE_RENDERS_STORE]);
 function warnSilentStoreOnce(name) {
     if (RETICLE_OWNED_STORES.has(name) || warnedSilent.has(name))
@@ -150,23 +107,8 @@ function warnSilentStoreOnce(name) {
         `changes are invisible: no STATE_CHANGE events, no state diffs in causal summaries, and a state ` +
         `predicate will never see it update. Pass the store object (or a subscribe callback) to fix.`);
 }
-/**
- * Who owns a given store SOURCE — the object the app (or an adapter) was built from.
- *
- * Registration is keyed by name, which cannot answer "is this same store already readable?". The
- * question matters because the React adapter discovers stores from the fiber tree, and an app that
- * has already registered the very same store by hand must not get a second entry for it under a
- * second name. Comparing the READ VALUE cannot answer it either: `tanstackQueryStore` builds a fresh
- * snapshot object on every `getState`, so identity never matches. Measured on bench-app, which
- * registers `queries` itself and got an auto-discovered `query` beside it — one cache, listed twice,
- * in every state read.
- *
- * A WeakMap so nothing here keeps an app's store alive.
- */
 const sourceOwners = new WeakMap();
-/** Adapter instance → the object it wraps, so registering an adapter also claims its source. */
 const adapterSources = new WeakMap();
-/** Called by an adapter to record what it was built from. See `sourceOwner`. */
 export function markAdapterSource(store, source) {
     adapterSources.set(store, source);
 }
@@ -178,7 +120,6 @@ function claimSource(name, source) {
     if (wrapped !== undefined)
         sourceOwners.set(wrapped, name);
 }
-/** The name this store source is registered under, or undefined if nothing has claimed it. */
 export function sourceOwner(value) {
     if (null === value || ('object' !== typeof value && 'function' !== typeof value))
         return undefined;

package/dist/reticle-presenter-helpers.d.ts

@@ -1,18 +1,5 @@
 import { PresenterMode } from '@reticlehq/core';
-/** Coerce an unknown arg to a string, falling back to `fallback` (default empty) when it isn't one. */
 export declare function str(value: unknown, fallback?: string): string;
-/** A short human label for a ref ("button \"Save\"") for the presenter HUD. */
 export declare function refLabel(refId: string): string;
-/**
- * Classify a browser command into the presenter intent the human watcher sees. Exhaustive
- * over the ReticleCommand names that actually reach the browser. CLOCK/NARRATE are control/meta
- * (neither a page read nor an act) -> IDLE so they don't paint a misleading chip. NARRATE never
- * reaches #presentBefore anyway (it returns early in #handleCommand) and must not clear the mode.
- */
 export declare function modeForCommand(commandName: string): PresenterMode;
-/**
- * Human-legible status for a read command — now WITH the target (which testid/value/ref/store), so
- * the watcher sees "Finding [testid=row-3700]" instead of a meaningless repeating "Finding an
- * element". Falls back to the bare verb when no target is in the args.
- */
 export declare function presentStatus(commandName: string, args?: Record<string, unknown>): string;

package/dist/reticle-presenter-helpers.js

@@ -1,11 +1,13 @@
 import { ReticleCommand, PresenterMode, QueryBy } from '@reticlehq/core';
-import { refs } from './dom/refs.js';
+import { refs } from './dom/addressing/refs.js';
 import { describe } from './dom/a11y.js';
-/** Coerce an unknown arg to a string, falling back to `fallback` (default empty) when it isn't one. */
 export function str(value, fallback = '') {
     return 'string' === typeof value ? value : fallback;
 }
-/** A short human label for a ref ("button \"Save\"") for the presenter HUD. */
+function text(value) {
+    const asString = str(value);
+    return '' === asString ? undefined : asString;
+}
 export function refLabel(refId) {
     const el = refs.resolve(refId);
     if (!(el instanceof Element))
@@ -13,12 +15,6 @@ export function refLabel(refId) {
     const d = describe(el);
     return d.name.length > 0 ? `${d.role} "${d.name}"` : `${d.role} (${refId})`;
 }
-/**
- * Classify a browser command into the presenter intent the human watcher sees. Exhaustive
- * over the ReticleCommand names that actually reach the browser. CLOCK/NARRATE are control/meta
- * (neither a page read nor an act) -> IDLE so they don't paint a misleading chip. NARRATE never
- * reaches #presentBefore anyway (it returns early in #handleCommand) and must not clear the mode.
- */
 export function modeForCommand(commandName) {
     switch (commandName) {
         case ReticleCommand.ACT:
@@ -36,11 +32,6 @@ export function modeForCommand(commandName) {
             return PresenterMode.IDLE;
     }
 }
-/**
- * Human-legible status for a read command — now WITH the target (which testid/value/ref/store), so
- * the watcher sees "Finding [testid=row-3700]" instead of a meaningless repeating "Finding an
- * element". Falls back to the bare verb when no target is in the args.
- */
 export function presentStatus(commandName, args = {}) {
     switch (commandName) {
         case ReticleCommand.SNAPSHOT:
@@ -52,13 +43,13 @@ export function presentStatus(commandName, args = {}) {
             return target !== undefined ? `Finding ${target}` : 'Finding an element';
         }
         case ReticleCommand.INSPECT: {
-            const ref = str(args['ref']);
+            const ref = text(args['ref']);
             return ref !== undefined ? `Inspecting ${refLabel(ref)}` : 'Inspecting an element';
         }
         case ReticleCommand.ANIMATIONS:
             return 'Reading animations';
         case ReticleCommand.STATE_READ: {
-            const store = str(args['store']);
+            const store = text(args['store']);
             return store !== undefined ? `Reading state: ${store}` : 'Reading state';
         }
         case ReticleCommand.CAPABILITIES:
@@ -67,13 +58,12 @@ export function presentStatus(commandName, args = {}) {
             return commandName;
     }
 }
-/** Compact "what we're looking for" from a query's args (testid/value/name/role/text/label). */
 function queryTarget(q) {
-    const testid = str(q['testid']) ?? (QueryBy.TESTID === str(q['by']) ? str(q['value']) : undefined);
+    const testid = text(q['testid']) ?? (QueryBy.TESTID === str(q['by']) ? text(q['value']) : undefined);
     if (testid !== undefined)
         return `[testid=${testid}]`;
-    const name = str(q['name']);
-    const value = str(q['value']) ?? str(q['text']) ?? str(q['label']) ?? str(q['role']);
+    const name = text(q['name']);
+    const value = text(q['value']) ?? text(q['text']) ?? text(q['label']) ?? text(q['role']);
     if (value !== undefined)
         return name !== undefined ? `"${value}" (${name})` : `"${value}"`;
     return name !== undefined ? `"${name}"` : undefined;

package/dist/reticle-singleton.d.ts

@@ -0,0 +1,2 @@
+import { Reticle } from './reticle.js';
+export declare const reticle: Reticle;

package/dist/reticle-singleton.js

@@ -0,0 +1,3 @@
+import { Reticle } from './reticle.js';
+const globalStore = globalThis;
+export const reticle = (globalStore.__reticleInstance ??= new Reticle());