@fuzdev/fuz_app 0.27.0 → 0.28.0

package/dist/actions/register_action_ws.d.ts

@@ -1,5 +1,11 @@
 /**
- * WebSocket JSON-RPC dispatch — the canonical WS transport binding.
+ * WebSocket JSON-RPC dispatch — the low-level WS transport binding.
+ *
+ * Most consumers should mount WS endpoints via `register_ws_endpoint`
+ * (`./register_ws_endpoint.js`), which wraps this function with the standard
+ * upgrade stack (origin check + auth + optional role). This module stays
+ * exported as the lower-level entry point for tests that drive the
+ * dispatcher directly via `create_ws_test_harness`.
  *
  * Symmetric to `create_rpc_endpoint` (from `actions/action_rpc.ts`):
  * consumer supplies action specs + a handler map, the dispatcher parses the
@@ -15,9 +21,10 @@
  * ## Auth expectations
  *
  * The consumer is responsible for rejecting unauthenticated upgrades *before*
- * routing to this handler (fuz_app's `require_auth` middleware). Inside the
- * dispatcher, `get_request_context(c)` is treated as guaranteed non-null and
- * per-action auth is enforced on each message.
+ * routing to this handler (fuz_app's `require_auth` middleware, or
+ * `register_ws_endpoint` which wires it for you). Inside the dispatcher,
+ * `get_request_context(c)` is treated as guaranteed non-null and per-action
+ * auth is enforced on each message.
  *
  * @module
  */

package/dist/actions/register_action_ws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAgB1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AAErC,OAAO,EAAC,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAG7F,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F,YAAY,EAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAC,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA8WF,CAAC"}
+{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAgB1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AAErC,OAAO,EAAC,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAG7F,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F,YAAY,EAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAC,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA8WF,CAAC"}

package/dist/actions/register_action_ws.js

@@ -1,5 +1,11 @@
 /**
- * WebSocket JSON-RPC dispatch — the canonical WS transport binding.
+ * WebSocket JSON-RPC dispatch — the low-level WS transport binding.
+ *
+ * Most consumers should mount WS endpoints via `register_ws_endpoint`
+ * (`./register_ws_endpoint.js`), which wraps this function with the standard
+ * upgrade stack (origin check + auth + optional role). This module stays
+ * exported as the lower-level entry point for tests that drive the
+ * dispatcher directly via `create_ws_test_harness`.
  *
  * Symmetric to `create_rpc_endpoint` (from `actions/action_rpc.ts`):
  * consumer supplies action specs + a handler map, the dispatcher parses the
@@ -15,9 +21,10 @@
  * ## Auth expectations
  *
  * The consumer is responsible for rejecting unauthenticated upgrades *before*
- * routing to this handler (fuz_app's `require_auth` middleware). Inside the
- * dispatcher, `get_request_context(c)` is treated as guaranteed non-null and
- * per-action auth is enforced on each message.
+ * routing to this handler (fuz_app's `require_auth` middleware, or
+ * `register_ws_endpoint` which wires it for you). Inside the dispatcher,
+ * `get_request_context(c)` is treated as guaranteed non-null and per-action
+ * auth is enforced on each message.
  *
  * @module
  */

package/dist/actions/register_ws_endpoint.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Composed WebSocket endpoint registration — the idiomatic consumer entry
+ * point for mounting a fuz_app WS endpoint.
+ *
+ * Wraps the standard upgrade stack every consumer writes by hand:
+ *
+ * 1. `verify_request_source(allowed_origins)` — reject disallowed origins
+ *    before the upgrade handshake runs.
+ * 2. `require_auth` — reject unauthenticated upgrades.
+ * 3. Optional `require_role(required_role)` — for endpoints gated to a
+ *    specific role.
+ *
+ * Then delegates to {@link register_action_ws} for per-message JSON-RPC
+ * dispatch.
+ *
+ * @module
+ */
+import type { RoleName } from '../auth/role_schema.js';
+import { type RegisterActionWsOptions, type RegisterActionWsResult } from './register_action_ws.js';
+import type { BaseHandlerContext } from './action_types.js';
+/** Options for {@link register_ws_endpoint}. */
+export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> extends RegisterActionWsOptions<TCtx> {
+    /**
+     * Origin allowlist regexes — typically parsed from the `ALLOWED_ORIGINS`
+     * env var via `parse_allowed_origins`. Passed straight to
+     * `verify_request_source`.
+     */
+    allowed_origins: Array<RegExp>;
+    /**
+     * Role required to upgrade. Omit for any authenticated account (`require_auth`
+     * alone); set to e.g. `ROLE_ADMIN` to gate the endpoint behind a role. The
+     * per-action `auth` in each spec still applies at dispatch time — this is
+     * a coarse upgrade-time gate.
+     */
+    required_role?: RoleName;
+}
+/**
+ * Mount a WebSocket endpoint with the standard upgrade stack (origin check
+ * + auth + optional role) and JSON-RPC dispatch.
+ *
+ * Returns the {@link BackendWebsocketTransport} (supplied or freshly
+ * created), same as {@link register_action_ws} — retain it to wire
+ * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
+ */
+export declare const register_ws_endpoint: <TCtx extends BaseHandlerContext>(options: RegisterWsEndpointOptions<TCtx>) => RegisterActionWsResult;
+//# sourceMappingURL=register_ws_endpoint.d.ts.map

package/dist/actions/register_ws_endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAE1D,gDAAgD;AAChD,MAAM,WAAW,yBAAyB,CACzC,IAAI,SAAS,kBAAkB,CAC9B,SAAQ,uBAAuB,CAAC,IAAI,CAAC;IACtC;;;;OAIG;IACH,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,sBAUF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -0,0 +1,38 @@
+/**
+ * Composed WebSocket endpoint registration — the idiomatic consumer entry
+ * point for mounting a fuz_app WS endpoint.
+ *
+ * Wraps the standard upgrade stack every consumer writes by hand:
+ *
+ * 1. `verify_request_source(allowed_origins)` — reject disallowed origins
+ *    before the upgrade handshake runs.
+ * 2. `require_auth` — reject unauthenticated upgrades.
+ * 3. Optional `require_role(required_role)` — for endpoints gated to a
+ *    specific role.
+ *
+ * Then delegates to {@link register_action_ws} for per-message JSON-RPC
+ * dispatch.
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { require_auth, require_role } from '../auth/request_context.js';
+import { verify_request_source } from '../http/origin.js';
+import { register_action_ws, } from './register_action_ws.js';
+/**
+ * Mount a WebSocket endpoint with the standard upgrade stack (origin check
+ * + auth + optional role) and JSON-RPC dispatch.
+ *
+ * Returns the {@link BackendWebsocketTransport} (supplied or freshly
+ * created), same as {@link register_action_ws} — retain it to wire
+ * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
+ */
+export const register_ws_endpoint = (options) => {
+    const { app, path, allowed_origins, required_role, log = new Logger('[ws]'), ...rest } = options;
+    app.use(path, verify_request_source(allowed_origins));
+    app.use(path, require_auth);
+    if (required_role !== undefined) {
+        app.use(path, require_role(required_role));
+    }
+    return register_action_ws({ app, path, log, ...rest });
+};

package/dist/actions/socket.svelte.d.ts

@@ -24,6 +24,7 @@
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { AsyncStatus } from '@fuzdev/fuz_util/async.js';
 import { type JsonrpcRequestId } from '../http/jsonrpc.js';
 import type { WebsocketConnection } from './transports_ws.js';
 /** Default WebSocket close code (normal closure). */
@@ -91,11 +92,11 @@ export interface FrontendWebsocketClientOptions {
      */
     reconnect?: boolean | FrontendWebsocketReconnectOptions | null;
     /**
-     * Activity-aware heartbeat. `true` or omit for defaults; `false` disables
+     * Activity-aware heartbeat. `true`/`null`/omit for defaults; `false` disables
      * the timer entirely (only do this if the server side is also running
      * without heartbeat); pass an object to tune `interval` / `receive_timeout`.
      */
-    heartbeat?: boolean | FrontendWebsocketHeartbeatOptions;
+    heartbeat?: boolean | FrontendWebsocketHeartbeatOptions | null;
     /**
      * Durable queue for {@link FrontendWebsocketClient.request}. `true` or omit
      * for defaults; `false` disables buffering (requests while disconnected
@@ -163,6 +164,33 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      * does not synthesize a reconnect — wait for the next close.
      */
     set_reconnect(reconnect?: boolean | FrontendWebsocketReconnectOptions | null): void;
+    /**
+     * Swap the heartbeat policy in place. Accepts the same shape as the
+     * constructor's `heartbeat` option: `false` disables the timer, `true` or
+     * `null`/omitted restores the defaults, or a config object customizes
+     * specific fields (missing fields fall back to defaults, not "keep
+     * current" — each call defines the whole policy atomically, same as the
+     * constructor and {@link set_reconnect}).
+     *
+     * When connected, the live timer is restarted immediately so the new
+     * `interval` / `receive_timeout` take effect without a reconnect; when
+     * disconnected, just stashes the policy for the next open.
+     */
+    set_heartbeat(heartbeat?: boolean | FrontendWebsocketHeartbeatOptions | null): void;
+    /**
+     * Cancel a scheduled reconnect without closing the client or disabling
+     * auto-reconnect. Transitions status from `reconnecting` → `closed` and
+     * resets the backoff counters — the next close still triggers a fresh
+     * reconnect cycle under the current policy. No-op when no reconnect is
+     * pending.
+     *
+     * Use this when UI state asks "stop trying for now" without the finality
+     * of {@link disconnect} (which also rejects pending/queued requests and
+     * clears heartbeat) or the policy change of `set_reconnect(false)`
+     * (which disables future reconnects). The queue stays intact so that
+     * calling {@link connect} later flushes buffered work.
+     */
+    cancel_reconnect(): void;
     get url(): string;
     /**
      * Whether the server has permanently closed the session. Once `true`, all
@@ -219,4 +247,17 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
     add_message_handler(handler: SocketMessageHandler): () => void;
     add_error_handler(handler: SocketErrorHandler): () => void;
 }
+/**
+ * Project {@link SocketStatus} onto fuz_util's {@link AsyncStatus} — the
+ * 5-way → 4-way mapping every consumer re-derives to surface connection state
+ * to UI (loading indicators, retry banners). Collapses `reconnecting` into
+ * `failure` (UI shows "lost, retrying") and splits `closed` by `revoked` so
+ * a terminal session-revocation read as `failure` while a clean client-
+ * initiated close reads as `initial` (the "not connected, not trying" state).
+ *
+ * @param status - the socket's current {@link SocketStatus}
+ * @param revoked - whether the session has been permanently revoked
+ *   (typically `FrontendWebsocketClient.revoked`)
+ */
+export declare const socket_status_to_async_status: (status: SocketStatus, revoked: boolean) => AsyncStatus;
 //# sourceMappingURL=socket.svelte.d.ts.map

package/dist/actions/socket.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"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"}

package/dist/actions/socket.svelte.js

@@ -111,7 +111,7 @@ export class FrontendWebsocketClient {
         this.#backoff_factor = config.factor ?? DEFAULT_BACKOFF_FACTOR;
         const heartbeat = options.heartbeat;
         this.#heartbeat_enabled = heartbeat !== false;
-        const heartbeat_config = typeof heartbeat === 'object' ? heartbeat : {};
+        const heartbeat_config = typeof heartbeat === 'object' && heartbeat !== null ? heartbeat : {};
         this.#heartbeat_interval = heartbeat_config.interval ?? DEFAULT_HEARTBEAT_INTERVAL;
         this.#heartbeat_receive_timeout =
             heartbeat_config.receive_timeout ?? DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT;
@@ -152,8 +152,7 @@ export class FrontendWebsocketClient {
         if (!next_auto) {
             this.#cancel_reconnect();
             this.status = 'closed';
-            this.reconnect_count = 0;
-            this.current_reconnect_delay = 0;
+            this.#reset_reconnect_counters();
             return;
         }
         // Auto-reconnect still on: monotonically shorten the pending wait if
@@ -176,6 +175,50 @@ export class FrontendWebsocketClient {
             this.connect();
         }, new_remaining);
     }
+    /**
+     * Swap the heartbeat policy in place. Accepts the same shape as the
+     * constructor's `heartbeat` option: `false` disables the timer, `true` or
+     * `null`/omitted restores the defaults, or a config object customizes
+     * specific fields (missing fields fall back to defaults, not "keep
+     * current" — each call defines the whole policy atomically, same as the
+     * constructor and {@link set_reconnect}).
+     *
+     * When connected, the live timer is restarted immediately so the new
+     * `interval` / `receive_timeout` take effect without a reconnect; when
+     * disconnected, just stashes the policy for the next open.
+     */
+    set_heartbeat(heartbeat = null) {
+        this.#heartbeat_enabled = heartbeat !== false;
+        const config = typeof heartbeat === 'object' && heartbeat !== null ? heartbeat : {};
+        this.#heartbeat_interval = config.interval ?? DEFAULT_HEARTBEAT_INTERVAL;
+        this.#heartbeat_receive_timeout = config.receive_timeout ?? DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT;
+        if (this.connected) {
+            this.#start_heartbeat();
+        }
+        else {
+            this.#cancel_heartbeat();
+        }
+    }
+    /**
+     * Cancel a scheduled reconnect without closing the client or disabling
+     * auto-reconnect. Transitions status from `reconnecting` → `closed` and
+     * resets the backoff counters — the next close still triggers a fresh
+     * reconnect cycle under the current policy. No-op when no reconnect is
+     * pending.
+     *
+     * Use this when UI state asks "stop trying for now" without the finality
+     * of {@link disconnect} (which also rejects pending/queued requests and
+     * clears heartbeat) or the policy change of `set_reconnect(false)`
+     * (which disables future reconnects). The queue stays intact so that
+     * calling {@link connect} later flushes buffered work.
+     */
+    cancel_reconnect() {
+        if (this.#reconnect_timeout === null)
+            return;
+        this.#cancel_reconnect();
+        this.status = 'closed';
+        this.#reset_reconnect_counters();
+    }
     get url() {
         return this.#url;
     }
@@ -229,8 +272,7 @@ export class FrontendWebsocketClient {
         this.#cancel_heartbeat();
         this.#teardown(code);
         this.status = 'closed';
-        this.reconnect_count = 0;
-        this.current_reconnect_delay = 0;
+        this.#reset_reconnect_counters();
         this.#reject_all('client disconnected');
     }
     /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
@@ -535,10 +577,14 @@ export class FrontendWebsocketClient {
         }
         this.#reconnect_scheduled_at = null;
     }
-    #handle_open = (_event) => {
-        this.status = 'connected';
+    /** Reset the reactive reconnect counters — the pair always travels together. */
+    #reset_reconnect_counters() {
         this.reconnect_count = 0;
         this.current_reconnect_delay = 0;
+    }
+    #handle_open = (_event) => {
+        this.status = 'connected';
+        this.#reset_reconnect_counters();
         this.last_connect_time = Date.now();
         this.#cancel_reconnect();
         this.#start_heartbeat();
@@ -556,8 +602,7 @@ export class FrontendWebsocketClient {
             this.#revoked = true;
             this.status = 'closed';
             this.#cancel_reconnect();
-            this.reconnect_count = 0;
-            this.current_reconnect_delay = 0;
+            this.#reset_reconnect_counters();
             this.#reject_all('session revoked');
             return;
         }
@@ -630,3 +675,29 @@ export class FrontendWebsocketClient {
         }
     };
 }
+/**
+ * Project {@link SocketStatus} onto fuz_util's {@link AsyncStatus} — the
+ * 5-way → 4-way mapping every consumer re-derives to surface connection state
+ * to UI (loading indicators, retry banners). Collapses `reconnecting` into
+ * `failure` (UI shows "lost, retrying") and splits `closed` by `revoked` so
+ * a terminal session-revocation read as `failure` while a clean client-
+ * initiated close reads as `initial` (the "not connected, not trying" state).
+ *
+ * @param status - the socket's current {@link SocketStatus}
+ * @param revoked - whether the session has been permanently revoked
+ *   (typically `FrontendWebsocketClient.revoked`)
+ */
+export const socket_status_to_async_status = (status, revoked) => {
+    switch (status) {
+        case 'initial':
+            return 'initial';
+        case 'connecting':
+            return 'pending';
+        case 'connected':
+            return 'success';
+        case 'reconnecting':
+            return 'failure';
+        case 'closed':
+            return revoked ? 'failure' : 'initial';
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -45,9 +45,9 @@
     "@fuzdev/blake3_wasm": "^0.1.0",
     "@fuzdev/fuz_code": "^0.45.1",
     "@fuzdev/fuz_css": "^0.58.0",
-    "@fuzdev/fuz_ui": "^0.191.2",
-    "@fuzdev/fuz_util": "^0.56.0",
-    "@fuzdev/gro": "^0.197.3",
+    "@fuzdev/fuz_ui": "^0.191.4",
+    "@fuzdev/fuz_util": "^0.57.0",
+    "@fuzdev/gro": "^0.198.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@node-rs/argon2": "^2.0.2",
     "@ryanatkn/eslint-config": "^0.11.0",