@fuzdev/fuz_app 0.51.0 → 0.52.0

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

@@ -1 +1 @@
-{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE9F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,OAAO,EAGN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAW5B;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,8DAA8D;IAC9D,EAAE,EAAE,EAAE,CAAC;IACP,oFAAoF;IACpF,aAAa,EAAE,EAAE,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CACxD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,yBAAyB,EACjE,MAAM,KAAK,EACX,SAAS,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KACvE,SAGD,CAAC;AAEH,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACxC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;CACZ;AA4DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CAsQtF,CAAC"}
+{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE9F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,OAAO,EAGN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAW5B;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,8DAA8D;IAC9D,EAAE,EAAE,EAAE,CAAC;IACP,oFAAoF;IACpF,aAAa,EAAE,EAAE,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CACxD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,yBAAyB,EACjE,MAAM,KAAK,EACX,SAAS,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KACvE,SAGD,CAAC;AAEH,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACxC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;CACZ;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CAsQtF,CAAC"}

package/dist/actions/action_rpc.js

@@ -118,6 +118,10 @@ const check_action_auth = (auth, request_context, credential_type) => {
  *
  * @param options - endpoint path, actions, and logger
  * @returns route specs (GET + POST) ready for `apply_route_specs`
+ * @throws Error if two actions share the same `spec.method` (registration-time
+ *   duplicate detection); also throws if any action's `spec.input` is
+ *   `z.null()` (JSON-RPC 2.0 §4.2 forbids `params: null` on the wire — use
+ *   `z.void()` for parameterless methods).
  */
 export const create_rpc_endpoint = (options) => {
     const { path: endpoint_path, actions, log } = options;

package/dist/actions/action_spec.d.ts

@@ -5,6 +5,9 @@
  * auth, side effects, and input/output schemas. Bridge functions in
  * `actions/action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
  *
+ * @see `actions/action_rpc.ts` for the JSON-RPC dispatcher
+ * @see `actions/register_action_ws.ts` for the WebSocket dispatcher
+ *
  * TODO @action-system-review The action system (action_spec, action_registry,
  * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.
  * Current state: bridge is stable, registry and codegen are partially stub API.
@@ -59,6 +62,16 @@ export declare const ActionSpec: z.ZodObject<{
      * consumer-side concern.
      */
     streams: z.ZodOptional<z.ZodString>;
+    /**
+     * Error reason codes this action may surface via `error.data.reason` on
+     * failure. Declarative metadata mirroring the `streams` precedent —
+     * codegen, UI form-state matching, and docs read it off the spec instead
+     * of scanning handler implementations. Reuses the same `as const` string
+     * constants the handler throws (e.g. `ERROR_OFFER_*`) so call sites can
+     * import either side. Optional — actions that surface only standard
+     * transport errors leave it unset.
+     */
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
 }, z.core.$strict>;
 export type ActionSpec = z.infer<typeof ActionSpec>;
 export declare const RequestResponseActionSpec: z.ZodObject<{
@@ -73,6 +86,7 @@ export declare const RequestResponseActionSpec: z.ZodObject<{
     output: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"request_response">>;
     auth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
         role: z.ZodString;
@@ -90,6 +104,7 @@ export declare const RemoteNotificationActionSpec: z.ZodObject<{
     input: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"remote_notification">>;
     auth: z.ZodDefault<z.ZodNull>;
     side_effects: z.ZodDefault<z.ZodLiteral<true>>;
@@ -98,8 +113,8 @@ export declare const RemoteNotificationActionSpec: z.ZodObject<{
 }, z.core.$strict>;
 export type RemoteNotificationActionSpec = z.infer<typeof RemoteNotificationActionSpec>;
 /**
- * Local calls can wrap synchronous or asynchronous actions,
- * and are the escape hatch for remote APIs that do not support SAES.
+ * Local calls can wrap synchronous or asynchronous actions, and are the
+ * escape hatch for remote APIs that do not support SAES.
  */
 export declare const LocalCallActionSpec: z.ZodObject<{
     method: z.ZodString;
@@ -114,6 +129,7 @@ export declare const LocalCallActionSpec: z.ZodObject<{
     async: z.ZodBoolean;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"local_call">>;
     auth: z.ZodDefault<z.ZodNull>;
 }, z.core.$strict>;
@@ -130,6 +146,7 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     output: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"request_response">>;
     auth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
         role: z.ZodString;
@@ -145,6 +162,7 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     input: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"remote_notification">>;
     auth: z.ZodDefault<z.ZodNull>;
     side_effects: z.ZodDefault<z.ZodLiteral<true>>;
@@ -163,10 +181,12 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     async: z.ZodBoolean;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"local_call">>;
     auth: z.ZodDefault<z.ZodNull>;
 }, z.core.$strict>]>;
 export type ActionSpecUnion = z.infer<typeof ActionSpecUnion>;
+/** Structural type guard for any `ActionSpecUnion` variant — checks `kind` is one of the three known values. */
 export declare const is_action_spec: (value: unknown) => value is ActionSpecUnion;
 export declare const ActionEventPhase: z.ZodEnum<{
     send_request: "send_request";

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

@@ -1 +1 @@
-{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,UAAU;;oBAKrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;IAUtB;;;;;;OAMG;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,UAAU;;oBAKrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;IAUtB;;;;;;OAMG;;IAEH;;;;;;;;OAQG;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/actions/action_spec.js

@@ -5,6 +5,9 @@
  * auth, side effects, and input/output schemas. Bridge functions in
  * `actions/action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
  *
+ * @see `actions/action_rpc.ts` for the JSON-RPC dispatcher
+ * @see `actions/register_action_ws.ts` for the WebSocket dispatcher
+ *
  * TODO @action-system-review The action system (action_spec, action_registry,
  * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.
  * Current state: bridge is stable, registry and codegen are partially stub API.
@@ -40,6 +43,16 @@ export const ActionSpec = z.strictObject({
      * consumer-side concern.
      */
     streams: z.string().optional(),
+    /**
+     * Error reason codes this action may surface via `error.data.reason` on
+     * failure. Declarative metadata mirroring the `streams` precedent —
+     * codegen, UI form-state matching, and docs read it off the spec instead
+     * of scanning handler implementations. Reuses the same `as const` string
+     * constants the handler throws (e.g. `ERROR_OFFER_*`) so call sites can
+     * import either side. Optional — actions that surface only standard
+     * transport errors leave it unset.
+     */
+    error_reasons: z.array(z.string()).readonly().optional(),
 });
 export const RequestResponseActionSpec = ActionSpec.extend({
     kind: z.literal('request_response').default('request_response'),
@@ -54,8 +67,8 @@ export const RemoteNotificationActionSpec = ActionSpec.extend({
     async: z.literal(true).default(true),
 });
 /**
- * Local calls can wrap synchronous or asynchronous actions,
- * and are the escape hatch for remote APIs that do not support SAES.
+ * Local calls can wrap synchronous or asynchronous actions, and are the
+ * escape hatch for remote APIs that do not support SAES.
  */
 export const LocalCallActionSpec = ActionSpec.extend({
     kind: z.literal('local_call').default('local_call'),
@@ -66,6 +79,7 @@ export const ActionSpecUnion = z.union([
     RemoteNotificationActionSpec,
     LocalCallActionSpec,
 ]);
+/** Structural type guard for any `ActionSpecUnion` variant — checks `kind` is one of the three known values. */
 export const is_action_spec = (value) => value !== null &&
     typeof value === 'object' &&
     'method' in value &&

package/dist/actions/register_action_ws.d.ts

@@ -163,6 +163,9 @@ export interface RegisterActionWsResult {
  *
  * @returns the transport (supplied or freshly created) — retain it to wire
  *   `create_ws_auth_guard` or broadcast on audit events.
+ * @mutates options.app - registers a `GET path` route via `upgradeWebSocket`
+ * @mutates options.transport - on every message, adds/removes connections
+ *   in the transport's internal maps via `add_connection` / `remove_connection`
  */
 export declare const register_action_ws: <TCtx extends BaseHandlerContext>(options: RegisterActionWsOptions<TCtx>) => RegisterActionWsResult;
 //# sourceMappingURL=register_action_ws.d.ts.map

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

package/dist/actions/register_action_ws.js

@@ -61,6 +61,9 @@ export const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60_000;
  *
  * @returns the transport (supplied or freshly created) — retain it to wire
  *   `create_ws_auth_guard` or broadcast on audit events.
+ * @mutates options.app - registers a `GET path` route via `upgradeWebSocket`
+ * @mutates options.transport - on every message, adds/removes connections
+ *   in the transport's internal maps via `add_connection` / `remove_connection`
  */
 export const register_action_ws = (options) => {
     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;

package/dist/actions/register_ws_endpoint.d.ts

@@ -41,6 +41,9 @@ export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> exte
  * Returns the `BackendWebsocketTransport` (supplied or freshly
  * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
+ *
+ * @mutates options.app - applies origin/auth/role middleware via `app.use`,
+ *   then registers the `GET path` route via the inner `register_action_ws`
  */
 export declare const register_ws_endpoint: <TCtx extends BaseHandlerContext>(options: RegisterWsEndpointOptions<TCtx>) => RegisterActionWsResult;
 //# sourceMappingURL=register_ws_endpoint.d.ts.map

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

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

package/dist/actions/register_ws_endpoint.js

@@ -26,6 +26,9 @@ import { register_action_ws, } from './register_action_ws.js';
  * Returns the `BackendWebsocketTransport` (supplied or freshly
  * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
+ *
+ * @mutates options.app - applies origin/auth/role middleware via `app.use`,
+ *   then registers the `GET path` route via the inner `register_action_ws`
  */
 export const register_ws_endpoint = (options) => {
     const { app, path, allowed_origins, required_role, log = new Logger('[ws]'), ...rest } = options;

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

@@ -35,18 +35,26 @@ export declare class RequestTracker {
      * Track a new request with the given id.
      * @param id - the request id
      * @returns a deferred promise that will be resolved when the response is received
+     * @mutates this - inserts a `RequestTrackerItem` into `pending_requests`
+     *   and arms a timeout that auto-rejects after `request_timeout_ms`;
+     *   clears any prior timeout for the same id
      */
     track_request(id: JsonrpcRequestId): Deferred<JsonrpcResponseOrError>;
     /**
      * Resolve a pending request with the given response data.
      * @param id - the request id
      * @param response - the response data
+     * @mutates this - clears the timeout, marks status `'success'`,
+     *   resolves the deferred, and removes the entry from `pending_requests`
      */
     resolve_request(id: JsonrpcRequestId, response: JsonrpcResponseOrError): void;
     /**
      * Rejects a pending request with the given error.
      * @param id - the request id
      * @param error_message - the complete `JsonrpcErrorResponse` object
+     * @mutates this - clears the timeout, marks status `'failure'`,
+     *   rejects the deferred with a `ThrownJsonrpcError`, and removes the
+     *   entry from `pending_requests`
      */
     reject_request(id: JsonrpcRequestId, error_message: JsonrpcErrorResponse): void;
     /**
@@ -55,13 +63,18 @@ export declare class RequestTracker {
      */
     handle_message(message: any): void;
     /**
-     * Cancel a pending request.
+     * Cancel a pending request without rejecting its deferred — just
+     * cleanup. The caller's promise stays unsettled; pair with an external
+     * resolution if needed.
      * @param id - the request id
+     * @mutates this - clears the timeout and removes the entry from `pending_requests`
      */
     cancel_request(id: JsonrpcRequestId): void;
     /**
      * Cancel all pending requests.
      * @param reason - optional reason to include in rejection
+     * @mutates this - clears every timeout, marks each status `'failure'`,
+     *   rejects each deferred with `internal_error`, and empties `pending_requests`
      */
     cancel_all_requests(reason?: string): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"request_tracker.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/request_tracker.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAkB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAC,MAAM,2BAA2B,CAAC;AAC3F,OAAO,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,MAAM,oBAAoB,CAAC;AAG5B,2DAA2D;AAC3D,KAAK,QAAQ,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAAC;AAMxD;;GAEG;AACH,qBAAa,kBAAkB;IAC9B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,MAAM,EAAE,WAAW,CAAiB;IACpC,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS,CAAgB;gBAGlD,EAAE,EAAE,gBAAgB,EACpB,QAAQ,EAAE,QAAQ,CAAC,sBAAsB,CAAC,EAC1C,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS;CAQpC;AAED;;;GAGG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAmB;IAC7F,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;gBAExB,kBAAkB,SAAU;IAIxC;;;;OAIG;IACH,aAAa,CAAC,EAAE,EAAE,gBAAgB,GAAG,QAAQ,CAAC,sBAAsB,CAAC;IA6BrE;;;;OAIG;IACH,eAAe,CAAC,EAAE,EAAE,gBAAgB,EAAE,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAkB7E;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,GAAG,IAAI;IAuB/E;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAiBlC;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAe1C;;;OAGG;IACH,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;CAiB1C"}
+{"version":3,"file":"request_tracker.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/request_tracker.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAkB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAC,MAAM,2BAA2B,CAAC;AAC3F,OAAO,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,MAAM,oBAAoB,CAAC;AAG5B,2DAA2D;AAC3D,KAAK,QAAQ,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAAC;AAMxD;;GAEG;AACH,qBAAa,kBAAkB;IAC9B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,MAAM,EAAE,WAAW,CAAiB;IACpC,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS,CAAgB;gBAGlD,EAAE,EAAE,gBAAgB,EACpB,QAAQ,EAAE,QAAQ,CAAC,sBAAsB,CAAC,EAC1C,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS;CAQpC;AAED;;;GAGG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAmB;IAC7F,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;gBAExB,kBAAkB,SAAU;IAIxC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,EAAE,gBAAgB,GAAG,QAAQ,CAAC,sBAAsB,CAAC;IA6BrE;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,EAAE,gBAAgB,EAAE,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAkB7E;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,GAAG,IAAI;IAuB/E;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAiBlC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAe1C;;;;;OAKG;IACH,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;CAiB1C"}

package/dist/actions/request_tracker.svelte.js

@@ -43,6 +43,9 @@ export class RequestTracker {
      * Track a new request with the given id.
      * @param id - the request id
      * @returns a deferred promise that will be resolved when the response is received
+     * @mutates this - inserts a `RequestTrackerItem` into `pending_requests`
+     *   and arms a timeout that auto-rejects after `request_timeout_ms`;
+     *   clears any prior timeout for the same id
      */
     track_request(id) {
         const deferred = create_deferred();
@@ -69,6 +72,8 @@ export class RequestTracker {
      * Resolve a pending request with the given response data.
      * @param id - the request id
      * @param response - the response data
+     * @mutates this - clears the timeout, marks status `'success'`,
+     *   resolves the deferred, and removes the entry from `pending_requests`
      */
     resolve_request(id, response) {
         const request = this.pending_requests.get(id);
@@ -89,6 +94,9 @@ export class RequestTracker {
      * Rejects a pending request with the given error.
      * @param id - the request id
      * @param error_message - the complete `JsonrpcErrorResponse` object
+     * @mutates this - clears the timeout, marks status `'failure'`,
+     *   rejects the deferred with a `ThrownJsonrpcError`, and removes the
+     *   entry from `pending_requests`
      */
     reject_request(id, error_message) {
         const request = this.pending_requests.get(id);
@@ -127,8 +135,11 @@ export class RequestTracker {
         // ignore other messages
     }
     /**
-     * Cancel a pending request.
+     * Cancel a pending request without rejecting its deferred — just
+     * cleanup. The caller's promise stays unsettled; pair with an external
+     * resolution if needed.
      * @param id - the request id
+     * @mutates this - clears the timeout and removes the entry from `pending_requests`
      */
     cancel_request(id) {
         const request = this.pending_requests.get(id);
@@ -145,6 +156,8 @@ export class RequestTracker {
     /**
      * Cancel all pending requests.
      * @param reason - optional reason to include in rejection
+     * @mutates this - clears every timeout, marks each status `'failure'`,
+     *   rejects each deferred with `internal_error`, and empties `pending_requests`
      */
     cancel_all_requests(reason) {
         for (const [id, request] of this.pending_requests.entries()) {

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

@@ -8,13 +8,13 @@
  * server revokes auth), exposes reactive status for UI indicators, and ships
  * three correctness primitives default-on:
  *
- * - {@link FrontendWebsocketClient.request} — promise-based JSON-RPC with
+ * - `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 `DEFAULT_QUEUE_MAX_SIZE` requests and flush on reopen. Overflow
- *   rejects with `queue_overflow`. Raw {@link FrontendWebsocketClient.send}
+ *   rejects with `queue_overflow`. Raw `FrontendWebsocketClient.send`
  *   is drop-on-disconnect (fire-and-forget notifications want that).
  * - **Activity-aware heartbeat** — idles fire a shared `heartbeat` request;
  *   receive-silence past `DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT` closes
@@ -98,9 +98,9 @@ export interface FrontendWebsocketClientOptions {
      */
     heartbeat?: boolean | FrontendWebsocketHeartbeatOptions | null;
     /**
-     * Durable queue for {@link FrontendWebsocketClient.request}. `true` or omit
+     * Durable queue for `FrontendWebsocketClient.request`. `true` or omit
      * for defaults; `false` disables buffering (requests while disconnected
-     * reject immediately). Raw {@link FrontendWebsocketClient.send} is never
+     * reject immediately). Raw `FrontendWebsocketClient.send` is never
      * queued — use `request()` for RPC semantics.
      */
     queue?: boolean | FrontendWebsocketQueueOptions;
@@ -162,6 +162,10 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      * timer and transitions status to `closed` (since the lie of
      * `'reconnecting'` would be visible to UI indicators). Turning it back on
      * does not synthesize a reconnect — wait for the next close.
+     *
+     * @mutates this - replaces the reconnect policy fields; may also reset
+     *   `status`, `reconnect_count`, and `current_reconnect_delay` when an
+     *   in-flight reconnect timer is cancelled or rescheduled
      */
     set_reconnect(reconnect?: boolean | FrontendWebsocketReconnectOptions | null): void;
     /**
@@ -175,6 +179,9 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      * When connected, the live timer is restarted immediately so the new
      * `interval` / `receive_timeout` take effect without a reconnect; when
      * disconnected, just stashes the policy for the next open.
+     *
+     * @mutates this - replaces the heartbeat policy fields; restarts the
+     *   live heartbeat timer when connected
      */
     set_heartbeat(heartbeat?: boolean | FrontendWebsocketHeartbeatOptions | null): void;
     /**
@@ -189,6 +196,9 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      * clears heartbeat) or the policy change of `set_reconnect(false)`
      * (which disables future reconnects). The queue stays intact so that
      * calling `connect` later flushes buffered work.
+     *
+     * @mutates this - clears the pending reconnect timer, sets `status` to
+     *   `closed`, resets `reconnect_count` and `current_reconnect_delay`
      */
     cancel_reconnect(): void;
     get url(): string;
@@ -202,12 +212,21 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      * 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.
+     *
+     * @mutates this - replaces `ws`, sets `status` to `connecting` (or
+     *   `closed` on construction failure), and on construction failure may
+     *   schedule a reconnect (mutating `reconnect_count` /
+     *   `current_reconnect_delay`)
      */
     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.
+     *
+     * @mutates this - clears `ws`, heartbeat, and reconnect timers; sets
+     *   `status` to `closed`; rejects every pending and queued request with
+     *   `service_unavailable`
      */
     disconnect(code?: number): void;
     /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
@@ -238,17 +257,18 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      * for queued-but-never-sent (server doesn't know about it) and
      * response-beat-cancel races.
      *
-     * Rejections throw `ThrownJsonrpcError` with a specific code so
-     * `FrontendWebsocketTransport` can preserve the code verbatim in its
-     * error envelope rather than collapsing every rejection to
-     * `internal_error`:
-     * - `unauthenticated` — session revoked (entry check or close code);
-     * - `request_cancelled` — caller's `AbortSignal` fired;
-     * - `queue_overflow` — durable queue full;
-     * - `service_unavailable` — socket not connected / closed / torn down
-     *   mid-flight;
-     * - `internal_error` — `ws.send` threw (serialization, buffer full);
-     * - server's wire code verbatim — JSON-RPC error frame from peer.
+     * @mutates this - inserts the new pending entry into `#pending` (or
+     *   buffers into `#queue` when disconnected) and may bump
+     *   `#next_request_id`, `#last_send_time`, `last_send_error`
+     * @throws ThrownJsonrpcError on the returned promise — never thrown
+     *   synchronously. Rejection codes:
+     *   - `unauthenticated` — session revoked (entry check or close code)
+     *   - `request_cancelled` — caller's `AbortSignal` fired
+     *   - `queue_overflow` — durable queue full
+     *   - `service_unavailable` — socket not connected / closed / torn down
+     *     mid-flight
+     *   - `internal_error` — `ws.send` threw (serialization, buffer full)
+     *   - server's wire code verbatim — JSON-RPC error frame from peer
      */
     request<R = unknown>(method: string, params?: unknown, options?: {
         signal?: AbortSignal;

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

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

package/dist/actions/socket.svelte.js

@@ -8,13 +8,13 @@
  * server revokes auth), exposes reactive status for UI indicators, and ships
  * three correctness primitives default-on:
  *
- * - {@link FrontendWebsocketClient.request} — promise-based JSON-RPC with
+ * - `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 `DEFAULT_QUEUE_MAX_SIZE` requests and flush on reopen. Overflow
- *   rejects with `queue_overflow`. Raw {@link FrontendWebsocketClient.send}
+ *   rejects with `queue_overflow`. Raw `FrontendWebsocketClient.send`
  *   is drop-on-disconnect (fire-and-forget notifications want that).
  * - **Activity-aware heartbeat** — idles fire a shared `heartbeat` request;
  *   receive-silence past `DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT` closes
@@ -140,6 +140,10 @@ export class FrontendWebsocketClient {
      * timer and transitions status to `closed` (since the lie of
      * `'reconnecting'` would be visible to UI indicators). Turning it back on
      * does not synthesize a reconnect — wait for the next close.
+     *
+     * @mutates this - replaces the reconnect policy fields; may also reset
+     *   `status`, `reconnect_count`, and `current_reconnect_delay` when an
+     *   in-flight reconnect timer is cancelled or rescheduled
      */
     set_reconnect(reconnect = null) {
         const next_auto = reconnect !== false;
@@ -187,6 +191,9 @@ export class FrontendWebsocketClient {
      * When connected, the live timer is restarted immediately so the new
      * `interval` / `receive_timeout` take effect without a reconnect; when
      * disconnected, just stashes the policy for the next open.
+     *
+     * @mutates this - replaces the heartbeat policy fields; restarts the
+     *   live heartbeat timer when connected
      */
     set_heartbeat(heartbeat = null) {
         this.#heartbeat_enabled = heartbeat !== false;
@@ -212,6 +219,9 @@ export class FrontendWebsocketClient {
      * clears heartbeat) or the policy change of `set_reconnect(false)`
      * (which disables future reconnects). The queue stays intact so that
      * calling `connect` later flushes buffered work.
+     *
+     * @mutates this - clears the pending reconnect timer, sets `status` to
+     *   `closed`, resets `reconnect_count` and `current_reconnect_delay`
      */
     cancel_reconnect() {
         if (this.#reconnect_timeout === null)
@@ -235,6 +245,11 @@ export class FrontendWebsocketClient {
      * 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.
+     *
+     * @mutates this - replaces `ws`, sets `status` to `connecting` (or
+     *   `closed` on construction failure), and on construction failure may
+     *   schedule a reconnect (mutating `reconnect_count` /
+     *   `current_reconnect_delay`)
      */
     connect() {
         if (!BROWSER)
@@ -267,6 +282,10 @@ export class FrontendWebsocketClient {
      * 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.
+     *
+     * @mutates this - clears `ws`, heartbeat, and reconnect timers; sets
+     *   `status` to `closed`; rejects every pending and queued request with
+     *   `service_unavailable`
      */
     disconnect(code = DEFAULT_CLOSE_CODE) {
         this.#cancel_reconnect();
@@ -320,17 +339,18 @@ export class FrontendWebsocketClient {
      * for queued-but-never-sent (server doesn't know about it) and
      * response-beat-cancel races.
      *
-     * Rejections throw `ThrownJsonrpcError` with a specific code so
-     * `FrontendWebsocketTransport` can preserve the code verbatim in its
-     * error envelope rather than collapsing every rejection to
-     * `internal_error`:
-     * - `unauthenticated` — session revoked (entry check or close code);
-     * - `request_cancelled` — caller's `AbortSignal` fired;
-     * - `queue_overflow` — durable queue full;
-     * - `service_unavailable` — socket not connected / closed / torn down
-     *   mid-flight;
-     * - `internal_error` — `ws.send` threw (serialization, buffer full);
-     * - server's wire code verbatim — JSON-RPC error frame from peer.
+     * @mutates this - inserts the new pending entry into `#pending` (or
+     *   buffers into `#queue` when disconnected) and may bump
+     *   `#next_request_id`, `#last_send_time`, `last_send_error`
+     * @throws ThrownJsonrpcError on the returned promise — never thrown
+     *   synchronously. Rejection codes:
+     *   - `unauthenticated` — session revoked (entry check or close code)
+     *   - `request_cancelled` — caller's `AbortSignal` fired
+     *   - `queue_overflow` — durable queue full
+     *   - `service_unavailable` — socket not connected / closed / torn down
+     *     mid-flight
+     *   - `internal_error` — `ws.send` threw (serialization, buffer full)
+     *   - server's wire code verbatim — JSON-RPC error frame from peer
      */
     request(method, params = {}, options = {}) {
         return new Promise((resolve, reject) => {

package/dist/actions/transports.d.ts

@@ -60,15 +60,24 @@ export declare class Transports {
      */
     allow_fallback: boolean;
     /**
-     * Registers a transport.
+     * Registers a transport. The first transport registered also becomes the current.
+     *
+     * @mutates this - inserts into `#transport_by_name`; sets `#current_transport`
+     *   if no current is set
      */
     register_transport(transport: Transport): void;
+    /**
+     * Switch the current transport selection by name.
+     *
+     * @mutates this - sets `#current_transport`
+     * @throws Error if no transport with `transport_name` has been registered
+     */
     set_current_transport(transport_name: TransportName): void;
     /**
      * Gets either the current transport or the first ready transport
-     * depending on `allow_fallback`, or throws an error.
+     * depending on `allow_fallback`.
      * @param transport_name - optional transport to use instead of the current
-     * @throws when no transport available or ready
+     * @returns the resolved transport, or `null` when none is ready
      */
     get_transport(transport_name?: TransportName): Transport | null;
     is_ready(): boolean | null;

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;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;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/F,IAAI,CACH,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACxC,IAAI,CACH,OAAO,EAAE,gCAAgC,EACzC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IACpD,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;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/F,IAAI,CACH,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACxC,IAAI,CACH,OAAO,EAAE,gCAAgC,EACzC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IACpD,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;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAS9C;;;;;OAKG;IACH,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"}