@reticlehq/browser 2.4.0 → 2.6.0

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;
+}

package/dist/timers/clock.js

@@ -12,7 +12,7 @@ export function isClockFrozen() {
     return installed;
 }
 export function freezeClock() {
-    if (installed || typeof window === 'undefined')
+    if (installed || 'undefined' === typeof window)
         return;
     installed = true;
     virtualNow = 0;
@@ -81,7 +81,7 @@ export function advanceClock(ms) {
  * in still has ~3s to go), and the ids the app is holding keep working — see the translation note.
  */
 export function resetClock() {
-    if (!installed || originals === null)
+    if (!installed || null === originals)
         return;
     const natives = originals;
     const pending = tasks;
@@ -95,7 +95,7 @@ export function resetClock() {
     tasks = [];
     installed = false;
     virtualNow = 0;
-    if (pending.length === 0)
+    if (0 === pending.length)
         return;
     // Re-arm the app's pending work onto REAL timers, translating ids as we go.
     //
@@ -109,18 +109,26 @@ export function resetClock() {
     //
     // 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 done = (virtualId) => {
         reArmed.delete(virtualId);
-        if (reArmed.size === 0)
+        if (0 === reArmed.size)
             restoreRawClears(natives);
     };
     for (const task of pending) {
         if (task.interval !== undefined) {
-            reArmed.set(task.id, natives.setInterval(task.cb, task.interval));
+            reArmed.set(task.id, nativeSetInterval(task.cb, task.interval));
         }
         else {
-            reArmed.set(task.id, natives.setTimeout(() => {
+            reArmed.set(task.id, nativeSetTimeout(() => {
                 done(task.id);
                 task.cb();
             }, Math.max(0, task.time - resumeFrom)));
@@ -130,15 +138,20 @@ export function resetClock() {
 }
 /** Route a clear() for a re-armed virtual id to its real native id; everything else passes through. */
 function installTranslatingClears(reArmed, natives, done) {
-    const translate = (rawClear) => ((id) => {
-        const nativeId = reArmed.get(id);
-        if (nativeId === undefined) {
-            rawClear(id);
-            return;
-        }
-        rawClear(nativeId);
-        done(id);
-    });
+    // `.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) => {
+            const nativeId = reArmed.get(id);
+            if (nativeId === undefined) {
+                clear(id);
+                return;
+            }
+            clear(nativeId);
+            done(id);
+        });
+    };
     window.clearTimeout = translate(natives.clearTimeout);
     window.clearInterval = translate(natives.clearInterval);
 }

package/dist/timers/native-console.js

@@ -3,7 +3,7 @@
 // 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 = typeof g.console?.warn === 'function' ? g.console.warn.bind(g.console) : null;
+const realWarn = 'function' === typeof g.console?.warn ? g.console.warn.bind(g.console) : null;
 export const nativeWarn = (...args) => {
     realWarn?.(...args);
 };

package/dist/timers/native-timers.js

@@ -5,10 +5,10 @@
 // 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 = typeof g.setTimeout === 'function' ? g.setTimeout.bind(g) : null;
-const realClearTimeout = typeof g.clearTimeout === 'function' ? g.clearTimeout.bind(g) : null;
-const realRaf = typeof g.requestAnimationFrame === 'function' ? g.requestAnimationFrame.bind(g) : null;
-const realPerfNow = typeof g.performance?.now === 'function' ? g.performance.now.bind(g.performance) : null;
+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

package/dist/transport/transport.d.ts

@@ -36,7 +36,30 @@ interface TransportDeps {
      * 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. */

package/dist/transport/transport.js

@@ -1,19 +1,39 @@
-import { CommandMessageSchema, EventType, MessageKind, SESSION_LIFECYCLE, } from '@reticlehq/core';
+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 { safeStringify } from '../security/serialization.js';
 /** Default visibility source: fire `handler` whenever the document returns to the foreground. */
 function subscribeDocumentVisible(handler) {
-    if (typeof document === 'undefined')
+    if ('undefined' === typeof document)
         return () => undefined;
     const listener = () => {
-        if (document.visibilityState === 'visible')
+        if ('visible' === document.visibilityState)
             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;
 /**
@@ -29,10 +49,14 @@ const UNREACHABLE_WARN_AFTER = 3;
 /** WebSocket client to the bridge. Reconnects across reloads; buffers events while down. */
 export class Transport {
     #ws;
-    #queue = [];
+    #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. */
@@ -60,7 +84,7 @@ export class Transport {
         this.#now = deps.now ?? nativeNow;
     }
     connect() {
-        if (typeof WebSocket === 'undefined')
+        if ('undefined' === typeof WebSocket)
             return;
         this.#closed = false;
         this.#unsubscribeVisible ??= (this.#deps.onVisible ?? subscribeDocumentVisible)(() => this.#onVisible());
@@ -72,7 +96,14 @@ export class Transport {
      * exists (connected or mid-connect), so we never open a duplicate racing the scheduled retry.
      */
     #onVisible() {
-        if (this.#closed || this.#ws !== undefined)
+        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;
         this.#open();
     }
@@ -90,8 +121,7 @@ export class Transport {
             // note the outage and schedule the normal retry.
             this.#noteOutage();
             this.#noteInitialFailure();
-            if (!this.#closed)
-                nativeSetTimeout(() => this.#reopen(), RECONNECT_DELAY_MS);
+            this.#scheduleReopen();
             return;
         }
         this.#ws = ws;
@@ -99,22 +129,26 @@ export class Transport {
             this.#disconnectedSince = undefined; // healthy again — reset the loss timer
             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.
             const greeting = this.#deps.hello();
             this.#sessionId ??= greeting.sessionId;
             ws.send(JSON.stringify(greeting));
-            // Declare any gap BEFORE replaying the backlog. The queue evicts its OLDEST entries, so the
-            // hole always precedes everything that survived it.
+            // 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);
-            for (const msg of this.#queue)
+            const replay = [...this.#churnQueue, ...this.#signalQueue].sort((a, b) => a.order - b.order);
+            for (const msg of replay)
                 ws.send(msg.text);
-            this.#queue = [];
+            this.#churnQueue = [];
+            this.#signalQueue = [];
             this.#deps.onConnected?.();
         };
         ws.onmessage = (event) => {
             const data = event.data;
-            void this.#onMessage(typeof data === 'string' ? data : String(data));
+            void this.#onMessage('string' === typeof data ? data : String(data));
         };
         ws.onclose = (event) => {
             this.#ws = undefined;
@@ -131,8 +165,7 @@ export class Transport {
             }
             this.#noteOutage();
             this.#noteInitialFailure();
-            if (!this.#closed)
-                nativeSetTimeout(() => this.#reopen(), RECONNECT_DELAY_MS);
+            this.#scheduleReopen();
         };
         ws.onerror = () => {
             ws.close();
@@ -142,6 +175,20 @@ export class Transport {
      * 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;
+        const delay = this.#reconnectDelay;
+        this.#reconnectDelay = nextReconnectDelay(delay);
+        const schedule = this.#deps.schedule ?? nativeSetTimeout;
+        schedule(() => this.#reopen(), delay);
+    }
     #reopen() {
         if (this.#closed || this.#ws !== undefined)
             return;
@@ -189,7 +236,7 @@ export class Transport {
             // 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 (typeof id === 'string' && id.length > 0) {
+            if ('string' === typeof id && id.length > 0) {
                 this.#sendRaw(safeStringify({
                     kind: MessageKind.COMMAND_RESULT,
                     id,
@@ -241,6 +288,7 @@ export class Transport {
         this.#sendRaw(safeStringify({ kind: MessageKind.EVENT, event }), {
             seq: event.seq,
             t: event.t,
+            type: event.type,
         });
     }
     /**
@@ -262,19 +310,31 @@ export class Transport {
             this.#ws.send(text);
             return;
         }
-        if (this.#queue.length >= MAX_QUEUE) {
-            // Full offline queue: drop the OLDEST and keep the newest (ring), so after reconnect the agent
-            // replays RECENT activity instead of 500 stale events with the latest lost. Remember what went
-            // so the loss can be declared on reconnect — an unmarked hole reads as "the app did nothing".
-            // Only an evicted EVENT counts: a dropped COMMAND_RESULT is a reply the agent already gave up
-            // waiting for, not a hole in what the app was observed to do.
-            const evicted = this.#queue.shift();
+        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;
-                this.#gap = evicted.event;
+                // 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;
             }
         }
-        this.#queue.push({ text, event });
+        const isChurn = event !== undefined && CHURN_TYPES.has(event.type);
+        const order = this.#insertOrder++;
+        if (isChurn) {
+            this.#churnQueue.push({ text, event, order });
+        }
+        else {
+            this.#signalQueue.push({ text, event, order });
+        }
     }
     /**
      * Tell the bridge the offline queue swallowed events, then consider the gap declared.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,11 +9,12 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "dependencies": {
     "@testing-library/dom": "^10.4.1",
-    "@reticlehq/core": "2.4.0"
+    "@reticlehq/core": "2.6.0"
   },
   "devDependencies": {
     "@tanstack/query-core": "^5.101.4",
@@ -61,6 +62,7 @@
     "build": "tsc -b",
     "typecheck": "tsc -b",
     "lint": "eslint src",
-    "test:unit": "vitest run src --passWithNoTests"
+    "test:unit": "vitest run src --passWithNoTests",
+    "test:coverage": "vitest run src --passWithNoTests --coverage.enabled --coverage.provider=v8 --coverage.reporter=text-summary --coverage.include='src/**/*.ts' --coverage.exclude='src/**/*.test.ts'"
   }
 }