nucleus-core-ts 0.9.992 → 0.9.993

package/dist/src/Client/ApiCaller/client.d.ts

@@ -1,4 +1,5 @@
 import type { ApiResponse, EndpointAction, EndpointDefinition } from './types';
+export declare function createActionsFacade<TActions extends object>(endpoints: Record<string, unknown>, buildAction: (key: string) => TActions[keyof TActions]): TActions;
 export declare function createApiHook<TEndpoints extends Record<string, EndpointDefinition>>(endpoints: TEndpoints, factory: <K extends keyof TEndpoints & string>(endpointKey: K, payload: TEndpoints[K]['_payload']) => Promise<ApiResponse<TEndpoints[K]['_success'], TEndpoints[K]['_error']>>): () => { [K in keyof TEndpoints]: EndpointAction<TEndpoints[K]["_payload"], TEndpoints[K]["_success"], TEndpoints[K]["_error"]>; };
 export type ApiHook<TEndpoints extends Record<string, EndpointDefinition>> = ReturnType<typeof createApiHook<TEndpoints>>;
 export type ApiActions<TEndpoints extends Record<string, EndpointDefinition>> = ReturnType<ApiHook<TEndpoints>>;

package/dist/src/Client/Proxy/httpProxy.js

@@ -135,11 +135,11 @@ function appendSetCookieHeaders(responseHeaders, setCookieHeaders) {
         responseHeaders.append('Set-Cookie', cookie);
     }
 }
-/**
- * Preserve individual Set-Cookie headers when copying via new Headers().
- * new Headers(response.headers) may combine multiple Set-Cookie headers
- * into a single comma-separated value — browsers cannot parse this for
- * Set-Cookie (RFC 6265). This function re-adds them individually.
+/**
+ * Preserve individual Set-Cookie headers when copying via new Headers().
+ * new Headers(response.headers) may combine multiple Set-Cookie headers
+ * into a single comma-separated value — browsers cannot parse this for
+ * Set-Cookie (RFC 6265). This function re-adds them individually.
  */ function preserveSetCookieHeaders(target, source) {
     const setCookies = typeof source.getSetCookie === 'function' ? source.getSetCookie() : [];
     if (setCookies.length > 1) {
@@ -149,10 +149,10 @@ function appendSetCookieHeaders(responseHeaders, setCookieHeaders) {
         }
     }
 }
-/**
- * Resolve the user id to inject as x-user-id from a bearer token, or null if it can't be
- * TRUSTED. Fail-closed: returns null unless BOTH a secret and a token are present AND the token
- * passes HS256 signature + expiry verification. Never trusts a bare/forged/unsigned token.
+/**
+ * Resolve the user id to inject as x-user-id from a bearer token, or null if it can't be
+ * TRUSTED. Fail-closed: returns null unless BOTH a secret and a token are present AND the token
+ * passes HS256 signature + expiry verification. Never trusts a bare/forged/unsigned token.
  */ export function resolveInjectedUserId(token, secret) {
     if (!secret || !token) return null;
     const payload = verifyJwtHS256(token, secret);
@@ -179,9 +179,9 @@ export function createHttpProxyHandler(config) {
             }
         }
     }
-    /**
-   * Claim-gate a request for a target. Returns a 403 Response to block (enforce
-   * mode), or null to allow (also null in audit mode, where a would-block is logged).
+    /**
+   * Claim-gate a request for a target. Returns a 403 Response to block (enforce
+   * mode), or null to allow (also null in audit mode, where a would-block is logged).
    */ async function checkAuthorize(req, target, path) {
         const az = target.authorize;
         if (!az) return null;
@@ -369,30 +369,30 @@ export function createHttpProxyHandler(config) {
     function injectToken(headers, token, headerName) {
         headers.set(headerName, `Bearer ${token}`);
     }
-    /**
-   * Forward one request upstream, bounded by BOTH clocks that can end it.
-   *
-   * The timeout below only bounds time-to-first-headers: it is cleared the
-   * moment headers arrive, because a streamed body (SSE, a long download, a
-   * model's token stream) legitimately takes as long as it takes. That is
-   * correct — but on its own it left a streamed request with NO way to end.
-   *
-   * So when the person closed the tab, the browser's connection went away and
-   * ours did not. The upstream request stayed open, holding one of the
-   * runtime's outgoing connection slots, forever.
-   *
-   * That is not a slow leak. Measured on Bun 1.3.14: 256 clients that connect
-   * and hang up leave 256 upstream requests open (0 cancelled), and the process
-   * can then make no outgoing request at all — every later fetch times out.
-   * A single tab reconnecting an EventSource 256 times does it alone.
-   *
-   * Cancelling the body we hand back (`body.cancel()`) does NOT release the
-   * slot; only aborting the upstream fetch does. Measured both ways.
-   *
-   * Hence `clientSignal`: the client's hangup is wired to the same controller
-   * the timeout uses, so whichever ends first ends the upstream request. The
-   * listener is left attached deliberately — it belongs to this one request and
-   * is collected with it, and aborting an already-finished fetch is a no-op.
+    /**
+   * Forward one request upstream, bounded by BOTH clocks that can end it.
+   *
+   * The timeout below only bounds time-to-first-headers: it is cleared the
+   * moment headers arrive, because a streamed body (SSE, a long download, a
+   * model's token stream) legitimately takes as long as it takes. That is
+   * correct — but on its own it left a streamed request with NO way to end.
+   *
+   * So when the person closed the tab, the browser's connection went away and
+   * ours did not. The upstream request stayed open, holding one of the
+   * runtime's outgoing connection slots, forever.
+   *
+   * That is not a slow leak. Measured on Bun 1.3.14: 256 clients that connect
+   * and hang up leave 256 upstream requests open (0 cancelled), and the process
+   * can then make no outgoing request at all — every later fetch times out.
+   * A single tab reconnecting an EventSource 256 times does it alone.
+   *
+   * Cancelling the body we hand back (`body.cancel()`) does NOT release the
+   * slot; only aborting the upstream fetch does. Measured both ways.
+   *
+   * Hence `clientSignal`: the client's hangup is wired to the same controller
+   * the timeout uses, so whichever ends first ends the upstream request. The
+   * listener is left attached deliberately — it belongs to this one request and
+   * is collected with it, and aborting an already-finished fetch is a no-op.
    */ async function forwardRequest(finalUrl, method, headers, body, timeout, followRedirects, clientSignal) {
         const controller = new AbortController();
         const timeoutId = setTimeout(()=>controller.abort(), timeout);
@@ -408,13 +408,13 @@ export function createHttpProxyHandler(config) {
                     clientGone = true;
                     clearTimeout(timeoutId);
                     controller.abort();
-                    /*
-             * Logged HERE, not in the catch below, because the common case
-             * never reaches the catch: once headers have arrived this function
-             * has already returned, and the hangup happens while the body is
-             * still streaming. That is exactly the case that used to leak, so
-             * it is exactly the case that has to be visible — a cancellation
-             * nobody can see is how this went unnoticed for months.
+                    /*
+             * Logged HERE, not in the catch below, because the common case
+             * never reaches the catch: once headers have arrived this function
+             * has already returned, and the hangup happens while the body is
+             * still streaming. That is exactly the case that used to leak, so
+             * it is exactly the case that has to be visible — a cancellation
+             * nobody can see is how this went unnoticed for months.
              */ logger.info(`Client disconnected, upstream cancelled: ${finalUrl}`);
                 }, {
                     once: true
@@ -508,15 +508,15 @@ export function createHttpProxyHandler(config) {
                         status: 401,
                         headers: {
                             'Content-Type': 'application/json',
-                            /*
-                 * This 401 is OURS, not the API's. The API was never asked —
-                 * the refresh call to it is what failed, and it fails for the
-                 * same reason everything else does when the backend is down.
-                 *
-                 * Saying so matters: a client that reads an unqualified 401 as
-                 * "your session is over" turns one pod restart into a sign-in
-                 * prompt for somebody whose session has six more days on it.
-                 * That is exactly what happened to the realtime bar.
+                            /*
+                 * This 401 is OURS, not the API's. The API was never asked —
+                 * the refresh call to it is what failed, and it fails for the
+                 * same reason everything else does when the backend is down.
+                 *
+                 * Saying so matters: a client that reads an unqualified 401 as
+                 * "your session is over" turns one pod restart into a sign-in
+                 * prompt for somebody whose session has six more days on it.
+                 * That is exactly what happened to the realtime bar.
                  */ [SYNTHESIZED_AUTH_HEADER]: 'refresh-failed'
                         }
                     });
@@ -530,30 +530,30 @@ export function createHttpProxyHandler(config) {
                 logger.warn(`[Auth:proxy] NO TOKEN available for ${path} — request will likely fail with 401`);
             }
             const baseTimeout = target.timeout ?? 30000;
-            /*
-       * A file needs minutes, not thirty seconds.
-       *
-       * The fixed timeout aborted a 200 MB video long before the last byte, and
-       * the browser had no way to tell that from a slow line — the bar simply
-       * stopped. The allowance now grows with the declared size.
+            /*
+       * A file needs minutes, not thirty seconds.
+       *
+       * The fixed timeout aborted a 200 MB video long before the last byte, and
+       * the browser had no way to tell that from a slow line — the bar simply
+       * stopped. The allowance now grows with the declared size.
        */ const timeout = timeoutForBody(req.headers, baseTimeout);
             const followRedirects = target.followRedirects !== false;
             // Buffer body for potential retry (only if 401 retry is enabled)
             let bodyForRetry = null;
             let bodyToSend = req.body;
-            /*
-       * Only a body small enough to hold.
-       *
-       * Buffering exists so a 401 can be answered by refreshing the token and
-       * sending the same request again — worth it for a form post, fatal for a
-       * file. An 800 MB video was read into an ArrayBuffer inside a container
-       * limited to 256 MiB: the upload appeared to run, because the browser
-       * really was sending bytes, and then died with nothing to show for it.
-       *
-       * A large body streams straight through and gives up the retry. That is
-       * the right way round: an upload that is refused can be started again by
-       * the person who chose the file; an upload that never completes cannot be
-       * rescued by anybody.
+            /*
+       * Only a body small enough to hold.
+       *
+       * Buffering exists so a 401 can be answered by refreshing the token and
+       * sending the same request again — worth it for a form post, fatal for a
+       * file. An 800 MB video was read into an ArrayBuffer inside a container
+       * limited to 256 MiB: the upload appeared to run, because the browser
+       * really was sending bytes, and then died with nothing to show for it.
+       *
+       * A large body streams straight through and gives up the retry. That is
+       * the right way round: an upload that is refused can be started again by
+       * the person who chose the file; an upload that never completes cannot be
+       * rescued by anybody.
        */ const bufferable = canBufferForRetry(req.headers);
             if (refreshEnabled && (refreshConfig.retryOn401 ?? true) && req.body && bufferable) {
                 try {
@@ -605,15 +605,15 @@ export function createHttpProxyHandler(config) {
                         status: 401,
                         headers: {
                             'Content-Type': 'application/json',
-                            /*
-                 * This 401 is OURS, not the API's. The API was never asked —
-                 * the refresh call to it is what failed, and it fails for the
-                 * same reason everything else does when the backend is down.
-                 *
-                 * Saying so matters: a client that reads an unqualified 401 as
-                 * "your session is over" turns one pod restart into a sign-in
-                 * prompt for somebody whose session has six more days on it.
-                 * That is exactly what happened to the realtime bar.
+                            /*
+                 * This 401 is OURS, not the API's. The API was never asked —
+                 * the refresh call to it is what failed, and it fails for the
+                 * same reason everything else does when the backend is down.
+                 *
+                 * Saying so matters: a client that reads an unqualified 401 as
+                 * "your session is over" turns one pod restart into a sign-in
+                 * prompt for somebody whose session has six more days on it.
+                 * That is exactly what happened to the realtime bar.
                  */ [SYNTHESIZED_AUTH_HEADER]: 'refresh-failed'
                         }
                     });
@@ -637,14 +637,14 @@ export function createHttpProxyHandler(config) {
             } catch (error) {
                 const duration = performance.now() - startTime;
                 const err = error instanceof Error ? error : new Error(String(error));
-                /*
-         * The person closed the tab. Nothing failed, and there is nobody left
-         * to send a status to — so this is not an error, and calling it one
-         * sends whoever reads the log hunting a timeout that never happened.
-         *
-         * Reported with the elapsed time, because on a streaming path "the
-         * client left after 4 minutes" is genuinely useful and "Gateway
-         * Timeout" is genuinely misleading.
+                /*
+         * The person closed the tab. Nothing failed, and there is nobody left
+         * to send a status to — so this is not an error, and calling it one
+         * sends whoever reads the log hunting a timeout that never happened.
+         *
+         * Reported with the elapsed time, because on a streaming path "the
+         * client left after 4 minutes" is genuinely useful and "Gateway
+         * Timeout" is genuinely misleading.
          */ if (err.name === 'ClientGoneError') {
                     logger.info(`Client disconnected after ${duration.toFixed(0)}ms, upstream cancelled: ${path}`);
                     return new Response(null, {

package/dist/src/Client/Proxy/synthesizedAuth.js

@@ -1,11 +1,11 @@
-/**
- * How a client tells "the API refused you" from "we could not ask".
- *
- * A proxy that refreshes tokens on the way through has to answer something when
- * the refresh itself fails, and 401 is the honest status — the request cannot
- * be authorised. But the CAUSE is usually that the backend is unreachable, and
- * a client that reads it as "this session is over" turns one pod restart into a
- * sign-in prompt for somebody whose session has six more days on it.
- *
- * So the proxy stamps the 401s it invented. An unstamped 401 came from the API.
+/**
+ * How a client tells "the API refused you" from "we could not ask".
+ *
+ * A proxy that refreshes tokens on the way through has to answer something when
+ * the refresh itself fails, and 401 is the honest status — the request cannot
+ * be authorised. But the CAUSE is usually that the backend is unreachable, and
+ * a client that reads it as "this session is over" turns one pod restart into a
+ * sign-in prompt for somebody whose session has six more days on it.
+ *
+ * So the proxy stamps the 401s it invented. An unstamped 401 came from the API.
  */ export const SYNTHESIZED_AUTH_HEADER = 'x-nucleus-auth-synthesized';

package/dist/src/Client/Proxy/wsProxy.js

@@ -1,9 +1,9 @@
 import { deduplicatedRefresh } from './httpProxy';
 import { addQueryParam, createProxyLogger, httpToWs, matchPath, parseCookies, rewritePath } from './utils';
-/**
- * True when an access token is absent or within `skewMs` of expiring. Decodes the JWT
- * exp WITHOUT verifying (verification happens at the backend) — this only decides whether
- * to pre-emptively refresh before the WS handshake.
+/**
+ * True when an access token is absent or within `skewMs` of expiring. Decodes the JWT
+ * exp WITHOUT verifying (verification happens at the backend) — this only decides whether
+ * to pre-emptively refresh before the WS handshake.
  */ function accessTokenExpiringSoon(token, skewMs = 60000) {
     if (!token) return true;
     try {
@@ -16,20 +16,20 @@ import { addQueryParam, createProxyLogger, httpToWs, matchPath, parseCookies, re
         return true;
     }
 }
-/**
- * Keeps the proxy→backend socket alive with a PROTOCOL ping, not a data frame.
- *
- * This used to send `''`. An empty text frame is still application data, so it
- * arrived at the backend's `message` handler, where `JSON.parse('')` throws —
- * and nucleus' own PubSub route logged "Failed to parse client message" once per
- * interval per connected client. On a busy IDP that is the entire debug log, and
- * it names the proxy's own heartbeat as a misbehaving client.
- *
- * `ping()` is a control frame: it never reaches `message`, the peer answers with
- * pong automatically, and it resets the idle timer the same way. Bun's WebSocket
- * client implements it; the JSON heartbeat is the fallback for a runtime that
- * does not, because `{"type":"ping"}` is a frame the PubSub route understands and
- * replies to, rather than one it can only fail to parse.
+/**
+ * Keeps the proxy→backend socket alive with a PROTOCOL ping, not a data frame.
+ *
+ * This used to send `''`. An empty text frame is still application data, so it
+ * arrived at the backend's `message` handler, where `JSON.parse('')` throws —
+ * and nucleus' own PubSub route logged "Failed to parse client message" once per
+ * interval per connected client. On a busy IDP that is the entire debug log, and
+ * it names the proxy's own heartbeat as a misbehaving client.
+ *
+ * `ping()` is a control frame: it never reaches `message`, the peer answers with
+ * pong automatically, and it resets the idle timer the same way. Bun's WebSocket
+ * client implements it; the JSON heartbeat is the fallback for a runtime that
+ * does not, because `{"type":"ping"}` is a frame the PubSub route understands and
+ * replies to, rather than one it can only fail to parse.
  */ function pingBackend(backendWs) {
     const withPing = backendWs;
     if (typeof withPing.ping === 'function') {
@@ -51,14 +51,14 @@ export function createWsProxyHandler(config) {
         }
         return null;
     }
-    /**
-   * The backend URL, plus whether this handshake carries a credential at all.
-   *
-   * The second half is the point. This function already KNEW when it had no
-   * token — it logged "No token found" and handed back a URL anyway, and the
-   * caller upgraded the socket regardless. That silence is what turns one
-   * logged-out browser tab into a permanent reconnect storm; see the refusal in
-   * `upgrade()` for the measurements.
+    /**
+   * The backend URL, plus whether this handshake carries a credential at all.
+   *
+   * The second half is the point. This function already KNEW when it had no
+   * token — it logged "No token found" and handed back a URL anyway, and the
+   * caller upgraded the socket regardless. That silence is what turns one
+   * logged-out browser tab into a permanent reconnect storm; see the refusal in
+   * `upgrade()` for the measurements.
    */ async function buildBackendUrl(path, target, cookies, query) {
         let baseUrl = target.url.replace(/\/$/, '');
         if (baseUrl.startsWith('http')) {
@@ -244,21 +244,21 @@ export function createWsProxyHandler(config) {
                         rejectUnauthorized: state.rejectUnauthorized
                     }
                 });
-                /*
-         * Ask for ArrayBuffer, because the default is not one.
-         *
-         * Bun's client WebSocket defaults `binaryType` to `'nodebuffer'`, so a
-         * binary frame arrives as a Node `Buffer`. A Buffer is neither an
-         * `ArrayBuffer` nor a `Blob`, so it matched none of the branches below
-         * and was silently discarded — a proxy that relays text perfectly and
-         * drops every binary frame without a word.
-         *
-         * Measured against a Next 16 dev server, which sends its React debug
-         * chunks as binary on the HMR socket: 5 frames direct, 2 of them
-         * binary; 3 frames through the proxy, 0 binary. The consequence was a
-         * page that never hydrated at all — the client awaits those chunks
-         * before calling `hydrateRoot`, so the whole app stayed as the server
-         * had sent it, blank.
+                /*
+         * Ask for ArrayBuffer, because the default is not one.
+         *
+         * Bun's client WebSocket defaults `binaryType` to `'nodebuffer'`, so a
+         * binary frame arrives as a Node `Buffer`. A Buffer is neither an
+         * `ArrayBuffer` nor a `Blob`, so it matched none of the branches below
+         * and was silently discarded — a proxy that relays text perfectly and
+         * drops every binary frame without a word.
+         *
+         * Measured against a Next 16 dev server, which sends its React debug
+         * chunks as binary on the HMR socket: 5 frames direct, 2 of them
+         * binary; 3 frames through the proxy, 0 binary. The consequence was a
+         * page that never hydrated at all — the client awaits those chunks
+         * before calling `hydrateRoot`, so the whole app stayed as the server
+         * had sent it, blank.
          */ backendWs.binaryType = 'arraybuffer';
                 backendWs.onopen = ()=>{
                     logger.info(`Backend connected: ${state.path}`);

package/dist/src/Client/PubSub/usePubSub.js

@@ -16,13 +16,13 @@ function buildWsUrl(config) {
     const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
     return `${protocol}//${window.location.host}${path}${query}`;
 }
-/**
- * One WebSocket per distinct URL, shared across every `usePubSub` caller via
- * ref-counting. Previously each hook instance opened its own socket, so two
- * components subscribing for the same user (e.g. the header bell and the chat
- * panel) created competing connections — the server de-dupes by user, dropping
- * one and breaking realtime delivery (and the message chime). Sharing a single
- * socket eliminates that and the duplicate events it produced.
+/**
+ * One WebSocket per distinct URL, shared across every `usePubSub` caller via
+ * ref-counting. Previously each hook instance opened its own socket, so two
+ * components subscribing for the same user (e.g. the header bell and the chat
+ * panel) created competing connections — the server de-dupes by user, dropping
+ * one and breaking realtime delivery (and the message chime). Sharing a single
+ * socket eliminates that and the duplicate events it produced.
  */ const connections = new Map();
 let eventIdCounter = 0;
 function log(conn, ...args) {
@@ -64,19 +64,19 @@ function startHeartbeat(conn) {
         }
     }, conn.options.heartbeatInterval);
 }
-/**
- * How many refused handshakes in a row before the client stops trying.
- *
- * Small on purpose: a refused handshake is a session problem, and the second
- * attempt tells you the first was not a fluke. Anything beyond that is a storm.
+/**
+ * How many refused handshakes in a row before the client stops trying.
+ *
+ * Small on purpose: a refused handshake is a session problem, and the second
+ * attempt tells you the first was not a fluke. Anything beyond that is a storm.
  */ const HANDSHAKE_FAILURE_LIMIT = 3;
-/**
- * Find out whether the session is actually gone before saying so.
- *
- * A 401 or 403 is the server telling us in words. Anything else — a 200, a 500,
- * a network failure — is not evidence about the session, so the connection goes
- * back to reconnecting and the screen keeps saying "reconnecting", which is
- * both true and not alarming.
+/**
+ * Find out whether the session is actually gone before saying so.
+ *
+ * A 401 or 403 is the server telling us in words. Anything else — a 200, a 500,
+ * a network failure — is not evidence about the session, so the connection goes
+ * back to reconnecting and the screen keeps saying "reconnecting", which is
+ * both true and not alarming.
  */ async function confirmSessionThenDecide(conn) {
     const path = conn.options.sessionProbePath;
     if (!path) {
@@ -93,15 +93,15 @@ function startHeartbeat(conn) {
             method: 'GET'
         });
         if (res.status === 401 || res.status === 403) {
-            /*
-       * Only if the API itself said so.
-       *
-       * A proxy that refreshes tokens on the way through answers 401 when the
-       * REFRESH fails, and refresh fails for the same reason the socket did —
-       * the API is restarting. Believing that 401 turns one pod roll into
-       * "oturumunuz artık geçerli değil" on a session that is perfectly alive,
-       * which is the original defect wearing a new hat. The proxy marks its
-       * own 401s; see NUCLEUS_SYNTHESIZED_AUTH_HEADER.
+            /*
+       * Only if the API itself said so.
+       *
+       * A proxy that refreshes tokens on the way through answers 401 when the
+       * REFRESH fails, and refresh fails for the same reason the socket did —
+       * the API is restarting. Believing that 401 turns one pod roll into
+       * "oturumunuz artık geçerli değil" on a session that is perfectly alive,
+       * which is the original defect wearing a new hat. The proxy marks its
+       * own 401s; see NUCLEUS_SYNTHESIZED_AUTH_HEADER.
        */ if (res.headers.get(SYNTHESIZED_AUTH_HEADER)) {
                 log(conn, 'Probe 401 came from the proxy, not the API; treating as a network problem');
             } else {
@@ -124,10 +124,10 @@ function startHeartbeat(conn) {
     conn.handshakeFailures = 0;
     scheduleReconnect(conn);
 }
-/**
- * Stop retrying on a clock; start again when something real changes.
- *
- * See `armReturnListeners` for why this is two listeners and not a timer.
+/**
+ * Stop retrying on a clock; start again when something real changes.
+ *
+ * See `armReturnListeners` for why this is two listeners and not a timer.
  */ function waitForReturn(conn) {
     if (typeof window === 'undefined' || typeof document === 'undefined') return;
     // A connection nobody holds any more must not be woken; the probe that armed
@@ -151,15 +151,15 @@ function scheduleReconnect(conn) {
     if (!conn.options.autoReconnect) return;
     if (connections.get(conn.url) !== conn) return;
     if (conn.reconnectAttempt >= conn.options.maxReconnectAttempts) {
-        /*
-     * Out of attempts — but "out of attempts" used to mean "dead until the
-     * person reloads the page". Ten tries with the backoff above is about three
-     * minutes, so a closed laptop, a lunch break or a deploy that takes a while
-     * left realtime permanently off while the page still looked alive.
-     *
-     * Waiting is right; giving up is not. So stop retrying on a timer (that is
-     * what caused the storm) and instead wait for an event that says the world
-     * changed: the network came back, or the person looked at the tab again.
+        /*
+     * Out of attempts — but "out of attempts" used to mean "dead until the
+     * person reloads the page". Ten tries with the backoff above is about three
+     * minutes, so a closed laptop, a lunch break or a deploy that takes a while
+     * left realtime permanently off while the page still looked alive.
+     *
+     * Waiting is right; giving up is not. So stop retrying on a timer (that is
+     * what caused the storm) and instead wait for an event that says the world
+     * changed: the network came back, or the person looked at the tab again.
      */ conn.dispatch.setConnectionStatus('disconnected');
         conn.dispatch.setError(new Error('Max reconnection attempts reached'));
         log(conn, 'Max reconnect attempts reached; waiting for network or tab to return');
@@ -242,21 +242,21 @@ function openSocket(conn) {
     ws.onopen = ()=>{
         log(conn, 'WebSocket opened');
         opened = true;
-        /*
-     * The counters are NOT reset here, and that is the point.
-     *
-     * "The socket opened" proves nothing when there is a proxy in front: the
-     * proxy upgrades the browser's socket first and dials the backend after,
-     * so a handshake the backend refuses still reaches `onopen`, and the
-     * server's own refusal arrives afterwards as close code 4001. Resetting
-     * here meant every such cycle set `reconnectAttempt` back to 0 — the
-     * backoff never grew past its first step and the attempt cap was never
-     * reached. Simulated against this module's control flow: one hour, one
-     * tab, 3496 socket attempts at a flat ~1030 ms, forever.
-     *
-     * The honest signal is the server's `connected` message, which only
-     * arrives once it has actually registered the client. `handleMessage`
-     * resets both there.
+        /*
+     * The counters are NOT reset here, and that is the point.
+     *
+     * "The socket opened" proves nothing when there is a proxy in front: the
+     * proxy upgrades the browser's socket first and dials the backend after,
+     * so a handshake the backend refuses still reaches `onopen`, and the
+     * server's own refusal arrives afterwards as close code 4001. Resetting
+     * here meant every such cycle set `reconnectAttempt` back to 0 — the
+     * backoff never grew past its first step and the attempt cap was never
+     * reached. Simulated against this module's control flow: one hour, one
+     * tab, 3496 socket attempts at a flat ~1030 ms, forever.
+     *
+     * The honest signal is the server's `connected` message, which only
+     * arrives once it has actually registered the client. `handleMessage`
+     * resets both there.
      */ startHeartbeat(conn);
     };
     ws.onmessage = (event)=>handleMessage(conn, event.data);
@@ -273,21 +273,21 @@ function openSocket(conn) {
         conn.dispatch.setConnectionStatus('disconnected');
         conn.dispatch.setClientId(null);
         if (connections.get(conn.url) !== conn) return;
-        /*
-     * 4001 = the backend refused the handshake's bearer. That is NOT the same
-     * as "the session is over", and treating it as such is why a live session
-     * stopped receiving messages.
-     *
-     * The handshake bearer is the SHORT-LIVED access token, while the session
-     * itself can be configured to never expire. An access token that aged out
-     * — because the tab sat idle, or the pre-handshake refresh at the proxy
-     * happened to fail once — produces exactly this 4001 while the person is
-     * still perfectly signed in.
-     *
-     * The probe is the right answer twice over: it tells us the truth, and it
-     * REPAIRS this case on the way, because the same proxy that serves it
-     * exchanges the refresh cookie for a fresh access token. So by the time the
-     * next handshake goes out, the bearer it carries is a new one.
+        /*
+     * 4001 = the backend refused the handshake's bearer. That is NOT the same
+     * as "the session is over", and treating it as such is why a live session
+     * stopped receiving messages.
+     *
+     * The handshake bearer is the SHORT-LIVED access token, while the session
+     * itself can be configured to never expire. An access token that aged out
+     * — because the tab sat idle, or the pre-handshake refresh at the proxy
+     * happened to fail once — produces exactly this 4001 while the person is
+     * still perfectly signed in.
+     *
+     * The probe is the right answer twice over: it tells us the truth, and it
+     * REPAIRS this case on the way, because the same proxy that serves it
+     * exchanges the refresh cookie for a fresh access token. So by the time the
+     * next handshake goes out, the bearer it carries is a new one.
      */ if (event.code === 4001) {
             log(conn, 'Handshake bearer refused (4001); asking whether the session is still valid');
             void confirmSessionThenDecide(conn);
@@ -296,25 +296,25 @@ function openSocket(conn) {
         if (!opened) {
             conn.handshakeFailures += 1;
             if (conn.handshakeFailures >= HANDSHAKE_FAILURE_LIMIT) {
-                /*
-         * This used to declare the session over. It was wrong, and people saw
-         * it: `!opened` only says the socket never came up, and a socket fails
-         * to come up for a dozen reasons that have nothing to do with the
-         * session — the API pod restarting (which some installs do every few
-         * hours), a deploy, a laptop waking, a wifi hiccup. Three of those in a
-         * row and the screen told the person their session had expired. It had
-         * not, and on an install running sessions that never expire the
-         * sentence was not even possible.
-         *
-         * The close code cannot settle it either: a handshake refused before
-         * the upgrade reaches the browser as 1006, exactly like a network drop.
-         *
-         * So: ASK, then say. One cheap cookie-authenticated request answers the
-         * only question that matters, and until it answers, nobody is told
-         * anything about their session.
-         *
-         * Server load was never the reason for this branch anyway — the backoff
-         * and the attempt cap above already bound the retries.
+                /*
+         * This used to declare the session over. It was wrong, and people saw
+         * it: `!opened` only says the socket never came up, and a socket fails
+         * to come up for a dozen reasons that have nothing to do with the
+         * session — the API pod restarting (which some installs do every few
+         * hours), a deploy, a laptop waking, a wifi hiccup. Three of those in a
+         * row and the screen told the person their session had expired. It had
+         * not, and on an install running sessions that never expire the
+         * sentence was not even possible.
+         *
+         * The close code cannot settle it either: a handshake refused before
+         * the upgrade reaches the browser as 1006, exactly like a network drop.
+         *
+         * So: ASK, then say. One cheap cookie-authenticated request answers the
+         * only question that matters, and until it answers, nobody is told
+         * anything about their session.
+         *
+         * Server load was never the reason for this branch anyway — the backoff
+         * and the attempt cap above already bound the retries.
          */ void confirmSessionThenDecide(conn);
                 return;
             }
@@ -393,13 +393,13 @@ export function usePubSub(config) {
     return {
         isConnected: store.connection.status === 'connected',
         isConnecting: store.connection.status === 'connecting' || store.connection.status === 'reconnecting',
-        /**
-     * The session is over and realtime will not return on its own.
-     *
-     * Exposed as its own flag so a screen can say so. Without it the page keeps
-     * its live appearance and quietly delivers nothing — which is worse than
-     * the reconnect storm this replaced, because at least the storm was visible
-     * to somebody.
+        /**
+     * The session is over and realtime will not return on its own.
+     *
+     * Exposed as its own flag so a screen can say so. Without it the page keeps
+     * its live appearance and quietly delivers nothing — which is worse than
+     * the reconnect storm this replaced, because at least the storm was visible
+     * to somebody.
      */ sessionExpired: store.connection.status === 'unauthorized',
         clientId: store.connection.clientId,
         subscribedTopics: store.connection.subscribedTopics,