@fuzdev/fuz_app 0.16.0 → 0.17.1

package/dist/actions/broadcast_api.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Backend-initiated broadcast notification plumbing — generic across consumers.
+ *
+ * Builds a typed `{method_name: (input) => Promise<void>}` object from a list
+ * of action specs. Each call validates input against the spec, wraps it in a
+ * JSON-RPC notification, and either broadcasts to every connection or
+ * fans out with a per-connection ACL predicate.
+ *
+ * Counterpart to `register_action_ws`: that handles request-scoped dispatch
+ * (frontend-initiated), this handles broadcast (backend-initiated). Together
+ * they cover the two primitives fuz_app consumers share. Request-scoped
+ * streaming (`completion_progress`, `tx_apply` events) stays on
+ * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
+ *
+ * Extracted from zzz's `backend_actions_api.ts` as part of the websockets
+ * quest (Phase 3) to stop the pattern from drifting across zzz, tx, and
+ * undying.
+ *
+ * @module
+ */
+import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
+import type { ActionPeer } from './action_peer.js';
+import type { ActionSpecUnion } from './action_spec.js';
+import { type ConnectionIdentity } from './transports_ws_backend.js';
+/**
+ * Per-connection delivery predicate for subscription ACLs.
+ *
+ * Called once per connection for every broadcast send. Returning `false`
+ * skips that connection. Keep it fast — this runs in the broadcast hot path.
+ *
+ * `input` is the already-validated payload (matches the spec's input schema);
+ * `method` is the action method name.
+ */
+export type ShouldDeliverFn = (connection: ConnectionIdentity, method: string, input: unknown) => boolean;
+/** Options for `create_broadcast_api`. */
+export interface CreateBroadcastApiOptions {
+    /** The peer holding the transport registry used for sends. */
+    peer: ActionPeer;
+    /**
+     * Notification specs to expose as broadcast methods. Typically the
+     * `remote_notification` specs whose initiator is `backend` (or `both`).
+     * Other kinds are accepted — the helper only uses `spec.method` and
+     * `spec.input` — but the typical use is notifications.
+     */
+    specs: ReadonlyArray<ActionSpecUnion>;
+    /** Logger for validation/send errors. Defaults to a `[broadcast]` namespace. */
+    log?: LoggerType | null;
+    /**
+     * Optional per-connection ACL predicate. When set, the broadcast fans out
+     * via the transport's `broadcast_filtered` (feature-detected) — each
+     * connection's identity is checked before the message is sent. When
+     * unset, the transport broadcasts unfiltered via `transport.send`.
+     *
+     * Requires a transport that implements `FilterableBroadcastTransport`
+     * (today: only `BackendWebsocketTransport`). If set and the active
+     * transport is not filterable, the send is skipped and an error logged.
+     */
+    should_deliver?: ShouldDeliverFn;
+}
+/**
+ * Loose base shape for a broadcast API. Consumers typically declare a
+ * stricter per-method interface (e.g. `BackendActionsApi`) and pin it via
+ * the type parameter on `create_broadcast_api`.
+ */
+export type BroadcastApi = Record<string, (input: never) => Promise<void>>;
+/**
+ * Builds a typed broadcast API from a set of action specs.
+ *
+ * For each spec, adds a method keyed by `spec.method` that:
+ * - Validates `input` against the spec's Zod schema (logs and returns on failure)
+ * - Creates a JSON-RPC notification from the validated input
+ * - Broadcasts via the peer (filtered by `should_deliver` when supplied)
+ *
+ * Silently returns when no transport is ready (e.g. before any clients
+ * connect). Errors during send are logged but never thrown — broadcasts are
+ * fire-and-forget from the handler's perspective.
+ *
+ * ## Typed consumer surface
+ *
+ * Consumers declare an explicit interface and pin it via the type parameter:
+ *
+ * ```ts
+ * export interface BackendActionsApi {
+ *   filer_change: (input: ActionInputs['filer_change']) => Promise<void>;
+ *   workspace_changed: (input: ActionInputs['workspace_changed']) => Promise<void>;
+ * }
+ *
+ * const api = create_broadcast_api<BackendActionsApi>({
+ *   peer: backend.peer,
+ *   specs: [filer_change_action_spec, workspace_changed_action_spec],
+ * });
+ * ```
+ *
+ * The cast is unchecked — callers must keep the interface and the `specs`
+ * array in sync. Codegen (`action_collections.gen.ts`) is a natural fit
+ * if the consumer already generates per-method type maps.
+ */
+export declare const create_broadcast_api: <TApi = BroadcastApi>(options: CreateBroadcastApiOptions) => TApi;
+//# sourceMappingURL=broadcast_api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast_api.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/broadcast_api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG1E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,KACV,OAAO,CAAC;AAEb,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,gFAAgF;IAChF,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,GAAG,YAAY,EACvD,SAAS,yBAAyB,KAChC,IAoDF,CAAC"}

package/dist/actions/broadcast_api.js

@@ -0,0 +1,99 @@
+/**
+ * Backend-initiated broadcast notification plumbing — generic across consumers.
+ *
+ * Builds a typed `{method_name: (input) => Promise<void>}` object from a list
+ * of action specs. Each call validates input against the spec, wraps it in a
+ * JSON-RPC notification, and either broadcasts to every connection or
+ * fans out with a per-connection ACL predicate.
+ *
+ * Counterpart to `register_action_ws`: that handles request-scoped dispatch
+ * (frontend-initiated), this handles broadcast (backend-initiated). Together
+ * they cover the two primitives fuz_app consumers share. Request-scoped
+ * streaming (`completion_progress`, `tx_apply` events) stays on
+ * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
+ *
+ * Extracted from zzz's `backend_actions_api.ts` as part of the websockets
+ * quest (Phase 3) to stop the pattern from drifting across zzz, tx, and
+ * undying.
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { create_jsonrpc_notification, to_jsonrpc_params } from '../http/jsonrpc_helpers.js';
+import { is_filterable_broadcast_transport, } from './transports_ws_backend.js';
+/**
+ * Builds a typed broadcast API from a set of action specs.
+ *
+ * For each spec, adds a method keyed by `spec.method` that:
+ * - Validates `input` against the spec's Zod schema (logs and returns on failure)
+ * - Creates a JSON-RPC notification from the validated input
+ * - Broadcasts via the peer (filtered by `should_deliver` when supplied)
+ *
+ * Silently returns when no transport is ready (e.g. before any clients
+ * connect). Errors during send are logged but never thrown — broadcasts are
+ * fire-and-forget from the handler's perspective.
+ *
+ * ## Typed consumer surface
+ *
+ * Consumers declare an explicit interface and pin it via the type parameter:
+ *
+ * ```ts
+ * export interface BackendActionsApi {
+ *   filer_change: (input: ActionInputs['filer_change']) => Promise<void>;
+ *   workspace_changed: (input: ActionInputs['workspace_changed']) => Promise<void>;
+ * }
+ *
+ * const api = create_broadcast_api<BackendActionsApi>({
+ *   peer: backend.peer,
+ *   specs: [filer_change_action_spec, workspace_changed_action_spec],
+ * });
+ * ```
+ *
+ * The cast is unchecked — callers must keep the interface and the `specs`
+ * array in sync. Codegen (`action_collections.gen.ts`) is a natural fit
+ * if the consumer already generates per-method type maps.
+ */
+export const create_broadcast_api = (options) => {
+    const { peer, specs, should_deliver } = options;
+    const log = options.log === undefined ? new Logger('[broadcast]') : options.log;
+    const api = {};
+    for (const spec of specs) {
+        const { method } = spec;
+        api[method] = async (input) => {
+            const parsed = spec.input.safeParse(input);
+            if (!parsed.success) {
+                log?.error(`[${method}] input validation failed:`, parsed.error.issues);
+                return;
+            }
+            // Resolve the broadcast target deterministically — no fallback.
+            // Broadcast is 1→N over a specific primary transport; falling through
+            // to "any ready transport" would send to an unexpected audience.
+            // Silent skip when no ready transport (e.g. before any clients connect).
+            const transport_name = peer.default_send_options.transport_name;
+            const transport = transport_name
+                ? peer.transports.get_transport_by_name(transport_name)
+                : peer.transports.get_current_transport();
+            if (!transport?.is_ready())
+                return;
+            const notification = create_jsonrpc_notification(method, to_jsonrpc_params(parsed.data));
+            try {
+                if (should_deliver) {
+                    if (!is_filterable_broadcast_transport(transport)) {
+                        log?.error(`[${method}] should_deliver set but transport ${transport.transport_name} does not support per-connection filtering`);
+                        return;
+                    }
+                    transport.broadcast_filtered(notification, (identity) => should_deliver(identity, method, parsed.data));
+                    return;
+                }
+                const result = await transport.send(notification);
+                if (result !== null) {
+                    log?.error(`[${method}] failed to send notification:`, result.error);
+                }
+            }
+            catch (error) {
+                log?.error(`[${method}] unexpected error:`, error);
+            }
+        };
+    }
+    return api;
+};

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/dist/actions/transports_ws_backend.d.ts

@@ -5,7 +5,7 @@
  * @module
  */
 import type { WSContext } from 'hono/ws';
-import type { JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
+import type { JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 import { type Uuid } from '../uuid.js';
 import { type Transport } from './transports.js';
 /**
@@ -24,7 +24,21 @@ export interface ConnectionIdentity {
     /** `api_token.id` for bearer-authenticated connections, else null. */
     api_token_id: string | null;
 }
-export declare class BackendWebsocketTransport implements Transport {
+/**
+ * Structural capability for transports that can broadcast with a
+ * per-connection ACL predicate. Named separately from `Transport` so the
+ * broadcast API can feature-detect without importing a concrete class.
+ *
+ * `ConnectionIdentity` is the auth-gated identity shape used today. When a
+ * second implementation (e.g. SSE backend transport) lands with a
+ * different identity, consider parameterizing on `TIdentity`.
+ */
+export interface FilterableBroadcastTransport extends Transport {
+    broadcast_filtered: (message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean) => number;
+}
+/** Type guard for `FilterableBroadcastTransport`. */
+export declare const is_filterable_broadcast_transport: (transport: Transport) => transport is FilterableBroadcastTransport;
+export declare class BackendWebsocketTransport implements FilterableBroadcastTransport {
     #private;
     readonly transport_name: "backend_websocket_rpc";
     /**
@@ -66,6 +80,17 @@ export declare class BackendWebsocketTransport implements Transport {
     close_sockets_for_token(api_token_id: string): number;
     send(message: JsonrpcRequest): Promise<JsonrpcResponseOrError>;
     send(message: JsonrpcNotification): Promise<JsonrpcErrorResponse | null>;
+    /**
+     * Broadcast to connections whose identity satisfies a predicate.
+     *
+     * Used by the broadcast API when a consumer supplies a subscription ACL hook
+     * (e.g. tx's `tx_run_created` only reaches the account that owns the run).
+     * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
+     * to skip the per-connection predicate overhead.
+     *
+     * @returns the number of sockets the message was sent to
+     */
+    broadcast_filtered(message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean): number;
     is_ready(): boolean;
 }
 //# sourceMappingURL=transports_ws_backend.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,YAAY,CAAC;AAClD,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAIzE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,yBAA0B,YAAW,SAAS;;IAC1D,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAY3D;;;;;;;;OAQG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;OAQG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAsB/C,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4C9E,QAAQ,IAAI,OAAO;CAGnB"}
+{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAEX,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,YAAY,CAAC;AAClD,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAIzE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,SAAS;IAC9D,kBAAkB,EAAE,CACnB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,KAChD,MAAM,CAAC;CACZ;AAED,qDAAqD;AACrD,eAAO,MAAM,iCAAiC,GAC7C,WAAW,SAAS,KAClB,SAAS,IAAI,4BAEqE,CAAC;AAEtF,qBAAa,yBAA0B,YAAW,4BAA4B;;IAC7E,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAY3D;;;;;;;;OAQG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;OAQG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAsB/C,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4C9E;;;;;;;;;OASG;IACH,kBAAkB,CACjB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,GAClD,MAAM;IAoBT,QAAQ,IAAI,OAAO;CAGnB"}

package/dist/actions/transports_ws_backend.js

@@ -8,6 +8,9 @@ import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, to_jsonrpc_message_id, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
 import { create_uuid } from '../uuid.js';
 import { WS_CLOSE_SESSION_REVOKED } from './transports.js';
+/** Type guard for `FilterableBroadcastTransport`. */
+export const is_filterable_broadcast_transport = (transport) => 'broadcast_filtered' in transport &&
+    typeof transport.broadcast_filtered === 'function';
 export class BackendWebsocketTransport {
     transport_name = 'backend_websocket_rpc';
     // Map connection IDs to WebSocket contexts
@@ -135,6 +138,35 @@ export class BackendWebsocketTransport {
         // TODO hack - remove if not ever needed, I assume this will need to be async so let's hold that assumption
         return Promise.resolve();
     }
+    /**
+     * Broadcast to connections whose identity satisfies a predicate.
+     *
+     * Used by the broadcast API when a consumer supplies a subscription ACL hook
+     * (e.g. tx's `tx_run_created` only reaches the account that owns the run).
+     * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
+     * to skip the per-connection predicate overhead.
+     *
+     * @returns the number of sockets the message was sent to
+     */
+    broadcast_filtered(message, predicate) {
+        const serialized = JSON.stringify(message);
+        let count = 0;
+        for (const [connection_id, identity] of this.#connection_identities) {
+            if (!predicate(identity))
+                continue;
+            const ws = this.#connections.get(connection_id);
+            if (!ws)
+                continue;
+            try {
+                ws.send(serialized);
+                count++;
+            }
+            catch (error) {
+                console.error('[backend websocket transport] Error broadcasting filtered to client:', error);
+            }
+        }
+        return count;
+    }
     is_ready() {
         return this.#connections.size > 0;
     }

package/package.json

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