@reticlehq/browser 2.2.1 → 2.4.0

package/dist/presenter/presenter.js

@@ -421,4 +421,3 @@ export class Presenter {
             spawnRipple(this.#root, cx, cy);
     }
 }
-//# sourceMappingURL=presenter.js.map

package/dist/recorder/recorder-styles.d.ts

@@ -9,4 +9,3 @@ export declare const BTN_CSS: string;
 export declare const NAME_CSS: string;
 export declare const STATUS_CSS: string;
 export declare const MENU_CSS: string;
-//# sourceMappingURL=recorder-styles.d.ts.map

package/dist/recorder/recorder-styles.js

@@ -42,4 +42,3 @@ export const NAME_CSS = [
 ].join(';');
 export const STATUS_CSS = ['opacity:.75', 'margin-left:4px'].join(';');
 export const MENU_CSS = ['display:flex', 'gap:6px', 'align-items:center', 'flex-wrap:wrap'].join(';');
-//# sourceMappingURL=recorder-styles.js.map

package/dist/recorder/recorder.d.ts

@@ -57,4 +57,3 @@ export declare function compileRecording(name: string, steps: FlowStep[], annota
 /** Install the floating recorder toolbar. Default off; gated by the host (reticle.ts recorder flag). */
 export declare function installRecorder(deps: RecorderDeps): RecorderHandle;
 export {};
-//# sourceMappingURL=recorder.d.ts.map

package/dist/recorder/recorder.js

@@ -451,4 +451,3 @@ class Recorder {
 export function installRecorder(deps) {
     return new Recorder(deps);
 }
-//# sourceMappingURL=recorder.js.map

package/dist/registry/adapters.d.ts

@@ -28,4 +28,3 @@ export declare function readComponentState(el: Element): unknown;
  */
 export declare function elementHasHoverHandlers(el: Element): boolean;
 export declare function adapterNames(): string[];
-//# sourceMappingURL=adapters.d.ts.map

package/dist/registry/adapters.js

@@ -44,4 +44,3 @@ export function elementHasHoverHandlers(el) {
 export function adapterNames() {
     return adapters.map((a) => a.name);
 }
-//# sourceMappingURL=adapters.js.map

package/dist/registry/capabilities.d.ts

@@ -16,10 +16,11 @@ export interface CapabilitiesInput {
     stores?: string[];
     flows?: CapabilityFlow[];
 }
+/** Set by the SDK at connect. Idempotent; the last connect wins. */
+export declare function setCapabilitiesListener(cb: (() => void) | undefined): void;
 /** Called by the host app via reticle.describe. Merges (idempotent), never replaces wholesale. */
 export declare function registerCapabilities(input: CapabilitiesInput): void;
 /** Snapshot copy of the registered capabilities (defensive — never hand out the live arrays). */
 export declare function getCapabilities(): Capabilities;
 /** Whether the app has advertised any capabilities (used in the HELLO flag). */
 export declare function hasCapabilities(): boolean;
-//# sourceMappingURL=capabilities.d.ts.map

package/dist/registry/capabilities.js

@@ -12,6 +12,21 @@ function mergeUnique(into, add) {
         if (!into.includes(v))
             into.push(v);
 }
+/**
+ * Notified whenever capabilities change, so the SDK can re-announce them to the bridge.
+ *
+ * `hasCapabilities` rides in the HELLO, which goes out at connect() — and registering deliberately
+ * happens AFTER connect, because `registerStore` needs a live SDK to subscribe through. Without a
+ * notification, an app that declared its whole testable surface still appeared to the agent as
+ * having none, permanently. The hook lives HERE rather than on `reticle.describe` because the
+ * documented entry point is this bare function; only wiring `describe` would have fixed the path
+ * almost nobody uses.
+ */
+let onChanged;
+/** Set by the SDK at connect. Idempotent; the last connect wins. */
+export function setCapabilitiesListener(cb) {
+    onChanged = cb;
+}
 /** Called by the host app via reticle.describe. Merges (idempotent), never replaces wholesale. */
 export function registerCapabilities(input) {
     mergeUnique(capabilities.testids, input.testids);
@@ -28,6 +43,7 @@ export function registerCapabilities(input) {
             }
         }
     }
+    onChanged?.();
 }
 /** Snapshot copy of the registered capabilities (defensive — never hand out the live arrays). */
 export function getCapabilities() {
@@ -45,4 +61,3 @@ export function hasCapabilities() {
         capabilities.stores.length > 0 ||
         capabilities.flows.length > 0);
 }
-//# sourceMappingURL=capabilities.js.map

package/dist/registry/commit-and-signal.d.ts

@@ -6,4 +6,3 @@
  */
 import type { ReticleEmitter } from './emitter.js';
 export declare function commitAndSignal<T>(emitter: ReticleEmitter, mutate: () => T, name: string, data?: Record<string, unknown>): T;
-//# sourceMappingURL=commit-and-signal.d.ts.map

package/dist/registry/commit-and-signal.js

@@ -9,4 +9,3 @@ export function commitAndSignal(emitter, mutate, name, data) {
     emitter.signal(name, data);
     return result;
 }
-//# sourceMappingURL=commit-and-signal.js.map

package/dist/registry/domains.d.ts

@@ -12,4 +12,3 @@ export interface ReticleDomain {
     stores?: readonly string[];
 }
 export declare function registerReticleDomain(domain: ReticleDomain): void;
-//# sourceMappingURL=domains.d.ts.map

package/dist/registry/domains.js

@@ -16,4 +16,3 @@ export function registerReticleDomain(domain) {
         input.stores = [...domain.stores];
     registerCapabilities(input);
 }
-//# sourceMappingURL=domains.js.map

package/dist/registry/emitter.d.ts

@@ -25,4 +25,3 @@ export interface CreateReticleEmitterOptions {
  * made at module load — before `reticle.connect` — starts working the moment Reticle connects.
  */
 export declare function createReticleEmitter(options?: CreateReticleEmitterOptions): ReticleEmitter;
-//# sourceMappingURL=emitter.d.ts.map

package/dist/registry/emitter.js

@@ -24,4 +24,3 @@ export function createReticleEmitter(options = {}) {
         },
     };
 }
-//# sourceMappingURL=emitter.js.map

package/dist/registry/store-adapters.d.ts

@@ -1,4 +1,4 @@
-import type { StoreLike } from './stores.js';
+import type { StoreLike, StoreSubscribe } from './stores.js';
 /**
  * Adapters that give non-`{getState, subscribe}` state libraries the shape `registerStore` wants.
  *
@@ -60,10 +60,19 @@ export interface QuerySnapshot {
  * ```
  */
 export declare function tanstackQueryStore(client: QueryClientLike): StoreLike;
-/** The minimum of a Jotai vanilla store this adapter touches. */
-interface JotaiStoreLike {
-    get: (atom: object) => unknown;
-    sub: (atom: object, listener: () => void) => () => void;
+/**
+ * The minimum of a Jotai vanilla store this adapter touches, generic in the ATOM type.
+ *
+ * `atom: object` was rejected by TypeScript for a real store and the reason is contravariance, not
+ * pedantry: Jotai's `get` is `<Value>(atom: Atom<Value>) => Value`, and a function that requires an
+ * `Atom` cannot stand in for one that accepts any `object`. So `jotaiStore(createStore(), …)` did
+ * not compile — the adapter was advertised, shipped, and unusable from TypeScript without a cast,
+ * which the shape-matched fake in the sibling test could never reveal because the fake was written
+ * to the same belief the adapter was.
+ */
+interface JotaiStoreLike<A> {
+    get: (atom: A) => unknown;
+    sub: (atom: A, listener: () => void) => () => void;
 }
 /**
  * Expose a chosen set of Jotai atoms as one Reticle store.
@@ -76,7 +85,7 @@ interface JotaiStoreLike {
  * registerStore('app', jotaiStore(getDefaultStore(), { cart: cartAtom, user: userAtom }));
  * ```
  */
-export declare function jotaiStore(store: JotaiStoreLike, atoms: Record<string, object>): StoreLike;
+export declare function jotaiStore<A>(store: JotaiStoreLike<A>, atoms: Record<string, A>): StoreLike;
 /** The minimum of an XState actor this adapter touches. */
 interface ActorLike {
     getSnapshot: () => unknown;
@@ -110,6 +119,132 @@ export declare function valtioStore<T extends object>(proxy: T, snapshot: (p: T)
  * ```
  */
 export declare function mobxStore<T>(observable: T, toJS: (value: T) => unknown, reaction: (track: () => unknown, effect: () => void) => () => void): StoreLike;
+/** The minimum of a Recoil `Loadable` this adapter touches. */
+interface RecoilLoadableLike {
+    /** 'hasValue' | 'loading' | 'hasError'. Widened to string: it arrives from outside this package. */
+    state: string;
+    /** The value, the pending promise, or the thrown error — which one depends on `state`. */
+    contents: unknown;
+}
+/** The minimum of a Recoil `Snapshot` this adapter touches, generic in the ATOM type. */
+interface RecoilSnapshotLike<A> {
+    getLoadable: (atom: A) => RecoilLoadableLike;
+}
+/** How one Recoil atom is projected: the value never travels without the load state beside it. */
+export interface RecoilAtomSnapshot {
+    status: string;
+    value: unknown;
+    error: string | 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 declare function recoilStore<A>(atoms: Record<string, A>, snapshot: () => RecoilSnapshotLike<A>, subscribe: StoreSubscribe): StoreLike;
+/**
+ * The minimum of a Svelte store this adapter touches.
+ *
+ * `subscribe` may return either the unsubscribe function or an object carrying one — the store
+ * contract permits both, and an RxJS-shaped source returns the object form.
+ */
+interface SvelteReadable {
+    subscribe: (run: (value: unknown) => void) => (() => void) | {
+        unsubscribe: () => void;
+    };
+}
+/**
+ * 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 declare function svelteStore(readable: SvelteReadable, warn?: (message: string) => void): StoreLike;
+/**
+ * The minimum of a Pinia store this adapter touches.
+ *
+ * Two things here look over-specified and are not, both found by compiling against the real library
+ * rather than against a fake written to the same belief as the adapter:
+ *
+ *  - **`$state: object`, not `Record<string, unknown>`.** A Pinia store's `$state` is a concrete
+ *    object type with named keys and no index signature, and TypeScript rejects those for a
+ *    `Record<string, unknown>` parameter. `piniaStore(useCartStore())` did not compile — the same
+ *    shape of failure as the Jotai contravariance note above, and equally invisible to a fake.
+ *  - **`flush` as the literal union**, not `string`. The option object is checked contravariantly, so
+ *    a widened `string` here makes the real `$subscribe` unassignable to this shape and the whole
+ *    store stops matching.
+ */
+interface PiniaStoreLike {
+    $state: object;
+    $subscribe: (callback: (mutation: unknown, state: unknown) => void, options?: {
+        detached?: boolean;
+        flush?: 'pre' | 'post' | 'sync';
+    }) => () => void;
+}
+/**
+ * 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 declare function piniaStore(store: PiniaStoreLike): StoreLike;
 /**
  * Build a store whose value is PUSHED in rather than pulled — for state that has no object to read.
  *
@@ -125,4 +260,3 @@ export declare function pushStore(initial: unknown): {
     push: (value: unknown) => void;
 };
 export {};
-//# sourceMappingURL=store-adapters.d.ts.map

package/dist/registry/store-adapters.js

@@ -1,3 +1,4 @@
+import { nativeWarn } from '../timers/native-console.js';
 /**
  * Expose a TanStack Query cache as a Reticle store, keyed by query key.
  *
@@ -106,6 +107,183 @@ export function mobxStore(observable, toJS, reaction) {
         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',
+    HAS_ERROR: 'hasError',
+};
+function projectLoadable(loadable) {
+    if (loadable.state === RecoilLoadState.HAS_ERROR) {
+        const contents = loadable.contents;
+        return {
+            status: loadable.state,
+            value: null,
+            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 = {};
+            for (const [name, atom] of Object.entries(atoms)) {
+                out[name] = projectLoadable(current.getLoadable(atom));
+            }
+            return out;
+        },
+        subscribe,
+    };
+}
+function stopSubscription(handle) {
+    if (typeof handle === 'function') {
+        handle();
+        return;
+    }
+    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 {
+        getState: () => {
+            let value;
+            let called = false;
+            stopSubscription(readable.subscribe((next) => {
+                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 ' +
+                    'its current value cannot be read. reticle_state will report undefined for it. Svelte ' +
+                    'stores always call back immediately; an RxJS Observable does not unless it is a ' +
+                    'BehaviorSubject.');
+            }
+            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)
+                    listener();
+            });
+            inSubscribeCall = false;
+            return () => stopSubscription(handle);
+        },
+    };
+}
+/** 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.
  *
@@ -132,4 +310,3 @@ export function pushStore(initial) {
         },
     };
 }
-//# sourceMappingURL=store-adapters.js.map

package/dist/registry/stores.d.ts

@@ -48,4 +48,3 @@ export declare function readStoresWithTruncation(only?: string): {
     stores: Record<string, unknown>;
     truncation?: Record<string, TruncationReport>;
 };
-//# sourceMappingURL=stores.d.ts.map

package/dist/registry/stores.js

@@ -42,6 +42,14 @@ export function registerStore(name, source, subscribe) {
         notifyRegistered(name, getter, sub);
         return;
     }
+    if (typeof source !== 'function') {
+        const hasSubscribe = typeof source === 'object' && source !== null && 'subscribe' in source;
+        nativeWarn(`[reticle] store "${name}" is neither a getter function nor a {getState, subscribe} store` +
+            (hasSubscribe
+                ? ` — it has subscribe but no getState. Wrap it with an adapter or add getState.`
+                : '.'));
+        return;
+    }
     stores.set(name, source);
     if (subscribe !== undefined) {
         subscribers.set(name, subscribe);
@@ -141,4 +149,3 @@ 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.`);
 }
-//# sourceMappingURL=stores.js.map

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

@@ -16,4 +16,3 @@ export declare function modeForCommand(commandName: string): PresenterMode;
  * 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;
-//# sourceMappingURL=reticle-presenter-helpers.d.ts.map

package/dist/reticle-presenter-helpers.js

@@ -78,4 +78,3 @@ function queryTarget(q) {
         return name !== undefined ? `"${value}" (${name})` : `"${value}"`;
     return name !== undefined ? `"${name}"` : undefined;
 }
-//# sourceMappingURL=reticle-presenter-helpers.js.map

package/dist/reticle.d.ts

@@ -1,62 +1,7 @@
 import { EventType, RETICLE_URL_PARAM, type ReticleEvent } from '@reticlehq/core';
 import { type CapabilitiesInput } from './registry/capabilities.js';
-export interface ReticleConnectOptions {
-    /** WS endpoint of the local bridge. Defaults to ws://localhost:<port><path>. */
-    url?: string;
-    /** Human-friendly session label so the agent can target the right tab. */
-    session?: string;
-    /**
-     * Stable project identity, normally stamped by the build plugin (e.g. "acme-web-9f3c1d"). Lets the
-     * agent scope to the right app even when its dev server boots on an unexpected port. Optional.
-     */
-    projectId?: string;
-    /** Browser/bridge pairing token. Required when either endpoint is non-localhost. */
-    token?: string;
-    /** Explicitly allow Reticle on a non-localhost page or bridge. Requires token. */
-    allowNonLocalhost?: boolean;
-    /**
-     * Escape hatch for the production backstop. Reticle is dev-only and refuses to connect when the
-     * build reports NODE_ENV=production (an SSR healthcheck or a prod bundle opened locally would
-     * otherwise activate). The real fix is to gate the import behind `import.meta.env.DEV` so it's
-     * tree-shaken out; this flag only exists for the rare intentional prod diagnostic.
-     */
-    allowInProduction?: boolean;
-    /** Show a small in-page status chip (connection + event count). */
-    overlay?: boolean;
-    /**
-     * Capture request/response bodies on net.request events (dev-only; text-like content only,
-     * sensitive keys redacted, per-body capped). Off by default — bodies cost tokens and can carry PII.
-     */
-    captureNetworkBodies?: boolean;
-    /** Presenter mode: glow border, animated cursor, click/hover effects, narration HUD. */
-    present?: boolean;
-    /** Per-action pacing (ms) in presenter mode so a human can follow. Default 450. */
-    pace?: number;
-    /** Min ms each narration line stays visible before the next replaces it (presenter). Default 3000. */
-    narrationDwellMs?: number;
-    /**
-     * Border behavior in presenter mode: 'session' (default) persists the border for the whole
-     * session; 'busy' restores the fade-after-idle behavior.
-     */
-    border?: 'session' | 'busy';
-    /** Max accumulated activity-log rows before the oldest are pruned (presenter). Default 50. */
-    logMax?: number;
-    /**
-     * Mount the floating human-recorder toolbar (Record/Stop/Annotate).
-     * Default off — purely additive, dev-only.
-     */
-    recorder?: boolean;
-    /**
-     * Mount the "Flag a bug" annotator: the human clicks an element that looks wrong, types what's
-     * wrong, and Reticle emits a HUMAN_MARK the agent drains via reticle_review. Defaults to ON with the
-     * presenter (it's the human's side of the look→act→assert loop); pass `annotate: false` to suppress.
-     */
-    annotate?: boolean;
-    /** Live-control: overridable ended-border fade delay (native timer). Default 4000. */
-    endedFadeMs?: number;
-    /** Session auto-end after this much agent idle (presenter). Default 5min; agent-tunable via reticle_session. */
-    idleEndMs?: number;
-}
+import type { ReticleConnectOptions } from './connect-options.js';
+export type { ReticleConnectOptions };
 /**
  * Runtime backstop for the dev-only SDK: block connecting when the build reports production, unless
  * explicitly overridden. Pure so it's testable; connect reads NODE_ENV safely (process may be absent
@@ -64,7 +9,9 @@ export interface ReticleConnectOptions {
  * behind `import.meta.env.DEV` so the SDK is dead-code-eliminated from prod bundles entirely.
  */
 export declare function shouldBlockProduction(nodeEnv: string | undefined, allowInProduction: boolean): boolean;
-export declare function connectionPolicy(pageHostname: string, bridgeUrl: string, allowNonLocalhost: boolean, token: string | undefined): {
+export declare function connectionPolicy(pageHostname: string, bridgeUrl: string, allowNonLocalhost: boolean, token: string | undefined, 
+/** The page's protocol. Desktop webviews (file:, app:, tauri:) are local despite a non-loopback host. */
+pageProtocol?: string): {
     allowed: boolean;
     reason?: string;
 };
@@ -134,4 +81,3 @@ export declare class Reticle {
     endSession(): void;
     disconnect(): void;
 }
-//# sourceMappingURL=reticle.d.ts.map