@abloatai/ablo 0.26.0 → 0.28.0

package/dist/sync/{BootstrapHelper.js → BootstrapFetcher.js}

@@ -1,13 +1,17 @@
 /**
- * BootstrapHelper - Fixed to always fetch fresh data
- * Removed problematic caching that was serving stale data
+ * Fetches the initial snapshot the sync engine needs before it can go live: the
+ * current rows for the requested models plus the sync position from which to
+ * resume live updates. It calls the sync server's `/sync/bootstrap` HTTP
+ * endpoint, retries transient failures with backoff, and can fall back to a
+ * cached snapshot when the device is offline. {@link BootstrapData} is the
+ * shape it returns; {@link BootstrapOptions} configures it.
  */
 import { getContext } from '../context.js';
 import { SyncSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../errors.js';
 import { withAuthHeaders } from '../auth/credentialSource.js';
 // SyncObservability replaced by getContext().observability
 import { parseBootstrapResponse } from './schemas.js';
-export class BootstrapHelper {
+export class BootstrapFetcher {
     options;
     abortController = null;
     /** Warn about schema drift at most once per helper. */
@@ -39,23 +43,20 @@ export class BootstrapHelper {
             `\`ablo push\` to deploy your schema (or update this app to match the deployed one).`, { clientSchemaHash: clientHash, serverSchemaHash: serverHash });
     }
     constructor(options) {
-        // Defaults are spread first; the explicit `baseUrl` then takes precedence
-        // and is computed from `options.baseUrl` (or the localhost fallback).
-        //
-        // Historical note: a previous version of this constructor placed
-        // `baseUrl: \`${baseUrl}/api\`` BEFORE the `...options` spread, which
-        // meant the spread silently overwrote it back to the caller's value
-        // and the `/api` suffix was dead code. Both Ablo and `createSyncEngine`
-        // already pass `${url}/api` explicitly, so removing the suffix here
-        // preserves the actual on-the-wire behavior while making the contract
-        // explicit: callers pass the full base URL including `/api`.
+        // Defaults are spread first; the explicit `baseUrl` then takes precedence,
+        // resolved from `options.baseUrl` or the localhost fallback. Callers pass
+        // the full base URL, including the `/api` prefix.
         this.options = {
             syncGroups: [],
             maxRetries: 3,
             retryDelay: 1000,
             fetchTimeout: 10_000, // 10 second timeout per request - fail fast for good UX
             ...options,
-            baseUrl: options.baseUrl || 'http://localhost:8080/api',
+            baseUrl: options.baseUrl ?? 'http://localhost:8080/api',
+            // Reading the deprecated `organizationId` is deliberate: it preserves the
+            // cache namespace for callers that still construct BootstrapFetcher
+            // directly with the old field instead of `cacheScope`.
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             cacheScope: options.cacheScope ?? options.organizationId ?? null,
         };
         // Do not clear cache here; keep offline fallback available
@@ -73,8 +74,8 @@ export class BootstrapHelper {
         this.options.syncGroups = [...(syncGroups ?? [])];
     }
     /**
-     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
-     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     * Sets a fixed credential for callers that construct the helper directly.
+     * The SDK instead supplies `getAuthToken` and never calls this.
      */
     setAuthToken(authToken) {
         if (!authToken) {
@@ -83,26 +84,6 @@ export class BootstrapHelper {
         }
         this.options.authToken = authToken;
     }
-    /**
-     * Create a promise that rejects after a timeout
-     * Used to race against fetch requests that may hang indefinitely
-     */
-    createTimeoutPromise(ms, operation) {
-        return new Promise((_, reject) => {
-            setTimeout(() => {
-                reject(new AbloConnectionError(`Bootstrap ${operation} timed out after ${ms}ms`, {
-                    code: 'bootstrap_fetch_timeout',
-                }));
-            }, ms);
-        });
-    }
-    /**
-     * Wrap a promise with a timeout - if the promise doesn't resolve within
-     * the timeout period, the AbortController is triggered and an error is thrown
-     */
-    async withTimeout(promise, timeoutMs, operation) {
-        return Promise.race([promise, this.createTimeoutPromise(timeoutMs, operation)]);
-    }
     /**
      * Fetch bootstrap data from sync engine with partial bootstrap support
      * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
@@ -110,11 +91,12 @@ export class BootstrapHelper {
      */
     async fetchBootstrap(lastSyncId, 
     /**
-     * Per-call sync-group override for SCOPED hydrate-on-enter. When provided,
-     * the request uses THESE groups instead of `this.options.syncGroups`,
-     * WITHOUT mutating the shared options (so a concurrent full bootstrap is
-     * unaffected). Also bypasses the offline full-snapshot cache below, which
-     * holds the connection's full bootstrap and would be wrong for a subset.
+     * A per-call set of sync groups for a scoped hydrate-on-enter. When given,
+     * the request uses these groups instead of the configured `syncGroups`, and
+     * does so without mutating the shared options, so a concurrent full
+     * bootstrap is unaffected. It also bypasses the offline snapshot cache,
+     * which holds the full bootstrap and would be a wrong answer to a subset
+     * request.
      */
     syncGroupsOverride) {
         // organizationId omitted — server reads it from auth identity.
@@ -135,10 +117,19 @@ export class BootstrapHelper {
             params.append('models', this.options.instantModels.join(','));
         }
         const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
-        // If offline, try cached bootstrap. Skipped for a scoped override — the
-        // cache holds the FULL snapshot, which is not a valid answer to a subset
+        // If offline, try the cached bootstrap. Skipped for a scoped override: the
+        // cache holds the full snapshot, which is not a valid answer to a subset
         // request; a scoped hydrate just soft-fails offline and retries on re-enter.
-        if (!syncGroupsOverride && typeof navigator !== 'undefined' && navigator && navigator.onLine === false) {
+        //
+        // Only an explicit `false` means offline. `navigator.onLine` is *typed*
+        // `boolean`, but at runtime it is `boolean | undefined`: Node 21+ exposes a
+        // global `navigator` whose `onLine` is `undefined`. Reading `!navigator.onLine`
+        // would treat that `undefined` as offline and falsely short-circuit to the
+        // (empty, under `persistence: 'memory'`) cache — throwing instead of fetching.
+        // Capturing it at its true runtime type keeps the `=== false` honest (and lets
+        // the boolean-literal-compare lint rule see the nullable it really is).
+        const navigatorOnline = typeof navigator !== 'undefined' ? navigator.onLine : undefined;
+        if (!syncGroupsOverride && navigatorOnline === false) {
             const cached = this.options.cacheScope
                 ? this.loadCachedBootstrap(this.options.cacheScope)
                 : null;
@@ -160,7 +151,7 @@ export class BootstrapHelper {
                     type: data.type,
                     lastSyncId: data.lastSyncId,
                     modelCount: data.models ? Object.keys(data.models).length : 0,
-                    deltaCount: data.deltaCount || 0,
+                    deltaCount: data.deltaCount ?? 0,
                     totalItems: data.models
                         ? Object.values(data.models).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0)
                         : 0,
@@ -220,11 +211,9 @@ export class BootstrapHelper {
      * Fetch bootstrap with ETag, returning 304 hints
      */
     async fetchBootstrapWithETag() {
-        // organizationId is intentionally NOT sent. Server resolves it from
-        // the authenticated identity (`c.var.identity.organizationId`) —
-        // see `apps/sync-server/src/routes/bootstrap.ts`. Sending it
-        // client-side was historical: it predated the auth-context pipeline
-        // and forced a cross-org guard to defend against the SDK lying.
+        // The organization id is intentionally not sent. The server resolves it
+        // from the authenticated identity, so the client cannot select or spoof an
+        // organization it is not scoped to.
         const params = new URLSearchParams();
         this.options.syncGroups.forEach((g) => { params.append('syncGroups', g); });
         if (this.options.instantModels && this.options.instantModels.length > 0) {
@@ -252,7 +241,10 @@ export class BootstrapHelper {
         }
         if (!res.ok) {
             const bodyText = await res.text().catch(() => '');
-            let parsed = bodyText;
+            // Map an empty body to undefined so the `??` below falls through to the
+            // synthetic message — translateHttpError renders an empty string body as
+            // an empty error message, which is useless to the caller.
+            let parsed = bodyText || undefined;
             if (bodyText) {
                 try {
                     parsed = JSON.parse(bodyText);
@@ -261,12 +253,13 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            // Translate the canonical envelope FIRST so the server's specific code +
-            // message survive (e.g. `api_key_required`, `jwt_issuer_untrusted`).
-            const translated = translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
-            // Only a genuine session/JWT EXPIRY — or a bare auth failure carrying no
-            // structured code — should drive the sign-in redirect. A specific auth
-            // code like `api_key_required` is NOT an expired session: re-logging-in
+            // Translate the canonical envelope first so the server's specific code
+            // and message survive (for example `api_key_required` or
+            // `jwt_issuer_untrusted`).
+            const translated = translateHttpError(res.status, parsed ?? `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            // Only a genuine session or JWT expiry — or a bare auth failure carrying
+            // no structured code — should drive the sign-in redirect. A specific auth
+            // code like `api_key_required` is not an expired session: signing in again
             // mints the same credential and loops. Surface it as its real typed error
             // instead of a `session_expired` wrapping the stringified body.
             if (translated.code === 'session_expired' ||
@@ -277,8 +270,7 @@ export class BootstrapHelper {
             }
             throw translated;
         }
-        const rawJson = await res.json();
-        const data = parseBootstrapResponse(rawJson);
+        const data = parseBootstrapResponse(await res.json());
         this.warnOnSchemaDrift(data.schemaHash);
         // Persist payload for offline
         try {
@@ -286,7 +278,10 @@ export class BootstrapHelper {
                 this.saveCachedBootstrap(this.options.cacheScope, data);
             }
         }
-        catch { }
+        catch {
+            // Offline persistence is best-effort; a failed cache write must not
+            // block returning the freshly fetched data.
+        }
         getContext().logger.info('[Bootstrap] 200 OK - received new data');
         return { notModified: false, data, etag };
     }
@@ -329,7 +324,9 @@ export class BootstrapHelper {
         clearTimeout(timeoutId);
         if (!response.ok) {
             const bodyText = await response.text().catch(() => '');
-            let parsed = bodyText;
+            // Map an empty body to undefined so the `??` below falls through to the
+            // synthetic message (see the note on the primary fetch path).
+            let parsed = bodyText || undefined;
             if (bodyText) {
                 try {
                     parsed = JSON.parse(bodyText);
@@ -341,7 +338,7 @@ export class BootstrapHelper {
             // Same code-aware handling as the primary bootstrap fetch: preserve the
             // server's specific code/message; only a genuine expiry (or a bare,
             // code-less auth failure) drives the sign-in redirect.
-            const translated = translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            const translated = translateHttpError(response.status, parsed ?? `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
             if (translated.code === 'session_expired' ||
                 translated.code === 'jwt_expired' ||
                 ((response.status === 401 || response.status === 403) &&
@@ -350,8 +347,7 @@ export class BootstrapHelper {
             }
             throw translated;
         }
-        const rawJson = await response.json();
-        const data = parseBootstrapResponse(rawJson);
+        const data = parseBootstrapResponse(await response.json());
         this.warnOnSchemaDrift(data.schemaHash);
         // Save a copy for offline
         try {
@@ -359,7 +355,10 @@ export class BootstrapHelper {
                 this.saveCachedBootstrap(this.options.cacheScope, data);
             }
         }
-        catch { }
+        catch {
+            // Offline persistence is best-effort; a failed cache write must not
+            // block returning the freshly fetched data.
+        }
         return data;
     }
     /**
@@ -369,10 +368,9 @@ export class BootstrapHelper {
      */
     async fetchEntity(modelName, id) {
         const url = `${this.options.baseUrl}/sync/entity/${modelName}/${id}`;
-        // Same `fetchTimeout` deadline `performFetch` uses — this was the one
-        // fetch in this file with no AbortSignal, so a hung self-heal read could
-        // stall its caller forever. A LOCAL controller (not `this.abortController`)
-        // so an entity self-heal never cancels a concurrent bootstrap fetch.
+        // Uses the same `fetchTimeout` deadline as `performFetch`. A local
+        // AbortController, rather than the shared `this.abortController`, means an
+        // entity self-heal never cancels a concurrent bootstrap fetch.
         const controller = new AbortController();
         const timeoutId = setTimeout(() => { controller.abort(); }, this.options.fetchTimeout);
         let response;
@@ -401,7 +399,9 @@ export class BootstrapHelper {
         }
         if (!response.ok) {
             const bodyText = await response.text().catch(() => '');
-            let parsed = bodyText;
+            // Map an empty body to undefined so the `??` below falls through to the
+            // synthetic message (see the note on the primary fetch path).
+            let parsed = bodyText || undefined;
             if (bodyText) {
                 try {
                     parsed = JSON.parse(bodyText);
@@ -410,9 +410,9 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(response.status, parsed || `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            throw translateHttpError(response.status, parsed ?? `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
         }
-        return await response.json();
+        return (await response.json());
     }
     // ─────────────────────────────────────────────────────────────────────
     /**
@@ -426,7 +426,7 @@ export class BootstrapHelper {
             const keysToRemove = [];
             for (let i = 0; i < localStorage.length; i++) {
                 const key = localStorage.key(i);
-                if (key && key.includes('sync-bootstrap')) {
+                if (key?.includes('sync-bootstrap')) {
                     keysToRemove.push(key);
                 }
             }
@@ -495,10 +495,10 @@ export class BootstrapHelper {
             });
             if (!response.ok)
                 return false;
-            const data = await response.json();
-            return data.status === 'healthy';
+            const body = (await response.json());
+            return body.status === 'healthy';
         }
-        catch (error) {
+        catch {
             getContext().observability.breadcrumb('Health check failed', 'sync.bootstrap', 'warning');
             return false;
         }

package/dist/sync/ConnectionManager.d.ts

@@ -1,24 +1,18 @@
 /**
- * ConnectionManager — single source of truth for the sync engine's
- * connection lifecycle. Absorbs the FSM every SDK consumer used to
- * rebuild by hand (apps/web's `ConnectionStore` was the reference
- * implementation — 605 LOC of FSM + watchdog + backoff).
+ * Owns the sync engine's connection lifecycle: the state machine that carries a
+ * client from a healthy connection, through a dropout, and back to live. It
+ * watches the browser's online/offline and visibility events, probes real
+ * connectivity and session validity with {@link probeNetwork}, applies retry
+ * backoff with a ceiling and jitter, and runs a watchdog for the cases where
+ * the browser never fires an event (VPN flips, captive portals). When it
+ * decides to recover, it drives the reconnect sequence — bootstrap, then
+ * WebSocket connect — through the {@link ConnectionCallbacks.onReconnect}
+ * callback and reacts to the outcome.
  *
- * What it owns:
- *  - Browser online/offline + visibility events
- *  - Network probe orchestration (via `probeNetwork`)
- *  - Session-validity checks (HEAD /api/auth/check)
- *  - Retry backoff with ceiling, jitter, and offline-aware parking
- *  - Watchdog for browser events that never fire (VPN, captive portal)
- *  - The reconnect → bootstrap → WebSocket connect sequence
- *
- * What it DOES NOT own:
- *  - The actual bootstrap / IndexedDB / ObjectPool work — that lives in
- *    `BaseSyncedStore.performReconnect()`. This class calls it via the
- *    `onReconnect` callback and reacts to the outcome.
- *
- * Designed to be embedded by `BaseSyncedStore`: one instance per store,
- * started on first successful connect, disposed on teardown.
+ * It deliberately does not perform the bootstrap, local-storage, or object-pool
+ * work itself; that lives in the embedding store, which the manager reaches
+ * only through its callbacks. One manager is created per store, started on the
+ * first successful connect and disposed on teardown.
  *
  *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
  *        │                              │                  │
@@ -29,20 +23,15 @@
  *        ▼
  *   WAITING_FOR_NETWORK
  *
- * Includes three fixes over the original app-side FSM:
- *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
- *      probing immediately when the network comes back, without
- *      waiting for the backoff timer to elapse.
- *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
- *      `attempt`) when `navigator.onLine === false` at max retries,
- *      instead of hard-reloading an already-offline browser.
- *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
- *      STRAIGHT to `probing_network`, not the passive `offline` state.
- *      1006 is browser-local and carries no connectivity signal, so on a
- *      healthy machine no `online`/`offline` event ever fires — parking in
- *      `offline` stranded recovery until the 30s watchdog, long enough for
- *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
- *      parks in `offline` and waits for the `online` event.
+ * Three behaviors are worth calling out. A network return or tab focus during a
+ * backoff delay jumps straight to probing instead of waiting out the full
+ * interval. Reaching the retry ceiling while the browser reports offline parks
+ * in `waiting_for_network` rather than hard-reloading a browser that has no
+ * network. And a socket drop (close code 1006) goes straight to probing rather
+ * than the passive `offline` state — 1006 is generated locally and carries no
+ * connectivity signal, so on a healthy machine no online/offline event ever
+ * fires; only a genuine operating-system network loss parks in `offline` to
+ * wait for the `online` event.
  */
 import { type ProbeResult } from './NetworkProbe.js';
 import type { AuthTokenGetter } from '../auth/credentialSource.js';
@@ -93,17 +82,18 @@ export interface ConnectionCallbacks {
     /** Run bootstrap + WebSocket reconnect. Returns the outcome. */
     onReconnect: () => Promise<'success' | 'session_error' | 'network_error'>;
     /**
-     * Re-mint the short-lived access credential (the Stripe-style `ek_`/`rk_`)
-     * and push it into the credential source, then report the outcome. Invoked
-     * on `refreshing_credential` — i.e. when a probe found the access key stale
-     * (`PROBE_CREDENTIAL_STALE`). Mirrors the `getToken` contract:
-     *   - `'refreshed'`     → a fresh credential is in place; re-probe & reconnect.
-     *   - `'session_error'` → the LONG-LIVED login is gone (mint returned null →
-     *                          401/403); terminal → sign out.
-     *   - `'network_error'` → couldn't reach the mint endpoint (offline/5xx/throw);
-     *                          transient → back off and retry, never sign out.
-     * Optional: a deployment with no re-mint path (e.g. a static `apiKey`) omits
-     * it, and the FSM falls back to a plain re-probe.
+     * Re-mints the short-lived access credential (the `ek_`/`rk_`) and pushes it
+     * into the credential source, then reports the outcome. Invoked in the
+     * `refreshing_credential` state — that is, when a probe found the access key
+     * stale (`PROBE_CREDENTIAL_STALE`). The three outcomes map onto recovery:
+     *   - `'refreshed'`     → a fresh credential is in place; re-probe and reconnect.
+     *   - `'session_error'` → the long-lived login itself is gone (the mint
+     *                          returned null, a 401/403); terminal, so sign out.
+     *   - `'network_error'` → the mint endpoint was unreachable (offline, 5xx, or
+     *                          a throw); transient, so back off and retry rather
+     *                          than sign out.
+     * Optional: a deployment with no re-mint path (for example a static `apiKey`)
+     * omits it, and the state machine falls back to a plain re-probe.
      */
     onRefreshCredential?: () => Promise<'refreshed' | 'session_error' | 'network_error'>;
     /** Called when the session is confirmed expired — route to signin. */
@@ -111,12 +101,11 @@ export interface ConnectionCallbacks {
     /** Called to tear down the WebSocket when entering a dead state. */
     onDisconnectWebSocket: () => void;
     /**
-     * Fired on every FSM state transition. Lets the embedding store
-     * mirror recovery progress into its visible `syncStatus` so the UI
-     * can show "Reconnecting…" instead of a sticky "offline" while the
-     * FSM cycles through `probing_network` → `reconnecting` → `backoff`.
-     * Optional — omitting it preserves the previous behavior where the
-     * FSM was opaque to the UI.
+     * Fires on every state transition. It lets the embedding store mirror
+     * recovery progress into its visible `syncStatus`, so the UI can show
+     * "Reconnecting…" instead of a sticky "offline" while the machine cycles
+     * through `probing_network` → `reconnecting` → `backoff`. Optional; when
+     * omitted, the state machine is simply opaque to the UI.
      */
     onStateChange?: (next: ConnectionState, prev: ConnectionState) => void;
 }

package/dist/sync/ConnectionManager.js

@@ -1,24 +1,18 @@
 /**
- * ConnectionManager — single source of truth for the sync engine's
- * connection lifecycle. Absorbs the FSM every SDK consumer used to
- * rebuild by hand (apps/web's `ConnectionStore` was the reference
- * implementation — 605 LOC of FSM + watchdog + backoff).
+ * Owns the sync engine's connection lifecycle: the state machine that carries a
+ * client from a healthy connection, through a dropout, and back to live. It
+ * watches the browser's online/offline and visibility events, probes real
+ * connectivity and session validity with {@link probeNetwork}, applies retry
+ * backoff with a ceiling and jitter, and runs a watchdog for the cases where
+ * the browser never fires an event (VPN flips, captive portals). When it
+ * decides to recover, it drives the reconnect sequence — bootstrap, then
+ * WebSocket connect — through the {@link ConnectionCallbacks.onReconnect}
+ * callback and reacts to the outcome.
  *
- * What it owns:
- *  - Browser online/offline + visibility events
- *  - Network probe orchestration (via `probeNetwork`)
- *  - Session-validity checks (HEAD /api/auth/check)
- *  - Retry backoff with ceiling, jitter, and offline-aware parking
- *  - Watchdog for browser events that never fire (VPN, captive portal)
- *  - The reconnect → bootstrap → WebSocket connect sequence
- *
- * What it DOES NOT own:
- *  - The actual bootstrap / IndexedDB / ObjectPool work — that lives in
- *    `BaseSyncedStore.performReconnect()`. This class calls it via the
- *    `onReconnect` callback and reacts to the outcome.
- *
- * Designed to be embedded by `BaseSyncedStore`: one instance per store,
- * started on first successful connect, disposed on teardown.
+ * It deliberately does not perform the bootstrap, local-storage, or object-pool
+ * work itself; that lives in the embedding store, which the manager reaches
+ * only through its callbacks. One manager is created per store, started on the
+ * first successful connect and disposed on teardown.
  *
  *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
  *        │                              │                  │
@@ -29,20 +23,15 @@
  *        ▼
  *   WAITING_FOR_NETWORK
  *
- * Includes three fixes over the original app-side FSM:
- *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
- *      probing immediately when the network comes back, without
- *      waiting for the backoff timer to elapse.
- *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
- *      `attempt`) when `navigator.onLine === false` at max retries,
- *      instead of hard-reloading an already-offline browser.
- *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
- *      STRAIGHT to `probing_network`, not the passive `offline` state.
- *      1006 is browser-local and carries no connectivity signal, so on a
- *      healthy machine no `online`/`offline` event ever fires — parking in
- *      `offline` stranded recovery until the 30s watchdog, long enough for
- *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
- *      parks in `offline` and waits for the `online` event.
+ * Three behaviors are worth calling out. A network return or tab focus during a
+ * backoff delay jumps straight to probing instead of waiting out the full
+ * interval. Reaching the retry ceiling while the browser reports offline parks
+ * in `waiting_for_network` rather than hard-reloading a browser that has no
+ * network. And a socket drop (close code 1006) goes straight to probing rather
+ * than the passive `offline` state — 1006 is generated locally and carries no
+ * connectivity signal, so on a healthy machine no online/offline event ever
+ * fires; only a genuine operating-system network loss parks in `offline` to
+ * wait for the `online` event.
  */
 import { makeAutoObservable, runInAction } from 'mobx';
 import { getContext } from '../context.js';
@@ -158,13 +147,13 @@ export class ConnectionManager {
                         // work.
                         return 'offline';
                     case 'WS_DISCONNECTED':
-                        // The socket died (typically code 1006) but the OS network is
-                        // almost certainly fine — 1006 is generated locally when the TCP
-                        // conn vanishes and carries NO connectivity signal, so the browser
-                        // fires no online/offline event. Probe IMMEDIATELY rather than
-                        // landing in the passive `offline` dead-end (which only escaped via
-                        // the 30s watchdog, long after queued commits rolled back). The
-                        // probe fast-fails if we genuinely ARE offline → waiting_for_network.
+                        // The socket died (typically code 1006) but the operating-system
+                        // network is almost certainly fine — 1006 is generated locally when
+                        // the TCP connection vanishes and carries no connectivity signal, so
+                        // the browser fires no online/offline event. Probe immediately rather
+                        // than landing in the passive `offline` dead-end (which only escaped
+                        // via the 30s watchdog, long after queued commits rolled back). The
+                        // probe fast-fails if we genuinely are offline → waiting_for_network.
                         return 'probing_network';
                     case 'WS_SESSION_ERROR':
                     case 'BOOTSTRAP_FAILED_SESSION':
@@ -233,15 +222,15 @@ export class ConnectionManager {
                         return null;
                 }
             case 'refreshing_credential':
-                // Re-minting the short-lived access key (the Stripe-style `ek_`/`rk_`).
-                // The login is presumed valid; this is NOT a sign-out state.
+                // Re-minting the short-lived access key (the `ek_`/`rk_`). The login is
+                // presumed valid; this is not a sign-out state.
                 switch (event.type) {
                     case 'CREDENTIAL_REFRESHED':
                         // Fresh key in hand — re-probe so we reconnect with it.
                         return 'probing_network';
                     case 'BOOTSTRAP_FAILED_SESSION':
                         // The re-mint hit a genuine 401/403: the long-lived login itself is
-                        // gone. THIS is the only path from here to sign-out.
+                        // gone. This is the only path from here to sign-out.
                         return 'session_expired';
                     case 'RECONNECT_FAILED':
                         // Couldn't reach the mint endpoint (offline/5xx/throw) — transient.
@@ -336,15 +325,15 @@ export class ConnectionManager {
                 this.callbacks?.onDisconnectWebSocket();
                 break;
             case 'probing_network':
-                // A socket drop (`WS_DISCONNECTED`) now lands here directly so recovery
-                // starts immediately. Tear the dead socket down FIRST — this is what
+                // A socket drop (`WS_DISCONNECTED`) lands here directly so recovery
+                // starts immediately. Tear the dead socket down first — that is what
                 // sets SyncWebSocket's `isManualClose=true` and suppresses its own
-                // scheduleReconnect, keeping the FSM the single reconnect authority on
-                // the human path. The teardown runs synchronously inside the
-                // `disconnected` emit, before `SyncWebSocket.onclose` checks the flag,
-                // so the timing matches the previous `offline`-entry teardown. We gate
-                // on the drop event specifically: the other paths into `probing_network`
-                // (TAB_VISIBLE re-validation, handshake retry, backoff elapse) must NOT
+                // reconnect, keeping this machine the single reconnect authority on the
+                // human path. The teardown runs synchronously inside the `disconnected`
+                // emit, before `SyncWebSocket.onclose` checks the flag, so the timing
+                // matches the previous `offline`-entry teardown. We gate on the drop
+                // event specifically: the other paths into `probing_network`
+                // (tab-focus re-validation, handshake retry, backoff elapse) must not
                 // tear down a socket that may still be live.
                 if (event.type === 'WS_DISCONNECTED') {
                     this.callbacks?.onDisconnectWebSocket();
@@ -364,11 +353,12 @@ export class ConnectionManager {
                 this.scheduleBackoff();
                 break;
             case 'auth_blocked':
-                // Stop — reachable but the credential was rejected (e.g.
-                // api_key_required / jwt_issuer_untrusted from the data plane). Neither
-                // reconnecting nor re-auth fixes it. Drop the socket and wait for a
-                // manual retry / re-probe. Crucially NOT onSessionExpired (no sign-out)
-                // and NOT a reconnect — that's the whole point of this state.
+                // Stop here — the server is reachable but rejected the credential (for
+                // example api_key_required or jwt_issuer_untrusted from the data plane).
+                // Neither reconnecting nor re-authenticating fixes it. Drop the socket
+                // and wait for a manual retry or a re-probe. This deliberately does not
+                // call onSessionExpired (no sign-out) and does not reconnect — that is
+                // the whole point of the state.
                 this.clearBackoffTimer();
                 this.callbacks?.onDisconnectWebSocket();
                 getContext().observability.breadcrumb('Auth blocked — reachable but credential rejected; not reconnecting or signing out', 'sync.offline', 'error');
@@ -602,16 +592,15 @@ export class ConnectionManager {
         this.watchdogTimer = setInterval(() => {
             if (this.disposed)
                 return;
-            // "Stuck" = parked in a non-active recovery state (offline,
-            // waiting_for_network, backoff). We deliberately do NOT gate on
-            // `navigator.onLine === true` here: per MDN, `navigator.onLine`
-            // is only reliable when it returns false ("definitely offline"),
-            // and even that lies after laptop wake / VPN flips. Gating the
-            // watchdog on `onLine` was the actual "offline forever" bug —
-            // when the browser briefly reported offline and never re-fired
-            // the `online` event, the FSM had no escape from `'offline'`.
-            // The probe itself fast-fails when truly offline (NetworkProbe.ts),
-            // so an unconditional retry costs nothing in the genuine case.
+            // "Stuck" means parked in a non-active recovery state (offline,
+            // waiting_for_network, backoff). This deliberately does not gate on
+            // `navigator.onLine === true`: per MDN, `navigator.onLine` is only
+            // reliable when it returns false ("definitely offline"), and even that
+            // lies after laptop wake or VPN flips. Gating the watchdog on `onLine`
+            // was what stranded the machine in `offline` forever — when the browser
+            // briefly reported offline and never re-fired the `online` event, there
+            // was no escape. The probe itself fast-fails when truly offline, so an
+            // unconditional retry costs nothing in the genuine case.
             const isStuck = this.state !== 'connected' &&
                 this.state !== 'session_expired' &&
                 this.state !== 'probing_network' &&