@fuzdev/fuz_app 0.51.0 → 0.53.0

package/dist/actions/rpc_client.js

@@ -33,7 +33,6 @@ import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
  * const api_result = create_rpc_client<MyActionsApi>({peer, environment});
  * ```
  *
- * @param options - client options (peer, environment, optional callbacks)
  * @returns a Proxy typed as `TApi` that responds to any method name found in the environment's specs
  */
 export const create_rpc_client = (options) => {
@@ -56,9 +55,6 @@ export const create_rpc_client = (options) => {
         },
     });
 };
-/**
- * Creates a method that executes an action through its complete lifecycle.
- */
 const create_action_method = (peer, environment, spec, on_action_event, transport_for_method) => {
     switch (spec.kind) {
         case 'local_call':
@@ -71,10 +67,7 @@ const create_action_method = (peer, environment, spec, on_action_event, transpor
             return create_remote_notification_method(peer, environment, spec, on_action_event, transport_for_method);
     }
 };
-/**
- * Creates a synchronous local call method.
- * Returns value directly - can throw on error (sync methods cannot return Result).
- */
+/** Sync local-call dispatch — returns the value directly; throws on error (no Result wrapping). */
 const create_sync_local_call_method = (environment, spec, on_action_event) => {
     return (input) => {
         const event = create_action_event(environment, spec, input);
@@ -91,8 +84,7 @@ const create_sync_local_call_method = (environment, spec, on_action_event) => {
     };
 };
 /**
- * Creates an asynchronous local call method.
- * Returns Result for type-safe error handling.
+ * Async local-call dispatch — returns Result.
  *
  * Local calls don't traverse a transport, so `transport_name` is ignored and
  * `signal` can only short-circuit before the synchronous handler runs (no
@@ -112,9 +104,6 @@ const create_async_local_call_method = (environment, spec, on_action_event) => {
         return extract_action_result(event);
     };
 };
-/**
- * Creates a request/response method that communicates over the network.
- */
 const create_request_response_method = (peer, environment, spec, on_action_event, transport_for_method) => {
     return async (input, options) => {
         const event = create_action_event(environment, spec, input);
@@ -143,10 +132,7 @@ const create_request_response_method = (peer, environment, spec, on_action_event
         return extract_action_result(event);
     };
 };
-/**
- * Creates a remote notification method (fire and forget).
- * Returns Result<{value: void}> for consistency.
- */
+/** Fire-and-forget remote notification — returns `Result<{value: void}>` for consistency with `request_response`. */
 const create_remote_notification_method = (peer, environment, spec, on_action_event, transport_for_method) => {
     return async (input, options) => {
         const event = create_action_event(environment, spec, input);

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;
@@ -266,7 +286,6 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
  * a terminal session-revocation read as `failure` while a clean client-
  * initiated close reads as `initial` (the "not connected, not trying" state).
  *
- * @param status - the socket's current `SocketStatus`
  * @param revoked - whether the session has been permanently revoked
  *   (typically `FrontendWebsocketClient.revoked`)
  */

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) => {
@@ -704,7 +724,6 @@ export class FrontendWebsocketClient {
  * a terminal session-revocation read as `failure` while a clean client-
  * initiated close reads as `initial` (the "not connected, not trying" state).
  *
- * @param status - the socket's current `SocketStatus`
  * @param revoked - whether the session has been permanently revoked
  *   (typically `FrontendWebsocketClient.revoked`)
  */

package/dist/actions/transports.d.ts

@@ -60,15 +60,25 @@ 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.
-     * @param transport_name - optional transport to use instead of the current
-     * @throws when no transport available or ready
+     * Resolve a transport. With `allow_fallback`, walks specified → current →
+     * any-ready; without, returns the named transport (or current) only when
+     * it's 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;;;;;;OAMG;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;CA2CtE"}

package/dist/actions/transports.js

@@ -25,7 +25,10 @@ export class Transports {
      */
     allow_fallback = true; // TODO allow registering transports with a priority level so this can be customized
     /**
-     * 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) {
         this.#transport_by_name.set(transport.transport_name, transport); // TODO maybe ensure unregistering of any previous transport?
@@ -34,6 +37,12 @@ export class Transports {
             this.#current_transport = transport;
         }
     }
+    /**
+     * 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) {
         const transport = this.#transport_by_name.get(transport_name);
         if (!transport)
@@ -41,10 +50,11 @@ export class Transports {
         this.#current_transport = transport;
     }
     /**
-     * Gets either the current transport or the first ready transport
-     * depending on `allow_fallback`, or throws an error.
-     * @param transport_name - optional transport to use instead of the current
-     * @throws when no transport available or ready
+     * Resolve a transport. With `allow_fallback`, walks specified → current →
+     * any-ready; without, returns the named transport (or current) only when
+     * it's ready.
+     *
+     * @returns the resolved transport, or `null` when none is ready
      */
     get_transport(transport_name) {
         return this.allow_fallback
@@ -67,11 +77,6 @@ export class Transports {
     get_transport_by_name(transport_name) {
         return this.#transport_by_name.get(transport_name) ?? null;
     }
-    /**
-     * Gets the specified transport, defaulting to the current, or throws an error.
-     * @param transport_name - optional transport type to use instead of the current
-     * @throws when no transport available or ready
-     */
     #get_exact(transport_name) {
         const transport = transport_name
             ? this.#transport_by_name.get(transport_name)
@@ -81,11 +86,6 @@ export class Transports {
         }
         return null;
     }
-    /**
-     * Gets the appropriate transport or throws an error.
-     * @param transport_name - optional transport type or array of types to use instead of the current
-     * @throws when no transport available or ready
-     */
     #get_first_ready(transport_name) {
         // First try the specified transport(s) if provided
         if (transport_name) {

package/dist/actions/transports_http.d.ts

@@ -5,6 +5,13 @@
  */
 import type { JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 import type { Transport, TransportSendOptions } from './transports.js';
+/**
+ * Thin `fetch` adapter for the JSON-RPC endpoint. POST by default; GET when
+ * the optional `has_side_effects(method)` callback returns `false` for the
+ * method (matches `create_rpc_endpoint`'s GET convention). On non-OK HTTP
+ * responses, synthesizes a JSON-RPC error envelope via
+ * `http_status_to_jsonrpc_error_code`. Always reports ready.
+ */
 export declare class FrontendHttpTransport implements Transport {
     #private;
     readonly transport_name: "frontend_http_rpc";

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

@@ -1 +1 @@
-{"version":3,"file":"transports_http.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAErE,qBAAa,qBAAsB,YAAW,SAAS;;IACtD,QAAQ,CAAC,cAAc,EAAG,mBAAmB,CAAU;gBAOtD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO;IAOzC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAyEvC,QAAQ,IAAI,OAAO;CAGnB"}
+{"version":3,"file":"transports_http.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAErE;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,SAAS;;IACtD,QAAQ,CAAC,cAAc,EAAG,mBAAmB,CAAU;gBAOtD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO;IAOzC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAyEvC,QAAQ,IAAI,OAAO;CAGnB"}

package/dist/actions/transports_http.js

@@ -6,6 +6,13 @@
 import { DEV } from 'esm-env';
 import { ThrownJsonrpcError, jsonrpc_error_messages, http_status_to_jsonrpc_error_code, UNKNOWN_ERROR_MESSAGE, } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, to_jsonrpc_message_id, is_jsonrpc_error_response, } from '../http/jsonrpc_helpers.js';
+/**
+ * Thin `fetch` adapter for the JSON-RPC endpoint. POST by default; GET when
+ * the optional `has_side_effects(method)` callback returns `false` for the
+ * method (matches `create_rpc_endpoint`'s GET convention). On non-OK HTTP
+ * responses, synthesizes a JSON-RPC error envelope via
+ * `http_status_to_jsonrpc_error_code`. Always reports ready.
+ */
 export class FrontendHttpTransport {
     transport_name = 'frontend_http_rpc';
     #url;

package/dist/actions/transports_ws.d.ts

@@ -41,6 +41,12 @@ export interface WebsocketRpcConnection extends WebsocketConnection {
         id?: JsonrpcRequestId;
     }) => Promise<unknown>;
 }
+/**
+ * Thin adapter over `WebsocketRpcConnection` (canonical implementation:
+ * `FrontendWebsocketClient`). Routes inbound server-pushed requests and
+ * notifications into the supplied `receive` callback; responses are owned
+ * by the connection's own `request()` pending map and are ignored here.
+ */
 export declare class FrontendWebsocketTransport implements Transport {
     #private;
     readonly transport_name: "frontend_websocket_rpc";
@@ -48,6 +54,13 @@ export declare class FrontendWebsocketTransport implements Transport {
     send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;
     send(message: JsonrpcNotification, options?: TransportSendOptions): Promise<JsonrpcErrorResponse | null>;
     is_ready(): boolean;
+    /**
+     * Detach the inbound message and error handlers registered on the
+     * connection. Idempotent — subsequent calls no-op. Does not close the
+     * underlying connection (that lifecycle is owned by the caller).
+     *
+     * @mutates this - clears the two stored unsubscribe references after invoking them
+     */
     dispose(): void;
 }
 //# sourceMappingURL=transports_ws.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAIrE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC5E,iBAAiB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IAClE,OAAO,EAAE,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE;QAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,gBAAgB,CAAA;KAAC,KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,qBAAa,0BAA2B,YAAW,SAAS;;IAC3D,QAAQ,CAAC,cAAc,EAAG,wBAAwB,CAAU;gBAOhD,UAAU,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC;IAyBtF,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4DvC,QAAQ,IAAI,OAAO;IAInB,OAAO,IAAI,IAAI;CAUf"}
+{"version":3,"file":"transports_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAIrE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC5E,iBAAiB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IAClE,OAAO,EAAE,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE;QAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,gBAAgB,CAAA;KAAC,KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,YAAW,SAAS;;IAC3D,QAAQ,CAAC,cAAc,EAAG,wBAAwB,CAAU;gBAOhD,UAAU,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC;IAyBtF,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4DvC,QAAQ,IAAI,OAAO;IAInB;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAUf"}

package/dist/actions/transports_ws.js

@@ -13,6 +13,12 @@
  */
 import { ThrownJsonrpcError, jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { is_jsonrpc_notification, is_jsonrpc_request, to_jsonrpc_message_id, to_jsonrpc_result, create_jsonrpc_response, create_jsonrpc_error_response, } from '../http/jsonrpc_helpers.js';
+/**
+ * Thin adapter over `WebsocketRpcConnection` (canonical implementation:
+ * `FrontendWebsocketClient`). Routes inbound server-pushed requests and
+ * notifications into the supplied `receive` callback; responses are owned
+ * by the connection's own `request()` pending map and are ignored here.
+ */
 export class FrontendWebsocketTransport {
     transport_name = 'frontend_websocket_rpc';
     #connection;
@@ -86,6 +92,13 @@ export class FrontendWebsocketTransport {
     is_ready() {
         return this.#connection.connected;
     }
+    /**
+     * Detach the inbound message and error handlers registered on the
+     * connection. Idempotent — subsequent calls no-op. Does not close the
+     * underlying connection (that lifecycle is owned by the caller).
+     *
+     * @mutates this - clears the two stored unsubscribe references after invoking them
+     */
     dispose() {
         if (this.#remove_message_handler) {
             this.#remove_message_handler();

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -45,9 +45,10 @@ export declare const WS_DISCONNECT_EVENT_TYPES: ReadonlySet<string>;
  * the submitted session_id), so reacting to them would let any authenticated
  * user close another user's socket by guessing a session hash or token id.
  *
- * @param transport - the backend WebSocket transport to guard
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`
+ * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`.
+ *   The returned callback mutates `transport` (closing matching sockets via
+ *   `close_sockets_for_session` / `_token` / `_account`) on every relevant event.
  */
 export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
 /**
@@ -76,9 +77,10 @@ export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport
  * to them would let an unauthenticated probe close the targeted account's
  * sockets by submitting a logout for an arbitrary `account_id`.
  *
- * @param transport - the backend WebSocket transport to guard
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`
+ * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`.
+ *   The returned callback mutates `transport` via `close_sockets_for_account`
+ *   on every successful `logout` event with a non-empty `account_id`.
  */
 export declare const create_ws_logout_closer: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
 //# sourceMappingURL=transports_ws_auth_guard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBA6CF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBAaF,CAAC"}
+{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBA6CF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBAaF,CAAC"}

package/dist/actions/transports_ws_auth_guard.js

@@ -38,9 +38,10 @@ export const WS_DISCONNECT_EVENT_TYPES = new Set([
  * the submitted session_id), so reacting to them would let any authenticated
  * user close another user's socket by guessing a session hash or token id.
  *
- * @param transport - the backend WebSocket transport to guard
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`
+ * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`.
+ *   The returned callback mutates `transport` (closing matching sockets via
+ *   `close_sockets_for_session` / `_token` / `_account`) on every relevant event.
  */
 export const create_ws_auth_guard = (transport, log) => {
     return (event) => {
@@ -110,9 +111,10 @@ export const create_ws_auth_guard = (transport, log) => {
  * to them would let an unauthenticated probe close the targeted account's
  * sockets by submitting a logout for an arbitrary `account_id`.
  *
- * @param transport - the backend WebSocket transport to guard
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`
+ * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`.
+ *   The returned callback mutates `transport` via `close_sockets_for_account`
+ *   on every successful `logout` event with a non-empty `account_id`.
  */
 export const create_ws_logout_closer = (transport, log) => {
     return (event) => {

package/dist/actions/transports_ws_backend.d.ts

@@ -44,28 +44,39 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
     /**
      * Add a new WebSocket connection with auth info.
      * Session connections pass a token hash for targeted revocation.
-     * Bearer token connections (api_token) pass the `api_token.id` so the
+     * Bearer token connections (`api_token`) pass the `api_token.id` so the
      * socket can be closed when that specific token is revoked without
      * tearing down the account's other sockets. Daemon-token connections
      * pass `null` for both — they're only reachable via
      * `close_sockets_for_account`.
+     *
+     * @returns the freshly assigned `connection_id` (branded `Uuid`)
+     * @mutates this - inserts into `#connections`, `#connection_ids`, and
+     *   `#connection_identities`
      */
     add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null): Uuid;
     /**
      * Remove a WebSocket connection and its auth tracking data.
      * Idempotent — safe to call after revocation has already cleaned up.
+     *
+     * @mutates this - deletes the connection's entries from `#connections`,
+     *   `#connection_ids`, and `#connection_identities`
      */
     remove_connection(ws: WSContext): void;
     /**
      * Close all sockets associated with a specific session token hash.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_session(token_hash: string): number;
     /**
      * Close all sockets associated with a specific account.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_account(account_id: Uuid): number;
     /**
@@ -76,6 +87,8 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * tokens' sockets.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_token(api_token_id: string): number;
     send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;

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

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