@fuzdev/fuz_app 0.22.0 → 0.24.0

package/dist/actions/action_types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared type surface for the action system — context, handler, composable Action tuple.
+ *
+ * These types sit above `action_spec.ts` (pure Zod schemas) and below the
+ * dispatchers (`register_action_ws.ts`, `action_rpc.ts`). Extracted so the
+ * shared composable fuz_app actions (e.g. `heartbeat_action`) can name them
+ * without pulling in server-only modules.
+ *
+ * @module
+ */
+import type { JsonrpcRequestId } from '../http/jsonrpc.js';
+import type { ActionSpecUnion } from './action_spec.js';
+/**
+ * Minimum per-request context every server-side WS handler receives.
+ *
+ * Consumers extend this with domain-specific fields via the dispatcher's
+ * `extend_context` option. Mirrors the HTTP-side `ActionContext` and Rust's
+ * `Ctx<'a>` shape (`request_id` + `NotifyFn` + `CancellationToken`).
+ */
+export interface BaseHandlerContext {
+    /** JSON-RPC envelope request id — echoed back on the response. */
+    request_id: JsonrpcRequestId;
+    /**
+     * Send a request-scoped JSON-RPC notification to the originating socket.
+     * Not a broadcast — the message only reaches the client whose request
+     * triggered this handler.
+     */
+    notify: (method: string, params: unknown) => void;
+    /** Fires on socket close; streaming handlers poll for early termination. */
+    signal: AbortSignal;
+}
+/**
+ * Handler signature — receives validated input and per-request context.
+ *
+ * Named to disambiguate from `actions/action_rpc.ts`'s `ActionHandler`
+ * (HTTP-side, `ActionContext` + two generic slots). The WS variant is
+ * single-slotted on the context and returns `unknown`.
+ */
+export type WsActionHandler<TCtx extends BaseHandlerContext = BaseHandlerContext> = (input: unknown, ctx: TCtx) => unknown;
+/**
+ * A spec paired with its optional handler — the composable unit passed to
+ * {@link register_action_ws} and {@link create_rpc_client}. The server uses
+ * both fields; the client reads only {@link spec} (the {@link handler} is
+ * ignored, harmless). Shared fuz_app primitives (e.g. `heartbeat_action`)
+ * export a complete tuple so consumers spread them into both sides'
+ * `actions` array without inventing per-repo ping plumbing.
+ *
+ * Left open for future fields (`rate_limit`, ACL, middleware hooks) so
+ * additions attach to the action itself instead of scattering across
+ * parallel arrays.
+ */
+export interface Action<TCtx extends BaseHandlerContext = BaseHandlerContext> {
+    spec: ActionSpecUnion;
+    /** Server-side handler. Ignored by the client. Omit for client-only specs. */
+    handler?: WsActionHandler<TCtx>;
+}
+//# sourceMappingURL=action_types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action_types.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,4EAA4E;IAC5E,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB,IAAI,CACnF,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,IAAI,KACL,OAAO,CAAC;AAEb;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB;IAC3E,IAAI,EAAE,eAAe,CAAC;IACtB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC;CAChC"}

package/dist/actions/action_types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared type surface for the action system — context, handler, composable Action tuple.
+ *
+ * These types sit above `action_spec.ts` (pure Zod schemas) and below the
+ * dispatchers (`register_action_ws.ts`, `action_rpc.ts`). Extracted so the
+ * shared composable fuz_app actions (e.g. `heartbeat_action`) can name them
+ * without pulling in server-only modules.
+ *
+ * @module
+ */
+export {};

package/dist/actions/heartbeat.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared heartbeat action — the first composable fuz_app primitive carrying
+ * both a spec and a handler in one tuple. Consumers spread
+ * {@link heartbeat_action} into both the server's and the client's `actions`
+ * array so disconnect detection works identically across every repo without
+ * per-consumer ping plumbing.
+ *
+ * The client's activity-aware heartbeat timer (in
+ * `FrontendWebsocketClient`) issues a `heartbeat` request whenever the
+ * connection has been idle for its configured interval; server-side the
+ * dispatcher tracks receive time, so incoming heartbeats keep the socket
+ * alive without any handler-level state.
+ *
+ * Nullary input/output today. `{client_ts, server_ts}` fields can be added
+ * later if clock-skew telemetry ever matters — the {@link Action} container
+ * is open for additions without churning consumer call sites.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { Action } from './action_types.js';
+/** Method name on the wire — shared across every fuz_app consumer. */
+export declare const HEARTBEAT_METHOD = "heartbeat";
+/**
+ * `ActionSpec` for the shared heartbeat. `authenticated` auth — upgrade-time
+ * auth has already admitted the socket; heartbeats don't need role gating.
+ * `side_effects: false` keeps it orthogonal to state changes.
+ */
+export declare const heartbeat_action_spec: {
+    method: string;
+    initiator: "both" | "frontend" | "backend";
+    side_effects: boolean;
+    input: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    output: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    description: string;
+    kind: "request_response";
+    auth: "authenticated" | "keeper" | "public" | {
+        role: string;
+    };
+    async: true;
+    streams?: string | undefined;
+};
+/** Handler — nullary echo. Stateless, suitable for high-frequency pings. */
+export declare const heartbeat_handler: () => Record<string, never>;
+/**
+ * Composable tuple — spread into the server's `actions` array for dispatch
+ * and into the client's `actions` array so `create_rpc_client` types
+ * `app.api.heartbeat()` against the shared spec.
+ */
+export declare const heartbeat_action: Action;
+//# sourceMappingURL=heartbeat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAUhC,CAAC;AAEH,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAO,MAAM,CAAC,MAAM,EAAE,KAAK,CAAS,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAG9B,CAAC"}

package/dist/actions/heartbeat.js

@@ -0,0 +1,50 @@
+/**
+ * Shared heartbeat action — the first composable fuz_app primitive carrying
+ * both a spec and a handler in one tuple. Consumers spread
+ * {@link heartbeat_action} into both the server's and the client's `actions`
+ * array so disconnect detection works identically across every repo without
+ * per-consumer ping plumbing.
+ *
+ * The client's activity-aware heartbeat timer (in
+ * `FrontendWebsocketClient`) issues a `heartbeat` request whenever the
+ * connection has been idle for its configured interval; server-side the
+ * dispatcher tracks receive time, so incoming heartbeats keep the socket
+ * alive without any handler-level state.
+ *
+ * Nullary input/output today. `{client_ts, server_ts}` fields can be added
+ * later if clock-skew telemetry ever matters — the {@link Action} container
+ * is open for additions without churning consumer call sites.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { RequestResponseActionSpec } from './action_spec.js';
+/** Method name on the wire — shared across every fuz_app consumer. */
+export const HEARTBEAT_METHOD = 'heartbeat';
+/**
+ * `ActionSpec` for the shared heartbeat. `authenticated` auth — upgrade-time
+ * auth has already admitted the socket; heartbeats don't need role gating.
+ * `side_effects: false` keeps it orthogonal to state changes.
+ */
+export const heartbeat_action_spec = RequestResponseActionSpec.parse({
+    method: HEARTBEAT_METHOD,
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: false,
+    input: z.strictObject({}),
+    output: z.strictObject({}),
+    async: true,
+    description: 'Shared activity ping — keeps the socket alive and exercises the dispatch path.',
+});
+/** Handler — nullary echo. Stateless, suitable for high-frequency pings. */
+export const heartbeat_handler = () => ({});
+/**
+ * Composable tuple — spread into the server's `actions` array for dispatch
+ * and into the client's `actions` array so `create_rpc_client` types
+ * `app.api.heartbeat()` against the shared spec.
+ */
+export const heartbeat_action = {
+    spec: heartbeat_action_spec,
+    handler: heartbeat_handler,
+};

package/dist/actions/register_action_ws.d.ts

@@ -24,34 +24,12 @@
 import type { Context, Hono } from 'hono';
 import type { UpgradeWebSocket, WSContext } from 'hono/ws';
 import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
-import { type JsonrpcRequestId } from '../http/jsonrpc.js';
 import type { Uuid } from '../uuid.js';
-import type { ActionSpecUnion } from './action_spec.js';
+import { type Action, type BaseHandlerContext, type WsActionHandler } from './action_types.js';
 import { BackendWebsocketTransport, type ConnectionIdentity } from './transports_ws_backend.js';
-/**
- * Minimum per-request context every handler receives.
- *
- * Consumers extend this with domain-specific fields via
- * `RegisterActionWsOptions.extend_context` (e.g., a `backend` singleton
- * or the authenticated `RequestContext`). Keeping the base minimal matches
- * the HTTP-side `ActionContext` (from `actions/action_rpc.ts`) and mirrors
- * Rust's `Ctx<'a>` shape (`request_id` + `NotifyFn` + `CancellationToken`).
- */
-export interface BaseHandlerContext {
-    /** JSON-RPC envelope request id — echoed back on the response. */
-    request_id: JsonrpcRequestId;
-    /**
-     * Send a request-scoped JSON-RPC notification to the originating socket.
-     * Not a broadcast — the message only reaches the client whose request
-     * triggered this handler. Streaming handlers (e.g. `completion_progress`)
-     * route chunks through this.
-     */
-    notify: (method: string, params: unknown) => void;
-    /** Fires on socket close; streaming handlers poll for early termination. */
-    signal: AbortSignal;
-}
-/** Handler signature — receives validated input and per-request context. */
-export type WsActionHandler<TCtx extends BaseHandlerContext> = (input: unknown, ctx: TCtx) => unknown;
+export type { Action, BaseHandlerContext, WsActionHandler };
+/** Default inactivity window before the server closes a silent socket. */
+export declare const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60000;
 /**
  * Context passed to the `on_socket_open` hook.
  *
@@ -91,6 +69,15 @@ export interface SocketCloseContext {
     /** Auth identity captured at open time — still valid even if the transport already cleaned up. */
     identity: ConnectionIdentity;
 }
+export interface ServerHeartbeatOptions {
+    /**
+     * Receive-silence (ms) past which the server closes the socket with
+     * {@link WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT}. Any incoming message resets
+     * the counter — chatty clients never trip it. First {@link timeout}
+     * window after socket open is exempt (cold-start grace).
+     */
+    timeout?: number;
+}
 /** Options for `register_action_ws`. */
 export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
     /** Mount path (e.g., `/api/ws`). */
@@ -99,10 +86,14 @@ export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
     app: Hono;
     /** Hono's `upgradeWebSocket` helper from the runtime adapter. */
     upgradeWebSocket: UpgradeWebSocket;
-    /** Action specs — drives method lookup, per-action auth, and input/output validation. */
-    specs: ReadonlyArray<ActionSpecUnion>;
-    /** Handler map keyed by `spec.method`. */
-    handlers: Record<string, WsActionHandler<TCtx>>;
+    /**
+     * The actions registered on this endpoint — each carries a spec (drives
+     * method lookup, per-action auth, input/output validation) and an
+     * optional handler (omit for client-only specs like inbound
+     * notifications). Include the shared {@link heartbeat_action} here to
+     * complete the disconnect-detection pairing with the frontend client.
+     */
+    actions: ReadonlyArray<Action<TCtx>>;
     /**
      * Build the per-request context from the base and the upgrade-time Hono
      * context. Called once per incoming message. Consumers use this to attach
@@ -116,6 +107,13 @@ export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
      * handle for `create_ws_auth_guard` and `send_to`/`broadcast`.
      */
     transport?: BackendWebsocketTransport;
+    /**
+     * Server-side heartbeat policy. Default-on (receive-silence detection,
+     * 60s timeout). `false` disables the timer entirely — only do this if
+     * the upstream stack (TCP keepalive, Cloudflare idle timeout, etc.)
+     * already owns disconnect detection. Pass an object to tune the timeout.
+     */
+    heartbeat?: boolean | ServerHeartbeatOptions;
     /** Optional per-message delay for testing loading states. Ignored when `0`. */
     artificial_delay?: number;
     /** Optional logger; defaults to `[ws]` namespace. */

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":"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"}
+{"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;AAE7F,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,sBA0UF,CAAC"}

package/dist/actions/register_action_ws.js

@@ -31,7 +31,11 @@ import { JSONRPC_VERSION } from '../http/jsonrpc.js';
 import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, create_jsonrpc_notification, to_jsonrpc_message_id, to_jsonrpc_params, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
 import { CREDENTIAL_TYPE_KEY, AUTH_API_TOKEN_ID_KEY } from '../hono_context.js';
+import {} from './action_types.js';
+import { WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT } from './transports.js';
 import { BackendWebsocketTransport } from './transports_ws_backend.js';
+/** Default inactivity window before the server closes a silent socket. */
+export const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60_000;
 /**
  * Mount a JSON-RPC WebSocket endpoint that dispatches to the supplied handler
  * map. Per-request context is built from the base + consumer-provided
@@ -51,9 +55,24 @@ import { BackendWebsocketTransport } from './transports_ws_backend.js';
  *   `create_ws_auth_guard` or broadcast on audit events.
  */
 export const register_action_ws = (options) => {
-    const { path, app, upgradeWebSocket, specs, handlers, extend_context, transport = new BackendWebsocketTransport(), artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, } = options;
-    // Build spec lookup for per-action auth and input validation.
-    const spec_by_method = new Map(specs.map((spec) => [spec.method, spec]));
+    const { path, app, upgradeWebSocket, actions, extend_context, transport = new BackendWebsocketTransport(), heartbeat = true, artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, } = options;
+    // Fan the unified actions array into the two lookups the dispatcher
+    // consults at message time. Keeping them internal means the composable
+    // `{spec, handler}` tuple remains the only shape consumers name.
+    const spec_by_method = new Map();
+    const handlers = {};
+    for (const action of actions) {
+        spec_by_method.set(action.spec.method, action.spec);
+        if (action.handler)
+            handlers[action.spec.method] = action.handler;
+    }
+    const heartbeat_enabled = heartbeat !== false;
+    const heartbeat_config = typeof heartbeat === 'object' ? heartbeat : {};
+    const heartbeat_timeout = heartbeat_config.timeout ?? DEFAULT_SERVER_HEARTBEAT_TIMEOUT;
+    // Run the checker on timeout/2 so event-loop blockage pauses the timer
+    // itself — a dead-because-blocked socket is close enough to
+    // dead-because-unresponsive that closing is arguably correct.
+    const heartbeat_tick_interval = Math.max(100, Math.floor(heartbeat_timeout / 2));
     app.get(path, upgradeWebSocket((c) => {
         // Upgrade-time auth extraction — `require_auth` middleware has already
         // rejected unauthenticated requests, so request_context is guaranteed
@@ -83,6 +102,18 @@ export const register_action_ws = (options) => {
         // Captured on open, consumed on close. Null before onOpen fires or
         // when a consumer never opens (e.g. immediate disconnect).
         let captured_connection_id = null;
+        // Receive-silence watchdog. Seeded to open-time so the first window is
+        // exempt (cold-start grace — avoid killing mid-handshake sockets).
+        // Bumped by onMessage. Any incoming activity counts, not just
+        // heartbeats — chatty clients don't need to send extras.
+        let last_receive_time = 0;
+        let heartbeat_timer = null;
+        const stop_heartbeat_timer = () => {
+            if (heartbeat_timer !== null) {
+                clearInterval(heartbeat_timer);
+                heartbeat_timer = null;
+            }
+        };
         // Socket-scoped notification helper — routes to this socket only,
         // matches the `ctx.notify` semantics exposed to per-message handlers.
         const notify_socket = (ws) => (notify_method, notify_params) => {
@@ -99,6 +130,23 @@ export const register_action_ws = (options) => {
                 const connection_id = transport.add_connection(ws, token_hash, account_id, api_token_id);
                 captured_connection_id = connection_id;
                 log.debug('ws opened', connection_id, event);
+                if (heartbeat_enabled) {
+                    last_receive_time = Date.now();
+                    heartbeat_timer = setInterval(() => {
+                        const now = Date.now();
+                        const silence = now - last_receive_time;
+                        if (silence >= heartbeat_timeout) {
+                            log.info(`heartbeat timeout (${silence}ms) — closing ${WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT}`, connection_id, identity.account_id);
+                            stop_heartbeat_timer();
+                            try {
+                                ws.close(WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT, 'server heartbeat timeout');
+                            }
+                            catch (error) {
+                                log.error('heartbeat timeout close failed:', error);
+                            }
+                        }
+                    }, heartbeat_tick_interval);
+                }
                 if (on_socket_open) {
                     try {
                         await on_socket_open({
@@ -122,6 +170,7 @@ export const register_action_ws = (options) => {
                 }
             },
             onMessage: async (event, ws) => {
+                last_receive_time = Date.now();
                 let json;
                 try {
                     json = JSON.parse(String(event.data)); // eslint-disable-line @typescript-eslint/no-base-to-string
@@ -220,6 +269,7 @@ export const register_action_ws = (options) => {
                 }
             },
             onClose: async (event, ws) => {
+                stop_heartbeat_timer();
                 socket_abort_controller.abort();
                 if (on_socket_close && captured_connection_id) {
                     try {

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

@@ -5,11 +5,21 @@
  * 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.
+ * server revokes auth), exposes reactive status for UI indicators, and ships
+ * three correctness primitives default-on:
  *
- * 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.
+ * - {@link FrontendWebsocketClient.request} — promise-based JSON-RPC with
+ *   auto-assigned ids and a pending-id map. Intercepts responses on the
+ *   message path so request/response correlation is transport-level rather
+ *   than re-invented per consumer.
+ * - **Durable queue** — `request()` calls made while disconnected buffer up
+ *   to {@link DEFAULT_QUEUE_MAX_SIZE} requests and flush on reopen. Overflow
+ *   rejects with `queue_overflow`. Raw {@link FrontendWebsocketClient.send}
+ *   is drop-on-disconnect (fire-and-forget notifications want that).
+ * - **Activity-aware heartbeat** — idles fire a shared `heartbeat` request;
+ *   receive-silence past {@link DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT} closes
+ *   with {@link WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT} and lets auto-reconnect
+ *   pick back up.
  *
  * @module
  */
@@ -23,6 +33,12 @@ export declare const DEFAULT_RECONNECT_DELAY = 1000;
 export declare const DEFAULT_RECONNECT_DELAY_MAX = 10000;
 /** Exponential backoff factor: delay = base * factor^(attempt-1). */
 export declare const DEFAULT_BACKOFF_FACTOR = 1.5;
+/** Idle interval before sending a heartbeat (ms). */
+export declare const DEFAULT_HEARTBEAT_INTERVAL = 30000;
+/** Max receive silence before closing with {@link WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT} (ms). */
+export declare const DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT = 60000;
+/** Default bound on buffered requests while disconnected. Overflow rejects. */
+export declare const DEFAULT_QUEUE_MAX_SIZE = 100;
 /**
  * Client-side WebSocket status.
  *
@@ -44,12 +60,48 @@ export interface FrontendWebsocketReconnectOptions {
     /** Exponential backoff factor. Defaults to 1.5. */
     factor?: number;
 }
+export interface FrontendWebsocketHeartbeatOptions {
+    /**
+     * Idle duration (ms) after which a heartbeat is sent. Reset by any send or
+     * receive — chatty clients never emit extras. Defaults to
+     * {@link DEFAULT_HEARTBEAT_INTERVAL}.
+     */
+    interval?: number;
+    /**
+     * Receive-silence (ms) after which the client closes the socket with
+     * {@link WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT}, letting auto-reconnect kick
+     * in. Should be a comfortable multiple of {@link interval}. Defaults to
+     * {@link DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT}.
+     */
+    receive_timeout?: number;
+}
+export interface FrontendWebsocketQueueOptions {
+    /**
+     * Maximum number of requests held while the socket is disconnected.
+     * Enqueue past this rejects the new call with a `queue_overflow` error.
+     * Defaults to {@link DEFAULT_QUEUE_MAX_SIZE}.
+     */
+    max_size?: 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;
+    /**
+     * Activity-aware heartbeat. `true` or 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;
+    /**
+     * Durable queue for {@link FrontendWebsocketClient.request}. `true` or omit
+     * for defaults; `false` disables buffering (requests while disconnected
+     * reject immediately). Raw {@link FrontendWebsocketClient.send} is never
+     * queued — use `request()` for RPC semantics.
+     */
+    queue?: boolean | FrontendWebsocketQueueOptions;
     /** Optional logger for diagnostic messages. */
     log?: Logger | null;
 }
@@ -132,6 +184,26 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
     /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
     [Symbol.dispose](): void;
     send(data: object): boolean;
+    /**
+     * Promise-based JSON-RPC over the socket. Auto-assigns a monotonic request
+     * id, tracks the pending promise, and resolves when the server sends a
+     * matching response (or rejects on error frame, socket close, or aborted
+     * signal).
+     *
+     * While the socket is disconnected, the request is buffered in a bounded
+     * queue (default-on, {@link DEFAULT_QUEUE_MAX_SIZE}) and flushed on
+     * reopen. Pass `{queue: false}` to reject immediately when disconnected
+     * — used internally by the heartbeat, which must not fight the queue for
+     * the disconnect-detection slot.
+     *
+     * `AbortSignal` integration today rejects the local promise; the
+     * server-side cancel protocol (sending a `cancel` notification to abort
+     * the in-flight handler) lands in Phase 3c as a follow-up PR.
+     */
+    request<R = unknown>(method: string, params?: unknown, options?: {
+        signal?: AbortSignal;
+        queue?: boolean;
+    }): Promise<R>;
     add_message_handler(handler: SocketMessageHandler): () => void;
     add_error_handler(handler: SocketErrorHandler): () => void;
 }

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":"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;IACpD;;;;;;;;OAQG;IACH,eAAe,EAAE,KAAK,GAAG,IAAI,CAAoB;IASjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAyC;gBAExD,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,8BAAmC;IAWrE;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,SAAS,GAAE,OAAO,GAAG,iCAAiC,GAAG,IAAW,GAAG,IAAI;IA4CzF,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;IAa3B,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK9D,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;CAiH1D"}
+{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"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"}