@reticlehq/browser 2.13.1 → 2.14.0

package/dist/security/serialization.d.ts

@@ -1,33 +1,13 @@
 import { isSensitiveKey, scrubKnownSecrets } from '@reticlehq/core';
-/**
- * What the transport caps removed from a value, if anything.
- *
- * Truncation used to be entirely silent: a 1,000-entity store came back as ~142 entities with no
- * marker and no count, and a caller comparing it against expected data would conclude the app had
- * lost the rest. A partial answer that cannot be distinguished from a complete one is the precise
- * shape of a false green — the failure this project exists to prevent — so the caps now report.
- */
 export interface TruncationReport {
-    /** Whole collection items not included, either past the item cap or past the node budget. */
     droppedItems: number;
-    /** Values replaced by the `[TRUNCATED]` placeholder because a cap was hit inside them. */
     truncatedValues: number;
-    /** Human-and-agent readable summary. Present so a consumer never has to compose one. */
     note: string;
 }
-/** Convert arbitrary app state into a bounded, redacted JSON-compatible value. */
 export declare function sanitizeForTransport(value: unknown): unknown;
-/**
- * As `sanitizeForTransport`, but also reports what the caps removed.
- *
- * Returned as a separate field rather than embedded in the value: the value has to keep the exact
- * shape the consumer's schema declares, so a marker spliced inside it would break validation on the
- * very payloads that are already under pressure.
- */
 export declare function sanitizeWithReport(value: unknown): {
     value: unknown;
     truncation?: TruncationReport;
 };
-/** Serialize without allowing cycles, BigInt, getters, or secrets to break the transport. */
 export declare function safeStringify(value: unknown): string;
 export { isSensitiveKey, scrubKnownSecrets };

package/dist/security/serialization.js

@@ -3,8 +3,6 @@ const TRUNCATED_VALUE = '[TRUNCATED]';
 const UNSERIALIZABLE_VALUE = '[UNSERIALIZABLE]';
 const OMIT_VALUE = Symbol('omit');
 const MAX_KEY_LENGTH = 256;
-// UTF-8 encodes at most ~3 bytes per JS (UTF-16) code unit, so /4 is a provably-safe bound that never
-// exceeds the byte budget — /8 was ~1/8 of the real 1MiB wire budget and truncated legitimate state.
 const MAX_TOTAL_CHARACTERS = Math.floor(TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / 4);
 const MAX_TOTAL_NODES = TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS * 5;
 function boundedString(value, state, max) {
@@ -13,9 +11,6 @@ function boundedString(value, state, max) {
         state.remainingCharacters -= value.length;
         return value;
     }
-    // Count the cut. A silently shortened string is the same false green the collection caps were made
-    // to report: a caller comparing a 500k-char value against expected data sees 65k and concludes the
-    // app dropped the rest, with no marker saying WE did. The report interface exists for exactly this.
     state.truncatedValues += 1;
     const truncated = allowed <= TRUNCATED_VALUE.length
         ? TRUNCATED_VALUE.slice(0, allowed)
@@ -45,23 +40,13 @@ function sanitize(value, state, depth, key) {
     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
-    // RangeError on toISOString — and only safeStringify catches it, so a direct sanitize caller
-    // (readStoresWithTruncation, the state observer) crashed the WHOLE state read over one bad Date.
-    // Degrade to null, the same way a non-finite number does two branches up.
     if (value instanceof Date)
         return Number.isNaN(value.getTime()) ? null : value.toISOString();
-    // Map and Set are common enough in app state (a normalized store keyed by id, a set of selected
-    // ids) that serializing them to `{}` — which is what the plain-object branch below does, since they
-    // have no enumerable own keys — is a false green: an agent reads empty and concludes the state is
-    // empty, when really it was unrepresentable. Convert to a readable shape, bounded by the same caps.
     if (value instanceof Map) {
         const out = Object.create(null);
         let n = 0;
         for (const [k, v] of value) {
             if (state.nodes >= MAX_TOTAL_NODES || n >= TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS) {
-                // Budget spent — STOP. `continue` iterated a million-entry Map to the end just to count drops
-                // one at a time; size-n records the remainder in one shot (like the typed-array branch).
                 state.droppedItems += value.size - n;
                 break;
             }
@@ -78,7 +63,7 @@ function sanitize(value, state, depth, key) {
         let n = 0;
         for (const item of value) {
             if (state.nodes >= MAX_TOTAL_NODES || n >= TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS) {
-                state.droppedItems += value.size - n; // stop; record the remainder at once, don't walk the rest
+                state.droppedItems += value.size - n;
                 break;
             }
             const sv = sanitize(item, state, depth + 1);
@@ -87,10 +72,6 @@ function sanitize(value, state, depth, key) {
         }
         return out;
     }
-    // A typed array (Uint8Array, Float32Array, …) is array-like DATA, not a plain object. The
-    // plain-object branch below turned it into index-keyed keys ({"0":1,"1":2,…}) — a shape lie: an
-    // agent reading a tensor/binary field saw an object where an array lives, and a big one blew the key
-    // cap silently. Emit its numbers as a bounded array like a Set. DataView is opaque bytes — leave it.
     if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
         const len = value.length;
         const out = [];
@@ -117,35 +98,15 @@ function sanitize(value, state, depth, key) {
     state.seen.add(value);
     try {
         if (Array.isArray(value)) {
-            // Truncate by dropping whole ITEMS, never by corrupting them.
-            //
-            // The node budget used to run out mid-collection, so later items kept their shape while
-            // individual fields became the string "[TRUNCATED]" — an array field turned into a string, a
-            // boolean into a string. Consumers declare output schemas over these payloads, so that was not
-            // a degraded answer: validation rejected the whole message and the caller received NOTHING. On
-            // a page with thousands of matches that is a total loss of the query tool, in exactly the
-            // conditions where it matters most.
-            //
-            // Stopping BEFORE an item that will not fit keeps every survivor whole and type-correct. The
-            // collection's true size travels separately as a scalar (serialized first), so "how many" stays
-            // exact while the sample shrinks.
             const out = [];
             const considered = value.slice(0, TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS);
-            // Items beyond the collection cap are dropped before the loop even sees them; count them here
-            // so the report covers BOTH reasons a caller is holding a short list.
             state.droppedItems += Math.max(0, value.length - considered.length);
             for (const item of considered) {
                 if (state.nodes >= MAX_TOTAL_NODES) {
                     state.droppedItems += 1;
                     continue;
                 }
-                // Checking only BEFORE the item is not enough: one that starts under the budget can cross it
-                // partway through and come back with its tail replaced by placeholders. Serialize, then keep
-                // it only if it fitted — otherwise discard it and stop, so what ships is always whole.
                 const sanitized = sanitize(item, state, depth + 1);
-                // `>=`, not `>`: sanitize stops AT the ceiling rather than passing it, so the budget never
-                // reads as exceeded. Reaching it during this item means some field inside was replaced by a
-                // placeholder, which makes the item schema-invalid — drop it and stop.
                 if (state.nodes >= MAX_TOTAL_NODES) {
                     state.droppedItems += 1;
                     continue;
@@ -155,24 +116,9 @@ function sanitize(value, state, depth, key) {
             return out;
         }
         const out = Object.create(null);
-        // Scalars first, collections second. The node budget is spent in iteration order, so a large
-        // array sitting earlier in the object would consume the whole budget and turn the scalars after
-        // it into "[TRUNCATED]". Those scalars are the summary fields — a match `count`, a `total`, a
-        // status — and a summary that degrades to a placeholder while its own sample survives is the
-        // worst trade available: the caller keeps a partial list and loses the number that says the list
-        // is partial. Ordering by cost makes that impossible regardless of how a producer writes its
-        // object literal, so no caller has to know this rule to stay correct.
         const allKeys = Object.keys(value);
         const keys = allKeys.slice(0, TRANSPORT_LIMITS.MAX_OBJECT_KEYS);
-        // Keys past the cap are dropped — count them, like the array/Map/Set paths do, so a 5,000-key
-        // store reported as 200 keys carries a droppedItems marker instead of reading as complete.
         state.droppedItems += Math.max(0, allKeys.length - keys.length);
-        // Read each key's value ONCE, inside the guard. A property getter can throw — MobX strict mode,
-        // a Vue reactive trap read outside a reactive context, any hostile Proxy — and that throw must
-        // cost only its own key, not the whole object read. The earlier code dereferenced the getter in
-        // an unguarded `isScalar` (and again in the sanitize call: two invocations, doubling side
-        // effects), so one bad property lost the entire STATE_READ — the exact silent-loss shape the Date
-        // guard above was written to prevent. Snapshot first, then partition scalars-before-collections.
         const read = keys.map((key) => {
             try {
                 const v = value[key];
@@ -203,17 +149,9 @@ function sanitize(value, state, depth, key) {
         state.seen.delete(value);
     }
 }
-/** Convert arbitrary app state into a bounded, redacted JSON-compatible value. */
 export function sanitizeForTransport(value) {
     return sanitizeWithReport(value).value;
 }
-/**
- * As `sanitizeForTransport`, but also reports what the caps removed.
- *
- * Returned as a separate field rather than embedded in the value: the value has to keep the exact
- * shape the consumer's schema declares, so a marker spliced inside it would break validation on the
- * very payloads that are already under pressure.
- */
 export function sanitizeWithReport(value) {
     const state = {
         seen: new WeakSet(),
@@ -240,7 +178,6 @@ export function sanitizeWithReport(value) {
         },
     };
 }
-/** Serialize without allowing cycles, BigInt, getters, or secrets to break the transport. */
 export function safeStringify(value) {
     try {
         return JSON.stringify(sanitizeForTransport(value));
@@ -249,6 +186,4 @@ export function safeStringify(value) {
         return JSON.stringify(UNSERIALIZABLE_VALUE);
     }
 }
-// Re-exported: these moved to @reticlehq/core (they are wire rules, not DOM rules).
-// Kept on this module's surface so every existing importer inside the SDK is unaffected.
 export { isSensitiveKey, scrubKnownSecrets };

package/dist/session-continuity.d.ts

@@ -1,17 +1 @@
-/**
- * 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

@@ -1,20 +1,3 @@
-/**
- * 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 = () => {
@@ -23,7 +6,7 @@ export function rememberSessionLabel(explicit, store, generate) {
             return value !== null && value !== undefined && value.length > 0 ? value : undefined;
         }
         catch {
-            return undefined; // a sandboxed iframe throws on access; a session must still start
+            return undefined;
         }
     };
     const write = (value) => {
@@ -31,10 +14,8 @@ export function rememberSessionLabel(explicit, store, generate) {
             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);

package/dist/timers/clock.d.ts

@@ -1,18 +1,5 @@
+export declare const FREEZE_WATCHDOG_MS = 120000;
 export declare function isClockFrozen(): boolean;
 export declare function freezeClock(): void;
-/** Run all timers due within the next `ms` of virtual time, in order. */
 export declare function advanceClock(ms: number): void;
-/**
- * Restore the real timers AND hand back everything the app queued while frozen.
- *
- * The queue used to be discarded (`tasks = []`). Restoring the native functions is only half the job:
- * the callbacks the app scheduled during the freeze live in the virtual queue, and dropping them leaves
- * the app quietly broken in a new way — a toast that never dismisses, a retry that never fires, a
- * session-expiry check that never runs. `Date.now()` and future timers look healthy, so nothing points
- * at the cause. That matters most on the path this is called from: an agent freezes the clock, the
- * bridge dies, and the developer is left with an app that was never un-frozen deliberately.
- *
- * Pending work is re-scheduled onto REAL timers with its remaining virtual delay (a 5s toast frozen 2s
- * in still has ~3s to go), and the ids the app is holding keep working — see the translation note.
- */
 export declare function resetClock(): void;

package/dist/timers/clock.js

@@ -1,14 +1,26 @@
-// Fake clock: patch the APP's setTimeout/setInterval/Date.now/performance.now so the agent
-// can deterministically advance time (toasts, debounces, auto-dismiss, commit-on-blur).
-// We do NOT patch requestAnimationFrame/microtasks/MessageChannel — React's scheduler relies
-// on those, and freezing them would stall the page. Opt-in + reversible.
 import { requireCapturedMethod } from '../util/captured-method.js';
+import { captureMethod } from '../patching/capture-method.js';
+export const FREEZE_WATCHDOG_MS = 120_000;
 let installed = false;
 let virtualNow = 0;
 let realBase = 0;
 let seq = 1;
 let tasks = [];
 let originals = null;
+let watchdog;
+let ourFakes = {};
+function armWatchdog() {
+    if (null === originals)
+        return;
+    const natives = originals;
+    const clear = natives.clearTimeout.bind(window);
+    if (watchdog !== undefined)
+        clear(watchdog);
+    watchdog = natives.setTimeout.bind(window)(() => {
+        watchdog = undefined;
+        resetClock();
+    }, FREEZE_WATCHDOG_MS);
+}
 export function isClockFrozen() {
     return installed;
 }
@@ -18,8 +30,6 @@ export function freezeClock() {
     installed = true;
     virtualNow = 0;
     realBase = Date.now();
-    // Captured as stored VALUES, so teardown restores the same function objects the page had. See
-    // capturedMethod: these are deliberate unbound captures and the descriptor read says so.
     originals = {
         setTimeout: requireCapturedMethod(window, 'setTimeout'),
         clearTimeout: requireCapturedMethod(window, 'clearTimeout'),
@@ -36,15 +46,23 @@ export function freezeClock() {
     const cancel = (id) => {
         tasks = tasks.filter((t) => t.id !== id);
     };
-    window.setTimeout = ((cb, delay = 0) => schedule(cb, delay));
+    const withArgs = (cb, args) => () => {
+        cb(...args);
+    };
+    window.setTimeout = ((cb, delay = 0, ...args) => schedule(withArgs(cb, args), delay));
     window.clearTimeout = ((id) => cancel(id));
-    window.setInterval = ((cb, delay = 0) => schedule(cb, delay, Math.max(1, delay)));
+    window.setInterval = ((cb, delay = 0, ...args) => schedule(withArgs(cb, args), delay, Math.max(1, delay)));
     window.clearInterval = ((id) => cancel(id));
-    // Note: we deliberately do NOT patch performance.now — React 19's scheduler uses it to
-    // flush updates, and freezing it stalls re-renders. setTimeout/Date.now cover app timers.
+    ourFakes = {
+        setTimeout: captureMethod(window, 'setTimeout'),
+        clearTimeout: captureMethod(window, 'clearTimeout'),
+        setInterval: captureMethod(window, 'setInterval'),
+        clearInterval: captureMethod(window, 'clearInterval'),
+    };
     Date.now = () => realBase + virtualNow;
+    ourFakes.dateNow = captureMethod(Date, 'now');
+    armWatchdog();
 }
-/** Run all timers due within the next `ms` of virtual time, in order. */
 export function advanceClock(ms) {
     if (!installed)
         return;
@@ -62,37 +80,33 @@ export function advanceClock(ms) {
         virtualNow = next.time;
         next.cb();
         if (next.interval !== undefined) {
-            // Reschedule under the SAME id — a real setInterval keeps one id for its whole life. Minting a
-            // fresh id here (an earlier `id: seq++`) meant the app still held the original id, so its own
-            // clearInterval(id) after the first tick matched nothing and the interval fired forever.
             tasks.push({ ...next, time: virtualNow + next.interval });
         }
     }
     virtualNow = target;
+    armWatchdog();
 }
-/**
- * Restore the real timers AND hand back everything the app queued while frozen.
- *
- * The queue used to be discarded (`tasks = []`). Restoring the native functions is only half the job:
- * the callbacks the app scheduled during the freeze live in the virtual queue, and dropping them leaves
- * the app quietly broken in a new way — a toast that never dismisses, a retry that never fires, a
- * session-expiry check that never runs. `Date.now()` and future timers look healthy, so nothing points
- * at the cause. That matters most on the path this is called from: an agent freezes the clock, the
- * bridge dies, and the developer is left with an app that was never un-frozen deliberately.
- *
- * Pending work is re-scheduled onto REAL timers with its remaining virtual delay (a 5s toast frozen 2s
- * in still has ~3s to go), and the ids the app is holding keep working — see the translation note.
- */
 export function resetClock() {
     if (!installed || null === originals)
         return;
     const natives = originals;
     const pending = tasks;
-    window.setTimeout = natives.setTimeout;
-    window.clearTimeout = natives.clearTimeout;
-    window.setInterval = natives.setInterval;
-    window.clearInterval = natives.clearInterval;
-    Date.now = natives.dateNow;
+    if (watchdog !== undefined) {
+        natives.clearTimeout.bind(window)(watchdog);
+        watchdog = undefined;
+    }
+    const fakes = ourFakes;
+    ourFakes = {};
+    if (window.setTimeout === fakes.setTimeout)
+        window.setTimeout = natives.setTimeout;
+    if (window.clearTimeout === fakes.clearTimeout)
+        window.clearTimeout = natives.clearTimeout;
+    if (window.setInterval === fakes.setInterval)
+        window.setInterval = natives.setInterval;
+    if (window.clearInterval === fakes.clearInterval)
+        window.clearInterval = natives.clearInterval;
+    if (Date.now === fakes.dateNow)
+        Date.now = natives.dateNow;
     const resumeFrom = virtualNow;
     originals = null;
     tasks = [];
@@ -100,31 +114,14 @@ export function resetClock() {
     virtualNow = 0;
     if (0 === pending.length)
         return;
-    // Re-arm the app's pending work onto REAL timers, translating ids as we go.
-    //
-    // The app is still holding the VIRTUAL id it was handed while frozen; a native re-arm returns a
-    // different one. Without translation the app's own `clearTimeout(id)` would fail to cancel the
-    // re-armed callback AND would cancel whichever unrelated native timer happens to hold that id — both
-    // id spaces start at 1, so the collision is likely, not theoretical. An earlier version dropped
-    // intervals to dodge this and re-armed timeouts anyway, which has the identical hazard: a component
-    // that does `const t = setTimeout(hide, 5000); return () => clearTimeout(t)` cannot cancel `hide`,
-    // so it fires on an unmounted component.
-    //
-    // So keep a translation map and a clear-shim for exactly as long as re-armed work is outstanding.
-    // Nothing is dropped, and the app's handles keep working.
-    // Bound to `window`, not called off `natives`. A timer native invoked with any other receiver
-    // throws `TypeError: Illegal invocation` in a real browser — and `natives.setTimeout(...)` passes
-    // `natives`. jsdom does not enforce the receiver, so every unit test here passed while the browser
-    // threw on the one path that matters: re-arming work the app queued during the freeze. The early
-    // return above means it only fires when something IS pending, which is exactly when this function
-    // has a job to do. Caught by `bench/harness/clock-timetravel.mjs` driving real Chromium.
     const nativeSetTimeout = natives.setTimeout.bind(window);
     const nativeSetInterval = natives.setInterval.bind(window);
     const reArmed = new Map();
+    const shims = {};
     const done = (virtualId) => {
         reArmed.delete(virtualId);
-        if (0 === reArmed.size)
-            restoreRawClears(natives);
+        if (0 === reArmed.size && shims.current !== undefined)
+            restoreRawClears(natives, shims.current);
     };
     for (const task of pending) {
         if (task.interval !== undefined) {
@@ -137,12 +134,9 @@ export function resetClock() {
             }, Math.max(0, task.time - resumeFrom)));
         }
     }
-    installTranslatingClears(reArmed, natives, done);
+    shims.current = installTranslatingClears(reArmed, natives, done);
 }
-/** Route a clear() for a re-armed virtual id to its real native id; everything else passes through. */
 function installTranslatingClears(reArmed, natives, done) {
-    // `.bind(window)` for the same reason as the re-arm above: a bare `rawClear(id)` reaches the DOM
-    // with the wrong receiver and throws `Illegal invocation` in a real browser.
     const translate = (rawClear) => {
         const clear = rawClear.bind(window);
         return ((id) => {
@@ -157,9 +151,14 @@ function installTranslatingClears(reArmed, natives, done) {
     };
     window.clearTimeout = translate(natives.clearTimeout);
     window.clearInterval = translate(natives.clearInterval);
+    return {
+        clearTimeout: captureMethod(window, 'clearTimeout'),
+        clearInterval: captureMethod(window, 'clearInterval'),
+    };
 }
-/** Drop the shim once no re-armed work is outstanding — it costs nothing to remove and one hop to keep. */
-function restoreRawClears(natives) {
-    window.clearTimeout = natives.clearTimeout;
-    window.clearInterval = natives.clearInterval;
+function restoreRawClears(natives, shims) {
+    if (window.clearTimeout === shims.clearTimeout)
+        window.clearTimeout = natives.clearTimeout;
+    if (window.clearInterval === shims.clearInterval)
+        window.clearInterval = natives.clearInterval;
 }

package/dist/timers/native-console.js

@@ -1,7 +1,3 @@
-// Native console.warn captured at module load, BEFORE installConsole patches console.
-// SDK-internal diagnostics (transport failures, unreachable-bridge, store registration warnings)
-// MUST use this instead of bare `console.warn` — otherwise they emit spurious CONSOLE_WARN
-// events to the agent, polluting the observation stream with SDK internals.
 const g = globalThis;
 const realWarn = 'function' === typeof g.console?.warn ? g.console.warn.bind(g.console) : null;
 export const nativeWarn = (...args) => {

package/dist/timers/native-timers.d.ts

@@ -1,36 +1,11 @@
-/**
- * Monotonic "now" bound at load. clock.ts deliberately does NOT patch performance.now, so this
- * stays live even when the app clock (reticle_clock) is frozen — the presenter state machine relies
- * on it. Falls back to 0 in SSR where performance is absent.
- */
 export declare const nativeNow: () => number;
 export declare const nativeSetTimeout: (cb: () => void, ms?: number) => number;
 export declare const nativeClearTimeout: (id: number) => void;
-/**
- * A self-rescheduling interval built on the bound real timer. We do NOT use
- * `setInterval` because reticle_clock can freeze the app's timers — a native, pre-bound
- * timer keeps the page-health heartbeat ticking so a frozen clock never reads as stale.
- * Returns a stop function.
- */
 export declare const nativeSetInterval: (cb: () => void, ms: number) => (() => void);
-/** Outcome of a bounded frame/settle wait. */
 interface FrameOutcome {
-    /** true = a real rAF fired within budget; false = the timeout fallback fired. */
     settled: boolean;
 }
-/**
- * One animation frame, BOUNDED: races real rAF against a nativeSetTimeout(FRAME_BUDGET_MS).
- * In a throttled/background tab rAF never fires, so the timer wins and we still resolve.
- * Returns whether rAF won (settled:true) or the fallback fired (settled:false).
- */
 export declare const boundedFrame: (budgetMs?: number) => Promise<FrameOutcome>;
-/** One animation frame, BOUNDED — delegates to boundedFrame so it never hangs in a throttled tab. */
 export declare const nativeFrame: () => Promise<void>;
-/**
- * "Settle": let the framework flush. Awaits a microtask then one BOUNDED animation frame so a
- * React commit (and the MutationObserver records it triggers) lands before the caller returns.
- * Uses native timers/rAF so a frozen app clock (reticle_clock) never stalls it, AND is bounded so a
- * throttled/background tab (rAF never fires) never deadlocks. Reports whether a real frame fired.
- */
 export declare const settle: (budgetMs?: number) => Promise<FrameOutcome>;
 export {};

package/dist/timers/native-timers.js

@@ -1,30 +1,13 @@
-// Native timers captured (bound) at module load, BEFORE any fake-clock patch. The SDK uses
-// these for its own internal waits (presenter pacing, hover dwell, transport reconnect) so
-// that freezing the app's clock (reticle_clock) never deadlocks Reticle itself.
-//
-// Important: we bind the reference now. Resolving `setTimeout` at call time would pick up the
-// patched (frozen) timer once reticle_clock freezes the clock — which would hang the SDK.
 const g = globalThis;
 const realSetTimeout = 'function' === typeof g.setTimeout ? g.setTimeout.bind(g) : null;
 const realClearTimeout = 'function' === typeof g.clearTimeout ? g.clearTimeout.bind(g) : null;
 const realRaf = 'function' === typeof g.requestAnimationFrame ? g.requestAnimationFrame.bind(g) : null;
 const realPerfNow = 'function' === typeof g.performance?.now ? g.performance.now.bind(g.performance) : null;
-/**
- * Monotonic "now" bound at load. clock.ts deliberately does NOT patch performance.now, so this
- * stays live even when the app clock (reticle_clock) is frozen — the presenter state machine relies
- * on it. Falls back to 0 in SSR where performance is absent.
- */
 export const nativeNow = () => (realPerfNow ? realPerfNow() : 0);
 export const nativeSetTimeout = (cb, ms = 0) => realSetTimeout ? realSetTimeout(cb, ms) : 0;
 export const nativeClearTimeout = (id) => {
     realClearTimeout?.(id);
 };
-/**
- * A self-rescheduling interval built on the bound real timer. We do NOT use
- * `setInterval` because reticle_clock can freeze the app's timers — a native, pre-bound
- * timer keeps the page-health heartbeat ticking so a frozen clock never reads as stale.
- * Returns a stop function.
- */
 export const nativeSetInterval = (cb, ms) => {
     let stopped = false;
     let id = 0;
@@ -42,13 +25,7 @@ export const nativeSetInterval = (cb, ms) => {
         nativeClearTimeout(id);
     };
 };
-/** Max time we wait for a real animation frame before giving up and resolving anyway. */
 const FRAME_BUDGET_MS = 200;
-/**
- * One animation frame, BOUNDED: races real rAF against a nativeSetTimeout(FRAME_BUDGET_MS).
- * In a throttled/background tab rAF never fires, so the timer wins and we still resolve.
- * Returns whether rAF won (settled:true) or the fallback fired (settled:false).
- */
 export const boundedFrame = (budgetMs = FRAME_BUDGET_MS) => new Promise((resolve) => {
     let done = false;
     const finish = (settled) => {
@@ -62,17 +39,10 @@ export const boundedFrame = (budgetMs = FRAME_BUDGET_MS) => new Promise((resolve
     if (realRaf)
         realRaf(() => finish(true));
     else
-        nativeSetTimeout(() => finish(true), 0); // jsdom/SSR: 0ms timer "is" the frame
+        nativeSetTimeout(() => finish(true), 0);
 });
-/** One animation frame, BOUNDED — delegates to boundedFrame so it never hangs in a throttled tab. */
 export const nativeFrame = () => boundedFrame().then(() => undefined);
-/**
- * "Settle": let the framework flush. Awaits a microtask then one BOUNDED animation frame so a
- * React commit (and the MutationObserver records it triggers) lands before the caller returns.
- * Uses native timers/rAF so a frozen app clock (reticle_clock) never stalls it, AND is bounded so a
- * throttled/background tab (rAF never fires) never deadlocks. Reports whether a real frame fired.
- */
 export const settle = async (budgetMs = FRAME_BUDGET_MS) => {
-    await Promise.resolve(); // drain the current microtask queue (React scheduler tick)
-    return boundedFrame(budgetMs); // one bounded frame so commit + MutationObserver records flush
+    await Promise.resolve();
+    return boundedFrame(budgetMs);
 };

package/dist/transport/transport.d.ts

@@ -8,75 +8,24 @@ interface TransportDeps {
     url: string;
     hello: () => HelloMessage;
     handleCommand: (command: CommandMessage) => Promise<CommandOutcome>;
-    /** Unthrottled, unpatched clock for bridge-loss timing. Defaults to nativeNow (performance.now). */
     now?: () => number;
-    /** Fired each time the WebSocket (re-)connects to the bridge. */
     onConnected?: () => void;
-    /**
-     * Liveness fallback: fired once when the bridge has been unreachable for SESSION_LIFECYCLE
-     *.BRIDGE_LOST_MS — i.e. the server/agent process is gone, so no server-pushed end can arrive and
-     * the SDK must end the session itself instead of showing a forever-"running" HUD.
-     */
     onConnectionLost?: () => void;
-    /**
-     * Fired once when the VERY FIRST connection keeps failing (never opened) — i.e. the bridge is
-     * unreachable at this URL, most often a wrong port or a container/WSL network boundary. Distinct
-     * from onConnectionLost (which is about losing an ALREADY-established session). The caller surfaces
-     * an actionable hint instead of retrying silently forever.
-     */
     onUnreachable?: (detail: {
         url: string;
         attempts: number;
     }) => void;
-    /**
-     * Subscribe to "the tab became visible again" (default: document `visibilitychange`). Browsers
-     * throttle or suspend timers in a backgrounded tab, so the 1s reconnect loop stalls while hidden —
-     * a bridge blip during sleep/background otherwise leaves the panel stuck on "ENDED" until a manual
-     * reload. On foreground we retry IMMEDIATELY instead of waiting for the throttled timer. Returns an
-     * unsubscribe; injected so a test can drive visibility without a real document.
-     */
     onVisible?: (handler: () => void) => () => void;
-    /**
-     * Schedule an internal retry (default: `nativeSetTimeout`). Injected for the same reason `now` and
-     * `onVisible` are — the default is bound to the real timer at module load so a frozen app clock
-     * cannot deadlock the SDK, which also means no fake clock can observe what was scheduled.
-     */
     schedule?: (fn: () => void, ms: number) => void;
 }
-/**
- * The ceiling on reconnect backoff.
- *
- * A flat 1s retry with no growth and no cap meant a tab left open against a stopped daemon made
- * ~600 failed WebSocket opens in ten minutes — CPU, and a devtools console full of
- * ERR_CONNECTION_REFUSED. Backing off is only safe BECAUSE this transport also reconnects on
- * focus/visibility, so a human returning to the tab retries immediately rather than waiting out
- * the delay; the backoff resets on that path for the same reason.
- */
 export declare const RECONNECT_MAX_DELAY_MS = 30000;
-/**
- * The next reconnect delay: double, then clamp. Pure, and exported so the POLICY is testable —
- * the scheduling itself runs on `nativeSetTimeout`, which is bound to the real timer at module load
- * (deliberately, so a frozen `reticle_clock` cannot deadlock the SDK) and therefore cannot be driven
- * by a fake clock.
- */
 export declare function nextReconnectDelay(previous: number): number;
-/** Offline queue cap. Exported so tests overflow the real bound instead of a mirrored copy of it. */
 export declare const MAX_QUEUE = 500;
-/** WebSocket client to the bridge. Reconnects across reloads; buffers events while down. */
 export declare class Transport {
     #private;
     constructor(deps: TransportDeps);
     connect(): void;
     sendEvent(event: ReticleEvent): void;
-    /**
-     * Re-send the HELLO on a live socket.
-     *
-     * The hello carries `hasCapabilities`, and it goes out at connect() — before the app has had a
-     * chance to call `registerCapabilities`, which by design happens AFTER connect so `registerStore`
-     * has a live SDK to subscribe through. So an app that declared its whole testable surface still
-     * appeared to the agent as having none, and nothing ever corrected it. Cheap and idempotent: the
-     * bridge treats a hello as the session's current identity, not as a new session.
-     */
     reannounce(): void;
     close(): void;
 }