@fuzdev/fuz_app 0.17.0 → 0.18.0

package/dist/actions/register_action_ws.d.ts

@@ -96,8 +96,8 @@ export interface RegisterActionWsResult {
  * - Notifications (method + no id) are silently dropped per JSON-RPC spec.
  * - Per-action auth: `public` / `authenticated` pass through (upgrade auth
  *   already verified identity); `keeper` requires `daemon_token` credential
- *   type *and* the keeper role; role-based `{role}` is currently rejected as
- *   not-yet-supported.
+ *   type *and* the keeper role; role-based `{role}` requires the named role
+ *   via `has_role`, matching the HTTP path in `action_rpc.ts`.
  * - DEV mode validates handler output against the spec's `output` schema and
  *   warns on mismatches.
  *

package/dist/actions/register_action_ws.js

@@ -42,8 +42,8 @@ import { BackendWebsocketTransport } from './transports_ws_backend.js';
  * - Notifications (method + no id) are silently dropped per JSON-RPC spec.
  * - Per-action auth: `public` / `authenticated` pass through (upgrade auth
  *   already verified identity); `keeper` requires `daemon_token` credential
- *   type *and* the keeper role; role-based `{role}` is currently rejected as
- *   not-yet-supported.
+ *   type *and* the keeper role; role-based `{role}` requires the named role
+ *   via `has_role`, matching the HTTP path in `action_rpc.ts`.
  * - DEV mode validates handler output against the spec's `output` schema and
  *   warns on mismatches.
  *
@@ -118,8 +118,10 @@ export const register_action_ws = (options) => {
                     }
                 }
                 else if (typeof auth === 'object' && auth !== null) {
-                    ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.internal_error('role-based action auth is not yet supported on WebSocket'))));
-                    return;
+                    if (!has_role(request_context, auth.role)) {
+                        ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.forbidden(`requires role: ${auth.role}`))));
+                        return;
+                    }
                 }
                 // Look up handler — method is validated against spec_by_method above.
                 const handler = handlers[method];

package/dist/actions/rpc_client.d.ts

@@ -12,6 +12,16 @@
 import type { ActionEventEnvironment } from './action_event_types.js';
 import type { ActionPeer } from './action_peer.js';
 import type { ActionEventDataUnion } from './action_event_data.js';
+import type { TransportName } from './transports.js';
+/**
+ * Optional per-method transport selector. Return the transport to use for a
+ * given method, or `undefined` to let the peer pick via its fallback rules.
+ *
+ * Useful when methods are registered on different backend dispatchers — e.g.
+ * a streaming action mounted on the WebSocket endpoint while the rest of the
+ * RPC surface lives on HTTP.
+ */
+export type TransportForMethod = (method: string) => TransportName | undefined;
 /** Duck-typed action history — consumers pass their concrete Actions cell. */
 export interface RpcClientActionHistory {
     add_from_json: (json: {
@@ -27,6 +37,13 @@ export interface CreateRpcClientOptions {
     environment: ActionEventEnvironment;
     /** Optional action history tracking (duck-typed Actions cell). */
     actions?: RpcClientActionHistory;
+    /**
+     * Optional per-method transport selector. When provided, the client calls
+     * `peer.send(msg, {transport_name})` with the returned transport for each
+     * `request_response` / `remote_notification` dispatch. Returning `undefined`
+     * falls back to the peer's default selection.
+     */
+    transport_for_method?: TransportForMethod;
 }
 /**
  * Creates a Proxy-based API from action specs.

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

@@ -1 +1 @@
-{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAMjE,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC"}
+{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC"}

package/dist/actions/rpc_client.js

@@ -23,14 +23,14 @@ import { is_send_request, is_notification_send, extract_action_result, } from '.
  * @returns a Proxy that responds to any method name found in the environment's specs
  */
 export const create_rpc_client = (options) => {
-    const { peer, environment, actions } = options;
+    const { peer, environment, actions, transport_for_method } = options;
     return new Proxy({}, {
         get(_target, method) {
             const spec = environment.lookup_action_spec(method);
             if (!spec) {
                 return undefined;
             }
-            return create_action_method(peer, environment, spec, actions);
+            return create_action_method(peer, environment, spec, actions, transport_for_method);
         },
         has(_target, method) {
             return environment.lookup_action_spec(method) !== undefined;
@@ -40,16 +40,16 @@ export const create_rpc_client = (options) => {
 /**
  * Creates a method that executes an action through its complete lifecycle.
  */
-const create_action_method = (peer, environment, spec, actions) => {
+const create_action_method = (peer, environment, spec, actions, transport_for_method) => {
     switch (spec.kind) {
         case 'local_call':
             return spec.async
                 ? create_async_local_call_method(environment, spec, actions)
                 : create_sync_local_call_method(environment, spec, actions);
         case 'request_response':
-            return create_request_response_method(peer, environment, spec, actions);
+            return create_request_response_method(peer, environment, spec, actions, transport_for_method);
         case 'remote_notification':
-            return create_remote_notification_method(peer, environment, spec, actions);
+            return create_remote_notification_method(peer, environment, spec, actions, transport_for_method);
     }
 };
 /**
@@ -94,7 +94,7 @@ const create_async_local_call_method = (environment, spec, actions) => {
 /**
  * Creates a request/response method that communicates over the network.
  */
-const create_request_response_method = (peer, environment, spec, actions) => {
+const create_request_response_method = (peer, environment, spec, actions, transport_for_method) => {
     return async (input) => {
         const event = create_action_event(environment, spec, input);
         const action = actions?.add_from_json({
@@ -113,7 +113,8 @@ const create_request_response_method = (peer, environment, spec, actions) => {
         if (event.data.step !== 'handled') {
             return extract_action_result(event);
         }
-        const response = await peer.send(event.data.request);
+        const transport_name = transport_for_method?.(spec.method);
+        const response = await peer.send(event.data.request, transport_name ? { transport_name } : undefined);
         event.transition('receive_response');
         // TODO @api shouldn't this happen in the peer like the other method calls?
         event.set_response(response);
@@ -126,7 +127,7 @@ const create_request_response_method = (peer, environment, spec, actions) => {
  * Creates a remote notification method (fire and forget).
  * Returns Result<{value: void}> for consistency.
  */
-const create_remote_notification_method = (peer, environment, spec, actions) => {
+const create_remote_notification_method = (peer, environment, spec, actions, transport_for_method) => {
     return async (input) => {
         const event = create_action_event(environment, spec, input);
         const action = actions?.add_from_json({
@@ -138,7 +139,8 @@ const create_remote_notification_method = (peer, environment, spec, actions) =>
         if (!is_notification_send(event.data))
             throw Error(); // TODO @many maybe make this an assertion helper?
         if (event.data.step === 'handled') {
-            const send_result = await peer.send(event.data.notification);
+            const transport_name = transport_for_method?.(spec.method);
+            const send_result = await peer.send(event.data.notification, transport_name ? { transport_name } : undefined);
             // Check if notification failed to send
             if (send_result !== null) {
                 environment.log?.error('notification send failed:', send_result.error);

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

@@ -0,0 +1,108 @@
+/**
+ * Frontend WebSocket client — portable, Svelte-reactive, implements `WebsocketConnection`.
+ *
+ * Plain class with `$state` runes (no Cell inheritance, no app coupling).
+ * Drop into any SvelteKit frontend as the underlying connection for
+ * `FrontendWebsocketTransport`. Handles auto-reconnect with exponential
+ * backoff, respects `WS_CLOSE_SESSION_REVOKED` (no reconnect loop after the
+ * server revokes auth), and exposes reactive status for UI indicators.
+ *
+ * First cut: no message queue, no heartbeat. Those live in consumer-specific
+ * wrappers today (see zzz's `Socket` Cell); extract into fuz_app when two
+ * independent consumers motivate the shape.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { WebsocketConnection } from './transports_ws.js';
+/** Default WebSocket close code (normal closure). */
+export declare const DEFAULT_CLOSE_CODE = 1000;
+/** Base reconnect delay in ms. */
+export declare const DEFAULT_RECONNECT_DELAY = 1000;
+/** Max reconnect delay in ms (cap on exponential backoff). */
+export declare const DEFAULT_RECONNECT_DELAY_MAX = 10000;
+/** Exponential backoff factor: delay = base * factor^(attempt-1). */
+export declare const DEFAULT_BACKOFF_FACTOR = 1.5;
+/**
+ * Client-side WebSocket status.
+ *
+ * - `initial` — never connected; `connect()` has not been called.
+ * - `connecting` — WebSocket `readyState === CONNECTING`.
+ * - `connected` — WebSocket `readyState === OPEN`.
+ * - `reconnecting` — close fired; waiting out backoff before next attempt.
+ * - `closed` — socket is not open. Terminal only when `revoked` is `true`
+ *   or auto-reconnect is disabled; otherwise `connect()` reopens.
+ */
+export type SocketStatus = 'initial' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+export type SocketMessageHandler = (event: MessageEvent) => void;
+export type SocketErrorHandler = (event: Event) => void;
+export interface FrontendWebsocketReconnectOptions {
+    /** Base reconnect delay in ms. Defaults to 1000. */
+    delay?: number;
+    /** Max reconnect delay in ms (cap on exponential backoff). Defaults to 10000. */
+    delay_max?: number;
+    /** Exponential backoff factor. Defaults to 1.5. */
+    factor?: number;
+}
+export interface FrontendWebsocketClientOptions {
+    /**
+     * Auto-reconnect policy. `false` disables reconnect entirely; `true` or
+     * omit for default timing; pass an object to customize.
+     */
+    reconnect?: boolean | FrontendWebsocketReconnectOptions | null;
+    /** Optional logger for diagnostic messages. */
+    log?: Logger | null;
+}
+/**
+ * Reactive WebSocket client implementing `WebsocketConnection`.
+ *
+ * Construct with a URL and optional config; call `connect()` to open the
+ * socket and begin auto-reconnect. Register message/error handlers via
+ * `add_message_handler` / `add_error_handler` — both return unsubscribe
+ * functions. `FrontendWebsocketTransport` consumes this as its connection.
+ *
+ * Session-revocation close codes (`WS_CLOSE_SESSION_REVOKED`) put the client
+ * in a permanently-closed state; reconnecting would just loop on 401.
+ */
+export declare class FrontendWebsocketClient implements WebsocketConnection, Disposable {
+    #private;
+    ws: WebSocket | null;
+    status: SocketStatus;
+    reconnect_count: number;
+    current_reconnect_delay: number;
+    /** Epoch ms of the most recent successful open. Never cleared on close. */
+    last_connect_time: number | null;
+    /** Epoch ms of the most recent close event or client-initiated close. */
+    last_close_time: number | null;
+    /** Close code from the most recent close. Initial `null` means "never closed." */
+    last_close_code: number | null;
+    /** Reason string from the most recent close event (may be empty). */
+    last_close_reason: string | null;
+    readonly connected: boolean;
+    constructor(url: string, options?: FrontendWebsocketClientOptions);
+    get url(): string;
+    /**
+     * Whether the server has permanently closed the session. Once `true`, all
+     * `connect()` calls are no-ops. Distinct from `status:'closed'`, which
+     * reflects any closed state (incl. user-initiated `disconnect()`).
+     */
+    get revoked(): boolean;
+    /**
+     * Open the WebSocket. No-op on SSR, or if the session has been revoked.
+     * Cancels any pending reconnect and tears down any existing connection first;
+     * an open prior socket is closed with a normal-closure code.
+     */
+    connect(): void;
+    /**
+     * Close the WebSocket, cancel any pending reconnect, and reset the reconnect
+     * backoff counters. Puts the client in `closed` status; call `connect()` to
+     * reopen. Safe to call more than once.
+     */
+    disconnect(code?: number): void;
+    /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
+    [Symbol.dispose](): void;
+    send(data: object): boolean;
+    add_message_handler(handler: SocketMessageHandler): () => void;
+    add_error_handler(handler: SocketErrorHandler): () => void;
+}
+//# sourceMappingURL=socket.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,kCAAkC;AAClC,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,8DAA8D;AAC9D,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AACjD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AACjE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,iCAAiC;IACjD,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,8BAA8B;IAC9C;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,iCAAiC,GAAG,IAAI,CAAC;IAC/D,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB,EAAE,UAAU;;IAQ9E,EAAE,EAAE,SAAS,GAAG,IAAI,CAAoB;IACxC,MAAM,EAAE,YAAY,CAAyB;IAE7C,eAAe,EAAE,MAAM,CAAiB;IACxC,uBAAuB,EAAE,MAAM,CAAiB;IAChD,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IACpD,yEAAyE;IACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IAQpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAyC;gBAExD,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,8BAAmC;IAWrE,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI;IA2Bf;;;;OAIG;IACH,UAAU,CAAC,IAAI,GAAE,MAA2B,GAAG,IAAI;IAQnD,sGAAsG;IACtG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAW3B,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK9D,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;CA8G1D"}

package/dist/actions/socket.svelte.js

@@ -0,0 +1,245 @@
+/**
+ * Frontend WebSocket client — portable, Svelte-reactive, implements `WebsocketConnection`.
+ *
+ * Plain class with `$state` runes (no Cell inheritance, no app coupling).
+ * Drop into any SvelteKit frontend as the underlying connection for
+ * `FrontendWebsocketTransport`. Handles auto-reconnect with exponential
+ * backoff, respects `WS_CLOSE_SESSION_REVOKED` (no reconnect loop after the
+ * server revokes auth), and exposes reactive status for UI indicators.
+ *
+ * First cut: no message queue, no heartbeat. Those live in consumer-specific
+ * wrappers today (see zzz's `Socket` Cell); extract into fuz_app when two
+ * independent consumers motivate the shape.
+ *
+ * @module
+ */
+import { BROWSER } from 'esm-env';
+import { WS_CLOSE_SESSION_REVOKED } from './transports.js';
+/** Default WebSocket close code (normal closure). */
+export const DEFAULT_CLOSE_CODE = 1000;
+/** Base reconnect delay in ms. */
+export const DEFAULT_RECONNECT_DELAY = 1000;
+/** Max reconnect delay in ms (cap on exponential backoff). */
+export const DEFAULT_RECONNECT_DELAY_MAX = 10000;
+/** Exponential backoff factor: delay = base * factor^(attempt-1). */
+export const DEFAULT_BACKOFF_FACTOR = 1.5;
+/**
+ * Reactive WebSocket client implementing `WebsocketConnection`.
+ *
+ * Construct with a URL and optional config; call `connect()` to open the
+ * socket and begin auto-reconnect. Register message/error handlers via
+ * `add_message_handler` / `add_error_handler` — both return unsubscribe
+ * functions. `FrontendWebsocketTransport` consumes this as its connection.
+ *
+ * Session-revocation close codes (`WS_CLOSE_SESSION_REVOKED`) put the client
+ * in a permanently-closed state; reconnecting would just loop on 401.
+ */
+export class FrontendWebsocketClient {
+    #url;
+    #auto_reconnect;
+    #reconnect_delay;
+    #reconnect_delay_max;
+    #backoff_factor;
+    #log;
+    ws = $state.raw(null);
+    status = $state.raw('initial');
+    reconnect_count = $state.raw(0);
+    current_reconnect_delay = $state.raw(0);
+    /** Epoch ms of the most recent successful open. Never cleared on close. */
+    last_connect_time = $state.raw(null);
+    /** Epoch ms of the most recent close event or client-initiated close. */
+    last_close_time = $state.raw(null);
+    /** Close code from the most recent close. Initial `null` means "never closed." */
+    last_close_code = $state.raw(null);
+    /** Reason string from the most recent close event (may be empty). */
+    last_close_reason = $state.raw(null);
+    #reconnect_timeout = null;
+    #revoked = $state.raw(false);
+    #message_handlers = new Set();
+    #error_handlers = new Set();
+    connected = $derived(this.status === 'connected');
+    constructor(url, options = {}) {
+        this.#url = url;
+        const reconnect = options.reconnect;
+        this.#auto_reconnect = reconnect !== false;
+        const config = typeof reconnect === 'object' && reconnect !== null ? reconnect : {};
+        this.#reconnect_delay = config.delay ?? DEFAULT_RECONNECT_DELAY;
+        this.#reconnect_delay_max = config.delay_max ?? DEFAULT_RECONNECT_DELAY_MAX;
+        this.#backoff_factor = config.factor ?? DEFAULT_BACKOFF_FACTOR;
+        this.#log = options.log ?? null;
+    }
+    get url() {
+        return this.#url;
+    }
+    /**
+     * Whether the server has permanently closed the session. Once `true`, all
+     * `connect()` calls are no-ops. Distinct from `status:'closed'`, which
+     * reflects any closed state (incl. user-initiated `disconnect()`).
+     */
+    get revoked() {
+        return this.#revoked;
+    }
+    /**
+     * Open the WebSocket. No-op on SSR, or if the session has been revoked.
+     * Cancels any pending reconnect and tears down any existing connection first;
+     * an open prior socket is closed with a normal-closure code.
+     */
+    connect() {
+        if (!BROWSER)
+            return;
+        if (this.#revoked)
+            return;
+        this.#cancel_reconnect();
+        this.#teardown(DEFAULT_CLOSE_CODE);
+        try {
+            this.status = 'connecting';
+            const ws = new WebSocket(this.#url);
+            this.ws = ws;
+            ws.addEventListener('open', this.#handle_open);
+            ws.addEventListener('close', this.#handle_close);
+            ws.addEventListener('error', this.#handle_error);
+            ws.addEventListener('message', this.#handle_message);
+        }
+        catch (error) {
+            this.#log?.error('[socket] failed to create WebSocket:', error);
+            this.ws = null;
+            if (this.#auto_reconnect) {
+                this.#schedule_reconnect();
+            }
+            else {
+                this.status = 'closed';
+            }
+        }
+    }
+    /**
+     * Close the WebSocket, cancel any pending reconnect, and reset the reconnect
+     * backoff counters. Puts the client in `closed` status; call `connect()` to
+     * reopen. Safe to call more than once.
+     */
+    disconnect(code = DEFAULT_CLOSE_CODE) {
+        this.#cancel_reconnect();
+        this.#teardown(code);
+        this.status = 'closed';
+        this.reconnect_count = 0;
+        this.current_reconnect_delay = 0;
+    }
+    /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
+    [Symbol.dispose]() {
+        this.disconnect();
+    }
+    send(data) {
+        if (!this.connected || !this.ws)
+            return false;
+        try {
+            this.ws.send(JSON.stringify(data));
+            return true;
+        }
+        catch (error) {
+            this.#log?.error('[socket] send failed:', error);
+            return false;
+        }
+    }
+    add_message_handler(handler) {
+        this.#message_handlers.add(handler);
+        return () => this.#message_handlers.delete(handler);
+    }
+    add_error_handler(handler) {
+        this.#error_handlers.add(handler);
+        return () => this.#error_handlers.delete(handler);
+    }
+    #teardown(close_code) {
+        if (!this.ws)
+            return;
+        this.ws.removeEventListener('open', this.#handle_open);
+        this.ws.removeEventListener('close', this.#handle_close);
+        this.ws.removeEventListener('error', this.#handle_error);
+        this.ws.removeEventListener('message', this.#handle_message);
+        if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+            try {
+                this.ws.close(close_code);
+            }
+            catch (error) {
+                this.#log?.error('[socket] close failed:', error);
+            }
+            // Listeners are gone, so `#handle_close` won't fire for this close —
+            // record it here so the client-initiated close is still observable.
+            this.#record_close(close_code, '');
+        }
+        this.ws = null;
+    }
+    #record_close(code, reason) {
+        this.last_close_time = Date.now();
+        this.last_close_code = code;
+        this.last_close_reason = reason;
+    }
+    #schedule_reconnect() {
+        if (!this.#auto_reconnect || this.#revoked)
+            return;
+        this.#cancel_reconnect();
+        this.reconnect_count++;
+        this.current_reconnect_delay = Math.round(Math.min(this.#reconnect_delay_max, this.#reconnect_delay * this.#backoff_factor ** (this.reconnect_count - 1)));
+        this.status = 'reconnecting';
+        this.#reconnect_timeout = setTimeout(() => {
+            this.#reconnect_timeout = null;
+            this.connect();
+        }, this.current_reconnect_delay);
+    }
+    #cancel_reconnect() {
+        if (this.#reconnect_timeout !== null) {
+            clearTimeout(this.#reconnect_timeout);
+            this.#reconnect_timeout = null;
+        }
+    }
+    #handle_open = (_event) => {
+        this.status = 'connected';
+        this.reconnect_count = 0;
+        this.current_reconnect_delay = 0;
+        this.last_connect_time = Date.now();
+        this.#cancel_reconnect();
+    };
+    #handle_close = (event) => {
+        // Drop the dead-socket reference so consumers reading `client.ws` never
+        // see a CLOSED WebSocket during the reconnect window.
+        this.ws = null;
+        this.#record_close(event.code, event.reason);
+        // Session revocation is terminal — reconnecting would 401 in a loop.
+        if (event.code === WS_CLOSE_SESSION_REVOKED) {
+            this.#revoked = true;
+            this.status = 'closed';
+            this.#cancel_reconnect();
+            this.reconnect_count = 0;
+            this.current_reconnect_delay = 0;
+            return;
+        }
+        // Let `#schedule_reconnect` set `status: 'reconnecting'` directly to avoid
+        // a transient `'closed'` flicker; only set `'closed'` when reconnect is off.
+        if (this.#auto_reconnect) {
+            this.#schedule_reconnect();
+        }
+        else {
+            this.status = 'closed';
+        }
+    };
+    #handle_error = (event) => {
+        this.#log?.error('[socket] websocket error:', event);
+        for (const handler of this.#error_handlers) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                this.#log?.error('[socket] error handler threw:', error);
+            }
+        }
+        // Browsers fire `close` after error; reconnect logic lives there.
+    };
+    #handle_message = (event) => {
+        for (const handler of this.#message_handlers) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                this.#log?.error('[socket] message handler threw:', error);
+            }
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",