@fuzdev/fuz_app 0.23.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":"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;AAK1E,OAAO,EAAkB,KAAK,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAW1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AACrC,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;;OAKG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,4EAA4E;IAC5E,MAAM,EAAE,WAAW,CAAC;CACpB;AAED,4EAA4E;AAC5E,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,kBAAkB,IAAI,CAC9D,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,IAAI,KACL,OAAO,CAAC;AAEb;;;;;;;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,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,yFAAyF;IACzF,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD;;;;;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,+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,sBAwRF,CAAC"}
+{"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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"}

package/dist/actions/socket.svelte.js

@@ -5,16 +5,28 @@
  * 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
  */
 import { BROWSER } from 'esm-env';
-import { WS_CLOSE_SESSION_REVOKED } from './transports.js';
+import { JSONRPC_VERSION } from '../http/jsonrpc.js';
+import { WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, WS_CLOSE_SESSION_REVOKED } from './transports.js';
+import { HEARTBEAT_METHOD } from './heartbeat.js';
 /** Default WebSocket close code (normal closure). */
 export const DEFAULT_CLOSE_CODE = 1000;
 /** Base reconnect delay in ms. */
@@ -23,6 +35,12 @@ export const DEFAULT_RECONNECT_DELAY = 1000;
 export const DEFAULT_RECONNECT_DELAY_MAX = 10000;
 /** Exponential backoff factor: delay = base * factor^(attempt-1). */
 export const DEFAULT_BACKOFF_FACTOR = 1.5;
+/** Idle interval before sending a heartbeat (ms). */
+export const DEFAULT_HEARTBEAT_INTERVAL = 30_000;
+/** Max receive silence before closing with {@link WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT} (ms). */
+export const DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT = 60_000;
+/** Default bound on buffered requests while disconnected. Overflow rejects. */
+export const DEFAULT_QUEUE_MAX_SIZE = 100;
 /**
  * Reactive WebSocket client implementing `WebsocketConnection`.
  *
@@ -40,7 +58,20 @@ export class FrontendWebsocketClient {
     #reconnect_delay;
     #reconnect_delay_max;
     #backoff_factor;
+    #heartbeat_enabled;
+    #heartbeat_interval;
+    #heartbeat_receive_timeout;
+    #queue_enabled;
+    #queue_max_size;
     #log;
+    #next_request_id = 0;
+    #pending = new Map();
+    #queue = [];
+    #heartbeat_timer = null;
+    /** Epoch ms of the last outgoing send — used by the heartbeat activity check. */
+    #last_send_time = null;
+    /** Epoch ms of the last incoming message — used by the heartbeat activity check. */
+    #last_receive_time = null;
     ws = $state.raw(null);
     status = $state.raw('initial');
     reconnect_count = $state.raw(0);
@@ -77,6 +108,16 @@ export class FrontendWebsocketClient {
         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;
+        const heartbeat = options.heartbeat;
+        this.#heartbeat_enabled = heartbeat !== false;
+        const heartbeat_config = typeof heartbeat === 'object' ? heartbeat : {};
+        this.#heartbeat_interval = heartbeat_config.interval ?? DEFAULT_HEARTBEAT_INTERVAL;
+        this.#heartbeat_receive_timeout =
+            heartbeat_config.receive_timeout ?? DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT;
+        const queue = options.queue;
+        this.#queue_enabled = queue !== false;
+        const queue_config = typeof queue === 'object' ? queue : {};
+        this.#queue_max_size = queue_config.max_size ?? DEFAULT_QUEUE_MAX_SIZE;
         this.#log = options.log ?? null;
     }
     /**
@@ -184,10 +225,12 @@ export class FrontendWebsocketClient {
      */
     disconnect(code = DEFAULT_CLOSE_CODE) {
         this.#cancel_reconnect();
+        this.#cancel_heartbeat();
         this.#teardown(code);
         this.status = 'closed';
         this.reconnect_count = 0;
         this.current_reconnect_delay = 0;
+        this.#reject_all('client disconnected');
     }
     /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
     [Symbol.dispose]() {
@@ -199,6 +242,7 @@ export class FrontendWebsocketClient {
         try {
             this.ws.send(JSON.stringify(data));
             this.last_send_error = null;
+            this.#last_send_time = Date.now();
             return true;
         }
         catch (error) {
@@ -207,6 +251,81 @@ export class FrontendWebsocketClient {
             return false;
         }
     }
+    /**
+     * 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(method, params = {}, options = {}) {
+        return new Promise((resolve, reject) => {
+            const resolve_typed = resolve;
+            const reject_typed = reject;
+            if (this.#revoked) {
+                reject_typed(new Error('[socket] session revoked'));
+                return;
+            }
+            const { signal = null } = options;
+            if (signal?.aborted) {
+                reject_typed(this.#build_abort_error(method));
+                return;
+            }
+            const id = ++this.#next_request_id;
+            const frame = { jsonrpc: JSONRPC_VERSION, id, method, params };
+            // Bind the signal listener up-front so `#detach_signal` can find it by
+            // reference regardless of which settlement path runs (inline send,
+            // queued flush, close-time reject).
+            let pending = null;
+            const signal_handler = signal
+                ? () => {
+                    if (!pending)
+                        return;
+                    this.#pending.delete(id);
+                    this.#drop_queued(id);
+                    this.#detach_signal(pending);
+                    pending = null;
+                    reject_typed(this.#build_abort_error(method));
+                }
+                : null;
+            if (signal && signal_handler)
+                signal.addEventListener('abort', signal_handler);
+            pending = { method, resolve: resolve_typed, reject: reject_typed, signal, signal_handler };
+            const should_queue = options.queue !== false && this.#queue_enabled;
+            if (this.connected && this.ws) {
+                const sent = this.send(frame);
+                if (sent) {
+                    this.#pending.set(id, pending);
+                    return;
+                }
+                // Send failed mid-connected (serialization, buffer full). Requeue if
+                // the queue is on, otherwise reject — this socket is in an odd
+                // state but the caller asked for non-durable semantics.
+                if (should_queue) {
+                    this.#enqueue({ ...pending, id, frame });
+                    return;
+                }
+                this.#detach_signal(pending);
+                reject_typed(new Error(`[socket] send failed for ${method}`));
+                return;
+            }
+            if (should_queue) {
+                this.#enqueue({ ...pending, id, frame });
+                return;
+            }
+            this.#detach_signal(pending);
+            reject_typed(new Error(`[socket] not connected (method=${method})`));
+        });
+    }
     add_message_handler(handler) {
         this.#message_handlers.add(handler);
         return () => this.#message_handlers.delete(handler);
@@ -215,6 +334,124 @@ export class FrontendWebsocketClient {
         this.#error_handlers.add(handler);
         return () => this.#error_handlers.delete(handler);
     }
+    #build_abort_error(method) {
+        return new Error(`[socket] request aborted (method=${method})`);
+    }
+    #detach_signal(pending) {
+        if (pending.signal && pending.signal_handler) {
+            pending.signal.removeEventListener('abort', pending.signal_handler);
+        }
+    }
+    #enqueue(queued) {
+        if (this.#queue.length >= this.#queue_max_size) {
+            this.#detach_signal(queued);
+            queued.reject(new Error(`[socket] request queue overflow (method=${queued.method}, max=${this.#queue_max_size})`));
+            return;
+        }
+        this.#queue.push(queued);
+    }
+    #drop_queued(id) {
+        const index = this.#queue.findIndex((q) => q.id === id);
+        if (index !== -1)
+            this.#queue.splice(index, 1);
+    }
+    #flush_queue() {
+        if (!this.connected || !this.ws)
+            return;
+        const queued = this.#queue;
+        this.#queue = [];
+        for (const q of queued) {
+            if (q.signal?.aborted) {
+                this.#detach_signal(q);
+                q.reject(this.#build_abort_error(q.method));
+                continue;
+            }
+            const sent = this.send(q.frame);
+            if (sent) {
+                this.#pending.set(q.id, {
+                    method: q.method,
+                    resolve: q.resolve,
+                    reject: q.reject,
+                    signal: q.signal,
+                    signal_handler: q.signal_handler,
+                });
+            }
+            else {
+                this.#detach_signal(q);
+                q.reject(new Error(`[socket] queued request send failed (method=${q.method})`));
+            }
+        }
+    }
+    #reject_all(reason) {
+        const pending = this.#pending;
+        this.#pending = new Map();
+        for (const [id, p] of pending) {
+            this.#detach_signal(p);
+            p.reject(new Error(`[socket] ${reason} (method=${p.method}, id=${id})`));
+        }
+        const queued = this.#queue;
+        this.#queue = [];
+        for (const q of queued) {
+            this.#detach_signal(q);
+            q.reject(new Error(`[socket] ${reason} (method=${q.method})`));
+        }
+    }
+    #reject_pending_only(reason) {
+        // Socket closed but auto-reconnect will try again — pending requests were
+        // in flight on the old socket so we can't correlate them after reopen;
+        // queued requests haven't been sent yet and stay buffered for the flush.
+        const pending = this.#pending;
+        this.#pending = new Map();
+        for (const [id, p] of pending) {
+            this.#detach_signal(p);
+            p.reject(new Error(`[socket] ${reason} (method=${p.method}, id=${id})`));
+        }
+    }
+    #start_heartbeat() {
+        this.#cancel_heartbeat();
+        if (!this.#heartbeat_enabled)
+            return;
+        const now = Date.now();
+        this.#last_send_time = now;
+        this.#last_receive_time = now;
+        // Run the check at half the interval so any 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 tick = Math.max(100, Math.floor(this.#heartbeat_interval / 2));
+        this.#heartbeat_timer = setInterval(() => this.#heartbeat_tick(), tick);
+    }
+    #cancel_heartbeat() {
+        if (this.#heartbeat_timer !== null) {
+            clearInterval(this.#heartbeat_timer);
+            this.#heartbeat_timer = null;
+        }
+    }
+    #heartbeat_tick() {
+        if (!this.connected || !this.ws)
+            return;
+        const now = Date.now();
+        const last_receive = this.#last_receive_time ?? now;
+        if (now - last_receive >= this.#heartbeat_receive_timeout) {
+            this.#log?.info(`[socket] receive timeout (${now - last_receive}ms) — closing ${WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT}`);
+            try {
+                this.ws.close(WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, 'client heartbeat timeout');
+            }
+            catch (error) {
+                this.#log?.error('[socket] heartbeat timeout close failed:', error);
+            }
+            return;
+        }
+        const last_activity = Math.max(this.#last_send_time ?? 0, last_receive);
+        if (now - last_activity >= this.#heartbeat_interval) {
+            // Fire-and-forget the heartbeat. If it fails (network, serialization),
+            // receive-silence detection above will close the socket on the next
+            // tick. No queue — the heartbeat is the thing that tells us the
+            // queue needs flushing, it must not fight the queue for the slot.
+            void this.request(HEARTBEAT_METHOD, {}, { queue: false }).catch((error) => {
+                this.#log?.debug('[socket] heartbeat request failed:', error);
+            });
+        }
+    }
     #teardown(close_code) {
         if (!this.ws)
             return;
@@ -222,6 +459,7 @@ export class FrontendWebsocketClient {
         this.ws.removeEventListener('close', this.#handle_close);
         this.ws.removeEventListener('error', this.#handle_error);
         this.ws.removeEventListener('message', this.#handle_message);
+        this.#cancel_heartbeat();
         if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
             try {
                 this.ws.close(close_code);
@@ -230,8 +468,10 @@ export class FrontendWebsocketClient {
                 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.
+            // record it here so the client-initiated close is still observable,
+            // and reject any pending requests that can never resolve now.
             this.#record_close(close_code, '');
+            this.#reject_pending_only(`socket torn down (code ${close_code})`);
         }
         this.ws = null;
     }
@@ -267,12 +507,16 @@ export class FrontendWebsocketClient {
         this.current_reconnect_delay = 0;
         this.last_connect_time = Date.now();
         this.#cancel_reconnect();
+        this.#start_heartbeat();
+        // Flush buffered requests before anyone else can observe the open state.
+        this.#flush_queue();
     };
     #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);
+        this.#cancel_heartbeat();
         // Session revocation is terminal — reconnecting would 401 in a loop.
         if (event.code === WS_CLOSE_SESSION_REVOKED) {
             this.#revoked = true;
@@ -280,8 +524,12 @@ export class FrontendWebsocketClient {
             this.#cancel_reconnect();
             this.reconnect_count = 0;
             this.current_reconnect_delay = 0;
+            this.#reject_all('session revoked');
             return;
         }
+        // Pending in-flight requests can't be correlated post-reconnect; reject
+        // them. Queue stays so the flush on reopen replays unsent work.
+        this.#reject_pending_only(`connection closed (code ${event.code})`);
         // Let `#schedule_reconnect` set `status: 'reconnecting'` directly to avoid
         // a transient `'closed'` flicker; only set `'closed'` when reconnect is off.
         if (this.#auto_reconnect) {
@@ -289,6 +537,7 @@ export class FrontendWebsocketClient {
         }
         else {
             this.status = 'closed';
+            this.#reject_all('connection closed, auto-reconnect disabled');
         }
     };
     #handle_error = (event) => {
@@ -304,6 +553,39 @@ export class FrontendWebsocketClient {
         // Browsers fire `close` after error; reconnect logic lives there.
     };
     #handle_message = (event) => {
+        this.#last_receive_time = Date.now();
+        // Intercept JSON-RPC responses for pending `request()` calls. Parse
+        // defensively — if the frame isn't valid JSON or isn't a response, fall
+        // through to the registered message handlers (which still see every
+        // notification, plus any stray response we don't own).
+        let json;
+        try {
+            json = JSON.parse(String(event.data));
+        }
+        catch {
+            json = undefined;
+        }
+        if (typeof json === 'object' &&
+            json !== null &&
+            'id' in json &&
+            ('result' in json || 'error' in json)) {
+            const id = json.id;
+            if (id !== null) {
+                const pending = this.#pending.get(id);
+                if (pending) {
+                    this.#pending.delete(id);
+                    this.#detach_signal(pending);
+                    if ('error' in json && json.error) {
+                        const err = json.error;
+                        pending.reject(new Error(`[rpc ${pending.method} #${id}] ${err.code ?? '?'} ${err.message ?? 'unknown error'}`));
+                    }
+                    else {
+                        pending.resolve(json.result);
+                    }
+                    return;
+                }
+            }
+        }
         for (const handler of this.#message_handlers) {
             try {
                 handler(event);

package/dist/actions/transports.d.ts

@@ -10,6 +10,10 @@ import { z } from 'zod';
 import type { JsonrpcMessageFromClientToServer, JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 /** WebSocket close code for session revocation. */
 export declare const WS_CLOSE_SESSION_REVOKED = 4001;
+/** WebSocket close code — client timed out waiting for a response. */
+export declare const WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002;
+/** WebSocket close code — server timed out with no incoming activity. */
+export declare const WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT = 4003;
 export declare const TransportName: z.ZodString;
 export type TransportName = z.infer<typeof TransportName>;
 export interface Transport {

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

@@ -1 +1 @@
-{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAK7C,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACzE,IAAI,CAAC,OAAO,EAAE,gCAAgC,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IAClG,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,UAAU;;IAItB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAQ;IAE/B;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAS9C,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,IAAI;IAM1D;;;;;OAKG;IACH,aAAa,CAAC,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;IAO/D,QAAQ,IAAI,OAAO,GAAG,IAAI;IAM1B,qBAAqB,IAAI,SAAS,GAAG,IAAI;IAIzC,0BAA0B,IAAI,aAAa,GAAG,IAAI;IAIlD,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;CAqDtE"}
+{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,sEAAsE;AACtE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAKtD,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACzE,IAAI,CAAC,OAAO,EAAE,gCAAgC,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IAClG,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,UAAU;;IAItB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAQ;IAE/B;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAS9C,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,IAAI;IAM1D;;;;;OAKG;IACH,aAAa,CAAC,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;IAO/D,QAAQ,IAAI,OAAO,GAAG,IAAI;IAM1B,qBAAqB,IAAI,SAAS,GAAG,IAAI;IAIzC,0BAA0B,IAAI,aAAa,GAAG,IAAI;IAIlD,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;CAqDtE"}

package/dist/actions/transports.js

@@ -9,6 +9,10 @@
 import { z } from 'zod';
 /** WebSocket close code for session revocation. */
 export const WS_CLOSE_SESSION_REVOKED = 4001;
+/** WebSocket close code — client timed out waiting for a response. */
+export const WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002;
+/** WebSocket close code — server timed out with no incoming activity. */
+export const WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT = 4003;
 // TODO figure out the symmetry of frontend and backend transports (none/partial/full?) --
 // we may also need orthogonal abstractions to clarify the transport role
 export const TransportName = z.string(); // not branded for convenience, will just error at runtime, the schema is just for docs atm

package/dist/testing/ws_round_trip.d.ts

@@ -40,8 +40,9 @@ import type { Context } from 'hono';
 import { WSContext, type UpgradeWebSocket, type WSEvents } from 'hono/ws';
 import { Logger } from '@fuzdev/fuz_util/log.js';
 import type { ActionSpecUnion } from '../actions/action_spec.js';
+import type { Action } from '../actions/action_types.js';
 import type { ActionEventEnvironment } from '../actions/action_event_types.js';
-import { type BaseHandlerContext, type RegisterActionWsOptions, type WsActionHandler } from '../actions/register_action_ws.js';
+import { type BaseHandlerContext, type RegisterActionWsOptions } from '../actions/register_action_ws.js';
 import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 import { type RequestContext } from '../auth/request_context.js';
 import { type CredentialType } from '../hono_context.js';
@@ -202,11 +203,22 @@ export declare const is_notification_with: <P>(method: string, match: (params: P
 export declare const is_response_for: (id: number | string) => (msg: unknown) => boolean;
 /** Options for `create_ws_test_harness`. */
 export interface CreateWsTestHarnessOptions<TCtx extends BaseHandlerContext> {
-    specs: ReadonlyArray<ActionSpecUnion>;
-    handlers: Record<string, WsActionHandler<TCtx>>;
+    /**
+     * The actions registered on this endpoint — matches the shape
+     * `register_action_ws` accepts. Each entry is a `{spec, handler?}` tuple;
+     * shared fuz_app primitives (like `heartbeat_action`) can be spread in
+     * alongside consumer-specific actions.
+     */
+    actions: ReadonlyArray<Action<TCtx>>;
     extend_context?: RegisterActionWsOptions<TCtx>['extend_context'];
     /** Pass a pre-created transport to share with a broadcast API. */
     transport?: BackendWebsocketTransport;
+    /**
+     * Threaded through to `register_action_ws`. Defaults to `false` in tests —
+     * fake timers + receive-silence detection need explicit opt-in and per-
+     * test tuning to avoid spurious closes.
+     */
+    heartbeat?: RegisterActionWsOptions<TCtx>['heartbeat'];
     /** Optional logger. Defaults to a silent `[ws-test]` logger. */
     log?: Logger;
     /** Threaded straight through to `register_action_ws`. */

package/dist/testing/ws_round_trip.d.ts.map

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

package/dist/testing/ws_round_trip.js

@@ -249,7 +249,7 @@ const build_simple_request_context = (role) => {
  * `onOpen`/`onMessage`/`onClose` path against a real `WSContext`.
  */
 export const create_ws_test_harness = (options) => {
-    const { specs, handlers, extend_context = (base) => base, transport = new BackendWebsocketTransport(), log = new Logger('[ws-test]', { level: 'off' }), on_socket_open, on_socket_close, } = options;
+    const { actions, extend_context = (base) => base, transport = new BackendWebsocketTransport(), heartbeat = false, log = new Logger('[ws-test]', { level: 'off' }), on_socket_open, on_socket_close, } = options;
     const stub = create_stub_upgrade();
     // Minimal Hono stub — `register_action_ws` only needs `.get(path, handler)`.
     const stub_app = { get: () => stub_app };
@@ -257,10 +257,10 @@ export const create_ws_test_harness = (options) => {
         path: '/test/ws',
         app: stub_app,
         upgradeWebSocket: stub.upgradeWebSocket,
-        specs,
-        handlers,
+        actions,
         extend_context,
         transport,
+        heartbeat,
         log,
         on_socket_open,
         on_socket_close,

package/package.json

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