@reticlehq/browser 2.13.0 → 2.14.0

package/dist/transport/transport.js

@@ -2,7 +2,6 @@ import { CHURN_TYPES, CommandMessageSchema, EventType, MessageKind, SESSION_LIFE
 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 ('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'}`;
 }

package/dist/util/captured-method.d.ts

@@ -1,37 +1,2 @@
-/**
- * Read a host object's method as a STORED VALUE, for code that has to put it back.
- *
- * Every observer here patches a global and must be able to undo it: `console.error`, `window.fetch`,
- * `window.setTimeout`, `Date.now`. Undoing means holding the true original — the same function
- * object, so teardown restores exactly what was there and a later install can recognise it by
- * identity — and calling through a separately bound copy, because a host method invoked with the
- * wrong receiver throws (`fetch` gives "Illegal invocation").
- *
- * Written as `const original = window.fetch`, that is a bare unbound method reference, and
- * `@typescript-eslint/unbound-method` is right to flag the SHAPE even though this use is deliberate:
- * the rule cannot see that the next line binds it, nor that the raw value only ever goes back into
- * the slot it came from.
- *
- * The two obvious ways out are both wrong here. An `eslint-disable` is against this repo's standing
- * rule and hides the shape from every future reader. Annotating `this: void` asserts the function
- * does not use its receiver — which for a console method or `fetch` is simply false, and is the very
- * reason the binding exists.
- *
- * So the intent is expressed instead of suppressed. A property descriptor's `value` is a stored
- * value, not a method being detached from its object, which is exactly the distinction the rule is
- * drawing and exactly what this code wants. It is also strictly more accurate for the restore case:
- * it reads what the slot HOLDS rather than what calling the property would do, so an accessor
- * defined on the object cannot be silently flattened into its result.
- *
- * Returns undefined when the property is absent or inherited rather than own — a caller that needs a
- * fallback to the prototype chain should say so at its own call site rather than have it hidden here.
- */
 export declare function capturedMethod<T>(target: object, key: PropertyKey): T | undefined;
-/**
- * The same, for a property this code knows is present — the globals every observer patches.
- *
- * Throws rather than returning a broken teardown. A missing `window.fetch` is not a condition any
- * caller here can recover from, and silently installing a patch that cannot be undone is worse than
- * refusing: the page keeps the wrapper for the rest of its life with nothing able to remove it.
- */
 export declare function requireCapturedMethod<T>(target: object, key: PropertyKey): T;

package/dist/util/captured-method.js

@@ -1,41 +1,6 @@
-/**
- * Read a host object's method as a STORED VALUE, for code that has to put it back.
- *
- * Every observer here patches a global and must be able to undo it: `console.error`, `window.fetch`,
- * `window.setTimeout`, `Date.now`. Undoing means holding the true original — the same function
- * object, so teardown restores exactly what was there and a later install can recognise it by
- * identity — and calling through a separately bound copy, because a host method invoked with the
- * wrong receiver throws (`fetch` gives "Illegal invocation").
- *
- * Written as `const original = window.fetch`, that is a bare unbound method reference, and
- * `@typescript-eslint/unbound-method` is right to flag the SHAPE even though this use is deliberate:
- * the rule cannot see that the next line binds it, nor that the raw value only ever goes back into
- * the slot it came from.
- *
- * The two obvious ways out are both wrong here. An `eslint-disable` is against this repo's standing
- * rule and hides the shape from every future reader. Annotating `this: void` asserts the function
- * does not use its receiver — which for a console method or `fetch` is simply false, and is the very
- * reason the binding exists.
- *
- * So the intent is expressed instead of suppressed. A property descriptor's `value` is a stored
- * value, not a method being detached from its object, which is exactly the distinction the rule is
- * drawing and exactly what this code wants. It is also strictly more accurate for the restore case:
- * it reads what the slot HOLDS rather than what calling the property would do, so an accessor
- * defined on the object cannot be silently flattened into its result.
- *
- * Returns undefined when the property is absent or inherited rather than own — a caller that needs a
- * fallback to the prototype chain should say so at its own call site rather than have it hidden here.
- */
 export function capturedMethod(target, key) {
     return Object.getOwnPropertyDescriptor(target, key)?.value;
 }
-/**
- * The same, for a property this code knows is present — the globals every observer patches.
- *
- * Throws rather than returning a broken teardown. A missing `window.fetch` is not a condition any
- * caller here can recover from, and silently installing a patch that cannot be undone is worse than
- * refusing: the page keeps the wrapper for the rest of its life with nothing able to remove it.
- */
 export function requireCapturedMethod(target, key) {
     const value = capturedMethod(target, key);
     if (value === undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@reticlehq/core": "2.13.0"
+    "@reticlehq/core": "2.14.0"
   },
   "devDependencies": {
     "@iconify-json/heroicons-outline": "^1.2.1",