@reticlehq/browser 2.3.0 → 2.5.0

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 ('function' === typeof handle) {
+        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.
  *

package/dist/registry/stores.js

@@ -20,12 +20,12 @@ 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 (source === null)
+    if (null === source)
         return false;
     if (typeof source !== 'object' && typeof source !== 'function')
         return false;
     const candidate = source;
-    return typeof candidate.getState === 'function' && typeof candidate.subscribe === 'function';
+    return 'function' === typeof candidate.getState && 'function' === typeof candidate.subscribe;
 }
 /**
  * App calls this once per store. PREFER passing the store itself — `registerStore('app', useApp)` —
@@ -43,7 +43,7 @@ export function registerStore(name, source, subscribe) {
         return;
     }
     if (typeof source !== 'function') {
-        const hasSubscribe = typeof source === 'object' && source !== null && 'subscribe' in source;
+        const hasSubscribe = 'object' === typeof source && 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.`

package/dist/reticle-presenter-helpers.js

@@ -1,9 +1,9 @@
-import { ReticleCommand, PresenterMode } from '@reticlehq/core';
+import { ReticleCommand, PresenterMode, QueryBy } from '@reticlehq/core';
 import { refs } from './dom/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 typeof value === 'string' ? value : fallback;
+    return 'string' === typeof value ? value : fallback;
 }
 /** A short human label for a ref ("button \"Save\"") for the presenter HUD. */
 export function refLabel(refId) {
@@ -69,7 +69,7 @@ export function presentStatus(commandName, args = {}) {
 }
 /** 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']) ?? (str(q['by']) === 'testid' ? str(q['value']) : undefined);
+    const testid = str(q['testid']) ?? (QueryBy.TESTID === str(q['by']) ? str(q['value']) : undefined);
     if (testid !== undefined)
         return `[testid=${testid}]`;
     const name = str(q['name']);

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

package/dist/reticle.js

@@ -1,8 +1,9 @@
-import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, bridgeWsUrl, ReticleCommand, MessageKind, SESSION_AUTO, SessionState, TRANSPORT_LIMITS, isLoopbackHostname, isLocalPage, } from '@reticlehq/core';
+import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, bridgeWsUrl, ReticleCommand, MessageKind, SESSION_AUTO, SessionState, TRANSPORT_LIMITS, buildRedactionPolicy, isLoopbackHostname, isLocalPage, setActiveRedactionPolicy, wireRedactionKeys, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
+import { rememberSessionLabel } from './session-continuity.js';
 import { createCommandRegistry, RELOAD_CACHE_BUST_PARAM, } from './commands/commands.js';
 import { Transport } from './transport/transport.js';
 import { adapterNames } from './registry/adapters.js';
-import { registerCapabilities, hasCapabilities, } from './registry/capabilities.js';
+import { registerCapabilities, setCapabilitiesListener, hasCapabilities, } from './registry/capabilities.js';
 import { installAllObservers } from './observers/install-all.js';
 import { installOverlay } from './presenter/overlay.js';
 import { Presenter, LOG_KIND, LOG_RESULT, } from './presenter/presenter.js';
@@ -19,7 +20,7 @@ import { Annotator } from './review/annotator.js';
  * behind `import.meta.env.DEV` so the SDK is dead-code-eliminated from prod bundles entirely.
  */
 export function shouldBlockProduction(nodeEnv, allowInProduction) {
-    return nodeEnv === 'production' && !allowInProduction;
+    return 'production' === nodeEnv && !allowInProduction;
 }
 export function connectionPolicy(pageHostname, bridgeUrl, allowNonLocalhost, token, 
 /** The page's protocol. Desktop webviews (file:, app:, tauri:) are local despite a non-loopback host. */
@@ -53,7 +54,7 @@ pageProtocol = 'http:') {
             reason: 'Reticle is disabled outside localhost unless allowNonLocalhost is explicitly enabled',
         };
     }
-    if (token === undefined || token.length === 0) {
+    if (token === undefined || 0 === token.length) {
         return { allowed: false, reason: 'a pairing token is required outside localhost' };
     }
     return { allowed: true };
@@ -145,19 +146,22 @@ export class Reticle {
     #annotator;
     #eventCount = 0;
     #token;
+    #sdkVersion;
     #projectId;
+    /** App-declared extra redaction keys, announced in hello so the driven path honours them too. */
+    #redactKeys = [];
     /** Act-row log handle for the in-flight act/act_sequence, so its outcome stamps the right row. */
     #actHandle;
     connect(options = {}) {
         if (this.#connected)
             return;
-        if (typeof window === 'undefined' || typeof document === 'undefined')
+        if ('undefined' === typeof window || 'undefined' === typeof document)
             return;
         // Dev-only backstop: refuse to activate in a production build (SSR healthcheck, prod bundle opened
         // on localhost). `process` may not exist in a raw browser, so read NODE_ENV off globalThis.
         const proc = globalThis.process;
         const nodeEnv = proc?.env?.NODE_ENV;
-        if (shouldBlockProduction(nodeEnv, options.allowInProduction === true)) {
+        if (shouldBlockProduction(nodeEnv, true === options.allowInProduction)) {
             globalThis.console.warn('[Reticle] disabled in production (NODE_ENV=production). Gate the import behind ' +
                 'import.meta.env.DEV, or pass allowInProduction:true to override.');
             return;
@@ -167,20 +171,40 @@ export class Reticle {
         // reload permanently pollutes the URL the app and the agent see.
         stripReloadCacheBustParam();
         const url = options.url ?? bridgeWsUrl(RETICLE_DEFAULT_PORT);
-        const policy = connectionPolicy(window.location.hostname, url, options.allowNonLocalhost === true, options.token, window.location.protocol);
+        const policy = connectionPolicy(window.location.hostname, url, true === options.allowNonLocalhost, options.token, window.location.protocol);
         if (!policy.allowed) {
             globalThis.console.warn(`[Reticle] ${policy.reason ?? 'connection blocked'}`);
             return;
         }
+        // Publish the project root for the adapters' source relativisation. Done HERE, in library code,
+        // so the app-side connect stays plain JavaScript — see ReticleConnectOptions.root.
+        if (options.root !== undefined && options.root.length > 0) {
+            globalThis[RETICLE_ROOT_GLOBAL] = options.root;
+        }
+        // The build plugin defines this; a hand-wired connect can pass it explicitly. Either way an
+        // absent value means UNKNOWN, so the bridge never reports an unknown pair as in sync.
+        const declaredVersion = options.sdkVersion ?? globalThis[RETICLE_SDK_VERSION_GLOBAL];
+        this.#sdkVersion =
+            'string' === typeof declaredVersion && declaredVersion.length > 0
+                ? declaredVersion
+                : undefined;
         // A pooled/headless launcher can stamp identity via namespaced URL params; explicit (non-auto)
         // options win, but the `auto` sentinel defers to the URL param so leases correlate.
         const identity = resolveConnectIdentity(options, window.location.search);
-        this.#session = resolveSessionLabel(identity.session, () => typeof globalThis.crypto?.randomUUID === 'function'
+        // Remembered per TAB, so a reload rejoins the same session instead of appearing as a new one and
+        // stranding the agent's handle — see session-continuity. An explicit id (connect option, or the
+        // lease's URL param) still wins.
+        const explicitSession = resolveSessionLabel(identity.session, () => '');
+        this.#session = rememberSessionLabel(explicitSession.length > 0 ? explicitSession : undefined, 'undefined' === typeof globalThis.sessionStorage ? undefined : globalThis.sessionStorage, () => 'function' === typeof globalThis.crypto?.randomUUID
             ? `s${globalThis.crypto.randomUUID()}`
             : `s${Date.now().toString(36)}`);
         this.#token =
             options.token !== undefined && options.token.length > 0 ? options.token : undefined;
         this.#projectId = identity.projectId;
+        // Install the redaction rule BEFORE anything can emit. Every observer, the serializer and the
+        // snapshot path read it ambiently, so a policy set even one line after installAllObservers would
+        // leave the first events of the session redacted by a different rule than the rest.
+        this.#applyRedaction(options.redact);
         this.#start = performance.now();
         this.#registry = createCommandRegistry();
         this.#transport = new Transport({
@@ -200,7 +224,7 @@ export class Reticle {
                 // lodash debounce/throttle in the app (now - lastCall stays 0), so search boxes, autosave
                 // and resize handlers stop firing until a reload — with nothing on screen explaining why.
                 resetClock();
-                if (this.#presenter?.sessionActive === true) {
+                if (true === this.#presenter?.sessionActive) {
                     this.#presenter.setState(SessionState.ENDED, BRIDGE_LOST_SUMMARY);
                 }
             },
@@ -213,11 +237,14 @@ export class Reticle {
                     `or reticle.connect({ url })). Still retrying…`);
             },
         });
+        // Capabilities registered AFTER connect (which is when they are registered, by design) must
+        // reach the bridge, or an app that declared its whole testable surface reads as having none.
+        setCapabilitiesListener(() => this.#transport?.reannounce());
         const emit = this.#emit;
         this.#teardowns = installAllObservers(emit, {
-            captureBodies: options.captureNetworkBodies === true,
+            captureBodies: true === options.captureNetworkBodies,
         });
-        if (options.overlay === true) {
+        if (true === options.overlay) {
             this.#overlay = installOverlay();
             this.#overlay.update({ connected: true, events: 0 });
         }
@@ -247,7 +274,7 @@ export class Reticle {
             // so the presenter is visible as soon as the agent is reachable — not just on first command.
             this.#presenter.mount();
         }
-        if (options.recorder === true) {
+        if (true === options.recorder) {
             this.#recorder = installRecorder({ emit, now: () => Date.now() });
             this.#recorder.mount();
         }
@@ -288,7 +315,7 @@ export class Reticle {
     }
     /** Advertise the app's testable surface so the agent learns it without reading source. */
     describe(input) {
-        registerCapabilities(input);
+        registerCapabilities(input); // the registry notifies the transport — see setCapabilitiesListener
     }
     /** Live-control: end the session programmatically from the host app (drives the panel to ended). */
     endSession() {
@@ -340,6 +367,16 @@ export class Reticle {
             /* observation is best-effort; the host app's control flow is not */
         }
     };
+    /**
+     * Resolve the app's redaction config into the ambient policy, and remember the part of it that
+     * travels. A config of `undefined` is not "no policy" — it is the DEFAULT policy, installed
+     * explicitly so a second connect() in the same page (HMR, a re-mount) cannot inherit a rule the
+     * previous one set.
+     */
+    #applyRedaction(config) {
+        setActiveRedactionPolicy(buildRedactionPolicy(config, nativeWarn));
+        this.#redactKeys = wireRedactionKeys(config);
+    }
     #hello() {
         return {
             kind: MessageKind.HELLO,
@@ -351,6 +388,12 @@ export class Reticle {
             adapters: adapterNames(),
             ...(this.#token === undefined ? {} : { token: this.#token }),
             hasCapabilities: hasCapabilities(),
+            // Absent when no build plugin supplied one — "unknown", never "matching".
+            ...(this.#sdkVersion === undefined ? {} : { sdkVersion: this.#sdkVersion }),
+            // Always present: derived from THIS build's core, so it needs no build plugin to supply it.
+            // It is the half of the skew check that works on a hand-wired connect.
+            contract: CONTRACT_FINGERPRINT,
+            ...(0 === this.#redactKeys.length ? {} : { redactKeys: this.#redactKeys }),
         };
     }
     async #handleCommand(command) {
@@ -363,7 +406,7 @@ export class Reticle {
         // SESSION_CONFIG: the agent tunes the session for the app (currently the idle-end window).
         if (command.name === ReticleCommand.SESSION_CONFIG) {
             const idleEndMs = command.args['idleEndMs'];
-            if (typeof idleEndMs === 'number')
+            if ('number' === typeof idleEndMs)
                 this.#presenter?.setIdleEndMs(idleEndMs);
             return { ok: true, result: { applied: this.#presenter !== undefined, idleEndMs } };
         }

package/dist/review/annotator.js

@@ -80,7 +80,7 @@ export class Annotator {
         return this.#markCount;
     }
     mount() {
-        if (this.#root !== undefined || typeof document === 'undefined')
+        if (this.#root !== undefined || 'undefined' === typeof document)
             return;
         const style = document.createElement('style');
         style.setAttribute(MARK_ATTR, 'style');
@@ -193,7 +193,7 @@ export class Annotator {
             return;
         }
         const rect = target.getBoundingClientRect();
-        if (rect.width === 0 && rect.height === 0) {
+        if (0 === rect.width && 0 === rect.height) {
             this.#hi.setAttribute('data-on', '0');
             return;
         }
@@ -239,22 +239,22 @@ export class Annotator {
         const send = pop.querySelector('button[data-send]');
         const submit = () => {
             const note = textarea?.value.trim() ?? '';
-            if (note.length === 0)
+            if (0 === note.length)
                 return; // never send an empty mark
             this.#sendMark(note, resolved, x, y);
             this.#closePopover();
         };
         textarea?.addEventListener('input', () => {
             if (send !== null)
-                send.disabled = textarea.value.trim().length === 0;
+                send.disabled = 0 === textarea.value.trim().length;
         });
         // Keyboard ergonomics devs expect: ⌘/Ctrl+Enter sends, Esc cancels — without leaving the textarea.
         textarea?.addEventListener('keydown', (e) => {
-            if (e.key === 'Escape') {
+            if ('Escape' === e.key) {
                 e.preventDefault();
                 this.#closePopover();
             }
-            else if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+            else if ('Enter' === e.key && (e.metaKey || e.ctrlKey)) {
                 e.preventDefault();
                 submit();
             }
@@ -269,7 +269,7 @@ export class Annotator {
             anchor: resolved.anchor,
             strategy: resolved.strategy,
             label: resolved.label,
-            route: typeof location === 'undefined' ? '' : location.pathname + location.search,
+            route: 'undefined' === typeof location ? '' : location.pathname + location.search,
         };
         if (resolved.source !== undefined)
             data['source'] = resolved.source;

package/dist/security/serialization.js

@@ -31,18 +31,18 @@ function sanitize(value, state, depth, key) {
         return TRUNCATED_VALUE;
     }
     state.nodes += 1;
-    if (value === null || typeof value === 'boolean')
+    if (null === value || 'boolean' === typeof value)
         return value;
-    if (typeof value === 'string') {
-        return boundedString(value, state, key?.toLowerCase() === 'error'
+    if ('string' === typeof value) {
+        return boundedString(value, state, 'error' === key?.toLowerCase()
             ? TRANSPORT_LIMITS.MAX_ERROR_LENGTH
             : TRANSPORT_LIMITS.MAX_STRING_LENGTH);
     }
-    if (typeof value === 'number')
+    if ('number' === typeof value)
         return Number.isFinite(value) ? value : null;
-    if (typeof value === 'bigint')
+    if ('bigint' === typeof value)
         return value.toString();
-    if (typeof value === 'undefined' || typeof value === 'function' || typeof value === 'symbol') {
+    if ('undefined' === typeof value || 'function' === typeof value || 'symbol' === typeof value) {
         return OMIT_VALUE;
     }
     // An invalid Date (`new Date(NaN)` / `new Date(undefined)`, easy to land in app state) throws
@@ -65,7 +65,7 @@ function sanitize(value, state, depth, key) {
                 state.droppedItems += value.size - n;
                 break;
             }
-            const sk = boundedString(typeof k === 'string' ? k : String(k), state, MAX_KEY_LENGTH);
+            const sk = boundedString('string' === typeof k ? k : String(k), state, MAX_KEY_LENGTH);
             const sv = sanitize(v, state, depth + 1, sk);
             if (sv !== OMIT_VALUE)
                 out[sk] = sv;
@@ -176,7 +176,7 @@ function sanitize(value, state, depth, key) {
         const read = keys.map((key) => {
             try {
                 const v = value[key];
-                return { key, value: v, scalar: v === null || typeof v !== 'object', ok: true };
+                return { key, value: v, scalar: null === v || typeof v !== 'object', ok: true };
             }
             catch {
                 return { key, value: undefined, scalar: true, ok: false };
@@ -224,7 +224,7 @@ export function sanitizeWithReport(value) {
     };
     const sanitized = sanitize(value, state, 0);
     const out = sanitized === OMIT_VALUE ? null : sanitized;
-    if (state.droppedItems === 0 && state.truncatedValues === 0)
+    if (0 === state.droppedItems && 0 === state.truncatedValues)
         return { value: out };
     const parts = [];
     if (state.droppedItems > 0)

package/dist/session-continuity.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Keep a tab's session id across a reload.
+ *
+ * The id was minted fresh on every `connect()`. A reload is a new document, so the page came back as
+ * a NEW session while the agent still held the old id — and every call after
+ * `reticle_navigate { reload: true }` was refused with "no browser session connected". Reported on 6
+ * of 6 apps; a reload is the most ordinary thing an agent does.
+ *
+ * `sessionStorage` is exactly the right scope: it survives reloads and same-tab navigations, and is
+ * NOT shared with another tab of the same app — so two tabs stay two sessions, which is what the
+ * multi-session tooling assumes.
+ *
+ * An explicit id still wins. `connect({ session })` and the `__reticle_session` URL param a lease
+ * stamps are callers ASSERTING an identity, not asking for one; they are also remembered, so a
+ * leased tab that reloads rejoins its own lease.
+ */
+export declare function rememberSessionLabel(explicit: string | undefined, store: Storage | undefined, generate: () => string): string;

package/dist/session-continuity.js

@@ -0,0 +1,42 @@
+/**
+ * Keep a tab's session id across a reload.
+ *
+ * The id was minted fresh on every `connect()`. A reload is a new document, so the page came back as
+ * a NEW session while the agent still held the old id — and every call after
+ * `reticle_navigate { reload: true }` was refused with "no browser session connected". Reported on 6
+ * of 6 apps; a reload is the most ordinary thing an agent does.
+ *
+ * `sessionStorage` is exactly the right scope: it survives reloads and same-tab navigations, and is
+ * NOT shared with another tab of the same app — so two tabs stay two sessions, which is what the
+ * multi-session tooling assumes.
+ *
+ * An explicit id still wins. `connect({ session })` and the `__reticle_session` URL param a lease
+ * stamps are callers ASSERTING an identity, not asking for one; they are also remembered, so a
+ * leased tab that reloads rejoins its own lease.
+ */
+/** Where the id lives. Namespaced like the URL param it mirrors. */
+const STORAGE_KEY = '__reticle_session';
+export function rememberSessionLabel(explicit, store, generate) {
+    const read = () => {
+        try {
+            const value = store?.getItem(STORAGE_KEY);
+            return value !== null && value !== undefined && value.length > 0 ? value : undefined;
+        }
+        catch {
+            return undefined; // a sandboxed iframe throws on access; a session must still start
+        }
+    };
+    const write = (value) => {
+        try {
+            store?.setItem(STORAGE_KEY, value);
+        }
+        catch {
+            /* same: never block connect on storage */
+        }
+    };
+    // `explicit` may be '' — resolveSessionLabel yields that for "none given" — and `??` would take it.
+    const asked = explicit !== undefined && explicit.length > 0 ? explicit : undefined;
+    const chosen = asked ?? read() ?? generate();
+    write(chosen);
+    return chosen;
+}