@reticlehq/browser 2.13.1 → 3.1.0

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/console/native-console.js

@@ -0,0 +1,5 @@
+const g = globalThis;
+const realWarn = 'function' === typeof g.console?.warn ? g.console.warn.bind(g.console) : null;
+export const nativeWarn = (...args) => {
+    realWarn?.(...args);
+};

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

@@ -0,0 +1,11 @@
+export declare const nativeNow: () => number;
+export declare const nativeSetTimeout: (cb: () => void, ms?: number) => number;
+export declare const nativeClearTimeout: (id: number) => void;
+export declare const nativeSetInterval: (cb: () => void, ms: number) => (() => void);
+interface FrameOutcome {
+    settled: boolean;
+}
+export declare const boundedFrame: (budgetMs?: number) => Promise<FrameOutcome>;
+export declare const nativeFrame: () => Promise<void>;
+export declare const settle: (budgetMs?: number) => Promise<FrameOutcome>;
+export {};

package/dist/timers/native/native-timers.js

@@ -0,0 +1,48 @@
+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;
+export const nativeNow = () => (realPerfNow ? realPerfNow() : 0);
+export const nativeSetTimeout = (cb, ms = 0) => realSetTimeout ? realSetTimeout(cb, ms) : 0;
+export const nativeClearTimeout = (id) => {
+    realClearTimeout?.(id);
+};
+export const nativeSetInterval = (cb, ms) => {
+    let stopped = false;
+    let id = 0;
+    const tick = () => {
+        if (stopped)
+            return;
+        cb();
+        if (stopped)
+            return;
+        id = nativeSetTimeout(tick, ms);
+    };
+    id = nativeSetTimeout(tick, ms);
+    return () => {
+        stopped = true;
+        nativeClearTimeout(id);
+    };
+};
+const FRAME_BUDGET_MS = 200;
+export const boundedFrame = (budgetMs = FRAME_BUDGET_MS) => new Promise((resolve) => {
+    let done = false;
+    const finish = (settled) => {
+        if (done)
+            return;
+        done = true;
+        nativeClearTimeout(timer);
+        resolve({ settled });
+    };
+    const timer = nativeSetTimeout(() => finish(false), budgetMs);
+    if (realRaf)
+        realRaf(() => finish(true));
+    else
+        nativeSetTimeout(() => finish(true), 0);
+});
+export const nativeFrame = () => boundedFrame().then(() => undefined);
+export const settle = async (budgetMs = FRAME_BUDGET_MS) => {
+    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;
 }

package/dist/transport/transport.js

@@ -1,8 +1,7 @@
 import { CHURN_TYPES, CommandMessageSchema, EventType, MessageKind, SESSION_LIFECYCLE, } from '@reticlehq/core';
-import { nativeSetTimeout, nativeNow } from '../timers/native-timers.js';
-import { nativeWarn } from '../timers/native-console.js';
+import { nativeSetTimeout, nativeNow } from '../timers/native/native-timers.js';
+import { nativeWarn } from '../timers/console/native-console.js';
 import { safeStringify } from '../security/serialization.js';
-/** Default visibility source: fire `handler` whenever the document returns to the foreground. */
 function subscribeDocumentVisible(handler) {
     if ('undefined' === typeof document)
         return () => undefined;
@@ -13,69 +12,29 @@ function subscribeDocumentVisible(handler) {
     document.addEventListener('visibilitychange', listener);
     return () => document.removeEventListener('visibilitychange', listener);
 }
-/** The first retry after a drop. Kept short: the common outage is a daemon restarting. */
 const RECONNECT_DELAY_MS = 1000;
-/**
- * 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 const RECONNECT_MAX_DELAY_MS = 30_000;
-/**
- * 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 function nextReconnectDelay(previous) {
     return Math.min(previous * 2, RECONNECT_MAX_DELAY_MS);
 }
-/** Offline queue cap. Exported so tests overflow the real bound instead of a mirrored copy of it. */
 export const MAX_QUEUE = 500;
-/**
- * Standard WebSocket close code 1008 ("policy violation") — the bridge sends it for TERMINAL refusals:
- * a protocol-version mismatch (the browser package is older than the bridge and must be upgraded),
- * auth failure, or a duplicate/invalid handshake. Reconnecting cannot fix any of those, so a blind
- * retry loop just hammers the bridge every second forever and buries the actionable reason. 1013
- * ("try again later" — rate/session limits) and transport-level closes stay retryable.
- */
 const WS_POLICY_VIOLATION = 1008;
-/** Warn that the bridge is unreachable after this many consecutive failed INITIAL connects (~3s). */
 const UNREACHABLE_WARN_AFTER = 3;
-/** WebSocket client to the bridge. Reconnects across reloads; buffers events while down. */
 export class Transport {
     #ws;
     #churnQueue = [];
     #signalQueue = [];
     #insertOrder = 0;
     #closed = false;
-    /** When the current continuous outage began (nativeNow), or undefined while connected. */
     #disconnectedSince;
-    /** Current reconnect delay; grows on each failure, resets on a successful open or on focus. */
     #reconnectDelay = RECONNECT_DELAY_MS;
-    /** Whether onConnectionLost has already fired for the current outage (fire-once). */
     #lost = false;
-    /** True once the socket has opened at least once — gates the "unreachable" first-connect warning. */
     #everConnected = false;
-    /** Consecutive failed INITIAL connects (before any success). */
     #initialFailures = 0;
-    /** Whether the unreachable warning has fired (fire-once). */
     #warnedUnreachable = false;
-    /** Events the offline queue has evicted since the last gap marker reached the bridge. */
     #dropped = 0;
-    /**
-     * Envelope coordinates of the most recent evicted event — the pending marker's tombstone. Set while
-     * a gap is undeclared, cleared once the bridge has been told about it.
-     */
     #gap;
-    /** Session id, cached from the first hello(). Stable for a Transport's life — no need to rebuild the
-     * whole HelloMessage (url/title/adapters) on every inbound command just to read it. */
     #sessionId;
-    /** Teardown for the visibility subscription (foreground-triggered reconnect), while connected. */
     #unsubscribeVisible;
     #deps;
     #now;
@@ -90,18 +49,9 @@ export class Transport {
         this.#unsubscribeVisible ??= (this.#deps.onVisible ?? subscribeDocumentVisible)(() => this.#onVisible());
         this.#open();
     }
-    /**
-     * The tab returned to the foreground. If we're disconnected (and not deliberately closed), reconnect
-     * NOW — a hidden tab's throttled timer may be minutes from firing. A no-op when a socket already
-     * exists (connected or mid-connect), so we never open a duplicate racing the scheduled retry.
-     */
     #onVisible() {
         if (this.#closed)
             return;
-        // A human just came back to the tab, which is the strongest signal the outage may be over — and
-        // it is what makes a 30s ceiling safe. Reset the backoff BEFORE the mid-connect early return: if
-        // a socket is already in flight and then fails, that retry should be prompt too, rather than
-        // inheriting a delay earned while nobody was watching.
         this.#reconnectDelay = RECONNECT_DELAY_MS;
         if (this.#ws !== undefined)
             return;
@@ -113,12 +63,6 @@ export class Transport {
             ws = new WebSocket(this.#deps.url);
         }
         catch {
-            // `new WebSocket()` throws SYNCHRONOUSLY on a mixed-content SecurityError — a ws:// URL from an
-            // https page, which Safari does not exempt for localhost the way Chrome does. Unguarded, that
-            // exception propagates out of connect() into the host app's bootstrap (the SDK's cardinal sin:
-            // it must never break the app it observes) AND leaves connect() half-run, so #connected never
-            // flips true and disconnect() can't remove the monkeypatches. Treat it like any failed open:
-            // note the outage and schedule the normal retry.
             this.#noteOutage();
             this.#noteInitialFailure();
             this.#scheduleReopen();
@@ -126,18 +70,13 @@ export class Transport {
         }
         this.#ws = ws;
         ws.onopen = () => {
-            this.#disconnectedSince = undefined; // healthy again — reset the loss timer
+            this.#disconnectedSince = undefined;
             this.#lost = false;
-            this.#everConnected = true; // a real connection happened ⇒ never warn "unreachable"
-            this.#reconnectDelay = RECONNECT_DELAY_MS; // recovered — the next drop starts prompt again
-            // HELLO is SDK-owned schema data. Preserve its pairing token; the generic sanitizer
-            // intentionally redacts fields named "token" from app-controlled payloads.
+            this.#everConnected = true;
+            this.#reconnectDelay = RECONNECT_DELAY_MS;
             const greeting = this.#deps.hello();
             this.#sessionId ??= greeting.sessionId;
             ws.send(JSON.stringify(greeting));
-            // Declare any gap BEFORE replaying the backlog, stamped with the OLDEST event the queue
-            // dropped — see #sendRaw. The two queues are drained back into one stream in insertion order,
-            // so what the bridge receives is the order the page produced, minus the holes.
             this.#sendGapMarker(ws, greeting.sessionId);
             const replay = [...this.#churnQueue, ...this.#signalQueue].sort((a, b) => a.order - b.order);
             for (const msg of replay)
@@ -152,10 +91,6 @@ export class Transport {
         };
         ws.onclose = (event) => {
             this.#ws = undefined;
-            // A 1008 is the bridge saying "don't come back as you are" — a version mismatch, a rejected
-            // handshake. Retrying every second cannot change the outcome; stop and surface the reason (the
-            // bridge puts an actionable message there, e.g. "upgrade @reticlehq/browser") instead of a
-            // silent reconnect storm. End the session cleanly so the HUD doesn't hang on "running".
             if (event.code === WS_POLICY_VIOLATION) {
                 this.#closed = true;
                 const reason = event.reason.length > 0 ? event.reason : 'policy violation';
@@ -171,16 +106,6 @@ export class Transport {
             ws.close();
         };
     }
-    /**
-     * A scheduled reconnect — skipped if the SDK was torn down, or if a foreground-triggered reconnect
-     * already opened a socket (guard against the throttled timer racing #onVisible into a duplicate).
-     */
-    /**
-     * Schedule the next retry and grow the delay. Nothing is scheduled once the SDK is torn down.
-     *
-     * The delay grows AFTER scheduling, so the first retry of any outage is prompt (a daemon
-     * restarting must not cost 30 seconds) and only a persistent outage backs off.
-     */
     #scheduleReopen() {
         if (this.#closed)
             return;
@@ -194,11 +119,6 @@ export class Transport {
             return;
         this.#open();
     }
-    /**
-     * The first connection has never opened: count failures and, once they cross the threshold, fire
-     * onUnreachable ONCE so the app surfaces an actionable hint (wrong port / container network) rather
-     * than retrying silently forever. Suppressed entirely once any connection has succeeded.
-     */
     #noteInitialFailure() {
         if (this.#everConnected || this.#warnedUnreachable)
             return;
@@ -208,11 +128,6 @@ export class Transport {
             this.#deps.onUnreachable?.({ url: this.#deps.url, attempts: this.#initialFailures });
         }
     }
-    /**
-     * Track how long the bridge has been unreachable. Once the outage exceeds BRIDGE_LOST_MS, fire
-     * onConnectionLost exactly once so the SDK can end the session (the server/agent is gone and can
-     * no longer push an end itself).
-     */
     #noteOutage() {
         const at = this.#now();
         this.#disconnectedSince ??= at;
@@ -231,10 +146,6 @@ export class Transport {
         }
         const result = CommandMessageSchema.safeParse(parsed);
         if (!result.success) {
-            // Also once silent. A command the page cannot parse is a version skew between the SDK and the
-            // daemon, and dropping it produces the same unfalsifiable timeout every other hang produces — the one
-            // failure mode where the cause is knowable and was being thrown away. Reply if we can recover
-            // an id; a message without one is not a command we can answer at all.
             const id = parsed?.id;
             if ('string' === typeof id && id.length > 0) {
                 this.#sendRaw(safeStringify({
@@ -248,13 +159,6 @@ export class Transport {
             return;
         }
         const command = result.data;
-        // #sessionId is set in onopen, which always precedes any inbound command on the same socket.
-        //
-        // A mismatch used to `return` — silently. The command then had no reply of any kind, so the agent
-        // waited out its full timeout and got "command timed out", which reads as a hung or suspended
-        // page. Measured on a Tauri shell: the session was connected and streaming events the whole time
-        // while every command vanished here, and three rounds of debugging went looking at the webview.
-        // A dropped command is a real fault, so it now says so and names both ids.
         if (command.sessionId !== undefined && command.sessionId !== this.#sessionId) {
             this.#sendRaw(safeStringify({
                 kind: MessageKind.COMMAND_RESULT,
@@ -291,15 +195,6 @@ export class Transport {
             type: event.type,
         });
     }
-    /**
-     * 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() {
         if (this.#ws === undefined || this.#ws.readyState !== WebSocket.OPEN)
             return;
@@ -311,17 +206,9 @@ export class Transport {
             return;
         }
         if (this.#churnQueue.length + this.#signalQueue.length >= MAX_QUEUE) {
-            // Prefer sacrificing churn (high-volume, low-signal) over signal events. Falls back to signal
-            // FIFO only when the churn queue is empty — the buffer is bounded either way.
             const evicted = this.#churnQueue.length > 0 ? this.#churnQueue.shift() : this.#signalQueue.shift();
             if (evicted?.event !== undefined) {
                 this.#dropped += 1;
-                // Keep the EARLIEST drop, not the latest. Under plain FIFO the two were the same thing, so
-                // "latest evicted" was a precise boundary: everything before it was gone. Churn-first
-                // eviction breaks that — a churn event newer than a surviving signal event can be the one
-                // sacrificed, and stamping the marker with it would claim a hole that swallows events the
-                // agent is about to receive. The oldest drop is the honest floor: the hole starts no later
-                // than here. A truncation marker may over-state its reach; it must never under-state it.
                 const previous = this.#gap;
                 if (previous === undefined || evicted.event.t < previous.t)
                     this.#gap = evicted.event;
@@ -336,19 +223,6 @@ export class Transport {
             this.#signalQueue.push({ text, event, order });
         }
     }
-    /**
-     * Tell the bridge the offline queue swallowed events, then consider the gap declared.
-     *
-     * Written straight to the open socket instead of going back through `sendEvent`, for two reasons
-     * that both bite at exactly the moment the marker matters. The queue is full when a drop happens,
-     * so a queued marker would evict another real event — every declared gap widening the gap it
-     * declares. And it would re-enter `#sendRaw` from inside the eviction branch, between the `shift`
-     * and the `push`, growing the queue by one on every later send. Writing here makes both impossible.
-     *
-     * The marker inherits the seq/t of the last event it displaced. That event never reaches the
-     * bridge, so the coordinates are free, and the server orders a session by `seq` — a marker minted
-     * at reconnect would carry the highest seq and blame a segment that never had a hole in it.
-     */
     #sendGapMarker(ws, sessionId) {
         const gap = this.#gap;
         if (gap === undefined)

package/dist/transport/unreachable-message.d.ts

@@ -1,19 +1,2 @@
-/**
- * What the page says when its websocket never opened.
- *
- * Pulled out of the connect path so it is a pure string function with a test on its CLAIMS rather
- * than a template inlined in a warn call. The rule it exists to hold: report what this page observed
- * and what it could not determine, never a cause. See unreachable-message.test.ts.
- */
-/**
- * The page tried, failed, and cannot see why. Names the address and the attempt count, refuses to
- * diagnose the daemon, and lists the checks in the order that actually resolves the ambiguity.
- */
 export declare function unreachableMessage(url: string, attempts: number): string;
-/**
- * The same fact, sized for the HUD's one-line status row.
- *
- * The console warning explains; this one only has room to name the URL, which is the answer in
- * most cases anyway — a bridge on a port the page is not dialling.
- */
 export declare function unreachableStripText(url: string, attempts: number): string;

package/dist/transport/unreachable-message.js

@@ -1,15 +1,4 @@
-/**
- * What the page says when its websocket never opened.
- *
- * Pulled out of the connect path so it is a pure string function with a test on its CLAIMS rather
- * than a template inlined in a warn call. The rule it exists to hold: report what this page observed
- * and what it could not determine, never a cause. See unreachable-message.test.ts.
- */
 import { UNREACHABLE_NOTICE_PREFIX } from '@reticlehq/core';
-/**
- * The page tried, failed, and cannot see why. Names the address and the attempt count, refuses to
- * diagnose the daemon, and lists the checks in the order that actually resolves the ambiguity.
- */
 export function unreachableMessage(url, attempts) {
     return (`${UNREACHABLE_NOTICE_PREFIX}${url}. ${String(attempts)} attempts, all ` +
         `failed. That is everything the page can see: from inside the browser it cannot tell a daemon ` +
@@ -19,12 +8,6 @@ export function unreachableMessage(url, attempts) {
         `different host, so set the URL explicitly (Vite: VITE_RETICLE_WS_URL, or ` +
         `reticle.connect({ url })). An https page cannot open a ws:// socket at all. Still retrying…`);
 }
-/**
- * The same fact, sized for the HUD's one-line status row.
- *
- * The console warning explains; this one only has room to name the URL, which is the answer in
- * most cases anyway — a bridge on a port the page is not dialling.
- */
 export function unreachableStripText(url, attempts) {
     return `no bridge at ${url} — ${String(attempts)} attempt${1 === attempts ? '' : 's'}`;
 }