@fuzdev/fuz_app 0.44.0 → 0.46.0

package/dist/actions/CLAUDE.md

@@ -581,11 +581,15 @@ per-method transport selector. Useful when methods are registered on
 different backend dispatchers (e.g. streaming action on WS, rest on HTTP).
 Returning `undefined` falls through to the peer's default selection.
 
-`RpcClientActionHistory` — duck-typed integration point for consumers
-(e.g. zzz's Actions cell) that want to record every dispatched event.
-`add_from_json({method, action_event_data})` returns an object with
-`listen_to_action_event(event)` — the Proxy wires each new event into the
-history if supplied.
+`on_action_event: (event: ActionEvent<keyof TApi & string>) => void` —
+optional callback fired once per dispatched action with the live
+`ActionEvent`. Consumers wire reactive state inside the callback — e.g.
+zzz's `Actions` cell calls its own `add_from_json` +
+`listen_to_action_event` here so the history plumbing stays inside zzz
+instead of leaking onto the rpc_client surface. `event.spec.method` and
+`event.data.method` narrow to `keyof TApi & string` so consumers passing
+a generated `ActionsApi` get the literal method-name union without an
+`as ActionMethod` cast at the call site.
 
 Cast the return to a generated `ActionsApi` interface for full typing:
 codegen via `generate_actions_api_method_signature` keeps the shape
@@ -605,26 +609,39 @@ attacker-shaped `result.error` payloads cannot overwrite them.
 | `create_throwing_rpc_call` | `(method, input?) => Promise<T>` | adapter wiring (e.g. `ui/admin_rpc_adapters.ts`) — method comes from a map |
 | `create_throwing_api`      | typed Proxy over `ActionsApi`    | direct call sites — `await api.foo(input)` keeps full inference            |
 
-**Recommended consumer convention.** The throwing form is the common
-case at call sites; the Result form is the composable escape hatch for
-sites that want to inspect `error.data.reason` without try/catch. Bind
-them as `api` (throwing wrapper) and `api_raw` (the unwrapped
-underlying, returning Results):
+**Layered design.** Result is the protocol primitive — `create_rpc_client`
+returns `Result<{value}, {error}>` per call with no Error allocation. The
+throwing wrappers sit _above_ it as ergonomic adapters; both shapes share
+the same underlying transport and call sites pick per-site. `Result` is
+preferable when the call site inspects `error.data.reason` (no Error
+allocation, no try/catch nesting) or when overhead matters (reconnect
+storms, hot paths). Throwing is preferable when the call site doesn't
+inspect — `await api.foo()` reads cleaner than the `if (!r.ok) throw …`
+ritual.
+
+`create_frontend_rpc_client` ships both shapes by default — see
+[Frontend factory](#frontend-factory-frontend_rpc_clientts) below. Direct
+consumers of `create_rpc_client` pass their typed `ActionsApi` as the
+generic to get the typed Result-shaped Proxy without casts, then build
+the throwing form on top:
 
 ```ts
-const api_raw = create_rpc_client({peer, environment}) as unknown as MyActionsApi;
-const api = create_throwing_api(api_raw);
+const api_result = create_rpc_client<MyActionsApi>({peer, environment});
+const api = create_throwing_api(api_result);
 // hot path:    await api.foo(input)
-// rare branch: const r = await api_raw.foo(input); if (!r.ok) { … }
+// rare branch: const r = await api_result.foo(input); if (!r.ok) { … }
 ```
 
-Composable — feed the same typed Proxy into both: the loose method-keyed
-form for adapter dispatch, the typed Proxy form for hand-written call
-sites. `ThrowingApi<TApi>` mapped type strips
-`Promise<Result<{value: T}, {error: JsonrpcErrorObject}>>` to `Promise<T>`
-on every method that matches the `request_response` / async `local_call`
-return shape; `remote_notification` (`=> void`) and sync `local_call`
-methods pass through. The Proxy implementation inspects each call's
+`create_throwing_rpc_call` is **not** a peer choice for direct call sites —
+it's a niche primitive for method-name-mapping adapter factories
+(`ui/admin_rpc_adapters.ts`) where the method string comes from a domain
+mapping rather than a typed call site. Use it only at adapter boundaries.
+
+`ThrowingApi<TApi>` (the mapped type returned by `create_throwing_api`)
+strips `Promise<Result<{value: T}, {error: JsonrpcErrorObject}>>` to
+`Promise<T>` on every method that matches the `request_response` /
+async `local_call` return shape; `remote_notification` (`=> void`) and
+sync `local_call` methods pass through. The Proxy inspects each call's
 result shape at runtime and only unwraps when it sees a Result, so
 non-Result returns flow through unchanged.
 
@@ -637,33 +654,42 @@ probed as a thenable by `await`.
 
 ### Frontend factory (`frontend_rpc_client.ts`)
 
-`create_frontend_rpc_client<TApi>({specs, path?, transports?})` bundles
-the `ActionRegistry + ActionEventEnvironment + Transports + ActionPeer +
-create_rpc_client` boilerplate every consumer repeats — plus the
-`lookup_action_handler: () => undefined` stub (frontend never registers
-`request_response` handlers; every method dispatches over the wire).
-The `as unknown as TApi` cast happens inside the helper, so call sites
-get a typed return without the cast hostility. Returns
-`{api, peer, environment}` so advanced consumers (zzz-style frontends
-needing extra transports / WS notification handlers / action-history
-wiring) can extend without recreating the bundle.
+`create_frontend_rpc_client<TApi>({specs, path?, transports?, transport_for_method?, on_action_event?})`
+bundles the `ActionRegistry + ActionEventEnvironment + Transports +
+ActionPeer + create_rpc_client + create_throwing_api` boilerplate every
+consumer repeats — plus the `lookup_action_handler: () => undefined`
+stub (frontend never registers `request_response` handlers; every
+method dispatches over the wire). The `as unknown as TApi` cast happens
+inside the helper, so call sites get a typed return without the cast
+hostility.
 
-Default transport is `FrontendHttpTransport(path ?? '/api/rpc')`. Pass
-`transports` for WS-first or mixed setups — when supplied, the default
-HTTP transport is **not** registered. `local_call` specs in `specs`
-silently no-op because `lookup_action_handler` always returns
-`undefined`; this factory targets wire-dispatched actions.
+Returns both Proxy shapes from one factory call:
 
-Pair with `create_throwing_api` to land the recommended `api` /
-`api_raw` convention in two lines:
+- `api: ThrowingApi<TApi>` — typed throwing Proxy. Default for hot-path call sites.
+- `api_result: TApi` — typed Result-shaped Proxy. For sites that inspect `error.data.reason` without try/catch.
+- `peer`, `environment` — exposed for advanced consumers that want to register more transports or share the environment with a separate dispatcher.
 
 ```ts
-const {api: api_raw} = create_frontend_rpc_client<MyActionsApi>({
+const {api, api_result} = create_frontend_rpc_client<MyActionsApi>({
 	specs: all_standard_action_specs,
 });
-const api = create_throwing_api(api_raw);
+// hot path:    await api.account_verify()
+// rare branch: const r = await api_result.account_verify(); if (!r.ok) { … }
 ```
 
+Default transport is `FrontendHttpTransport(path ?? '/api/rpc')`. Pass
+`transports` for WS-first or mixed setups — when supplied, the default
+HTTP transport is **not** registered. `local_call` specs in `specs`
+silently no-op because `lookup_action_handler` always returns
+`undefined`; this factory targets wire-dispatched actions.
+
+`transport_for_method` and `on_action_event` are pure pass-throughs to
+`create_rpc_client` — exposed so consumers needing per-method routing
+(tx-style WS-for-actions / HTTP-for-rest split) or per-dispatch event
+wiring (zzz-style reactive Cells observing `ActionEvent` lifecycle)
+don't have to drop down to manual `create_rpc_client` construction
+(which forfeits the bundled `api` / `api_result` pair).
+
 `all_standard_action_specs` (in `../auth/standard_action_specs.ts`) is
 the matching aggregate spec list mirroring `create_standard_rpc_actions`
 on the backend — see `../auth/CLAUDE.md` §`standard_rpc_actions.ts`.

package/dist/actions/action_event.d.ts

@@ -17,7 +17,16 @@ export type ActionEventChangeObserver<TMethod extends string = string> = (new_da
 export declare class ActionEvent<TMethod extends string = string, TPhase extends ActionEventPhase = ActionEventPhase, TStep extends ActionEventStep = ActionEventStep> {
     #private;
     readonly environment: ActionEventEnvironment;
-    readonly spec: ActionSpecUnion;
+    /**
+     * `method` narrows to `TMethod` so consumers passing a typed `TApi` to
+     * `create_rpc_client` get `event.spec.method` typed as the union of
+     * their API's method names rather than plain `string`. The runtime
+     * value comes from `lookup_action_spec(method)` keyed off the Proxy
+     * get trap, so the narrowing matches the dispatched method.
+     */
+    readonly spec: ActionSpecUnion & {
+        method: TMethod;
+    };
     get data(): ActionEventDataUnion<TMethod> & {
         phase: TPhase;
         step: TStep;

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

@@ -1 +1 @@
-{"version":3,"file":"action_event.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAC,gBAAgB,EAAc,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAWpF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,sBAAsB,EAAE,eAAe,EAAC,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAkB,KAAK,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAclF,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,CACxE,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KACvB,IAAI,CAAC;AAEV;;GAEG;AACH,qBAAa,WAAW,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAClD,KAAK,SAAS,eAAe,GAAG,eAAe;;IAK/C,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAC,CAEvE;gBAGA,WAAW,EAAE,sBAAsB,EACnC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAOpC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC;IAMvC,OAAO,CAAC,QAAQ,EAAE,yBAAyB,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI;IAKjE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI;IAUvD;;OAEG;IACH,KAAK,IAAI,IAAI;IA8Cb;;OAEG;IAGG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CnC;;OAEG;IACH,WAAW,IAAI,IAAI;IAkCnB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAezC,WAAW,IAAI,OAAO;IAItB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAQ1C,YAAY,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAUpD,gBAAgB,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;CAyKzD;AAGD;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAClE,aAAa,sBAAsB,EACnC,MAAM,eAAe,EACrB,OAAO,OAAO,EACd,gBAAgB,gBAAgB,KAC9B,WAAW,CAAC,OAAO,CAiBrB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAC5E,MAAM,oBAAoB,CAAC,OAAO,CAAC,EACnC,aAAa,sBAAsB,KACjC,WAAW,CAAC,OAAO,CAOrB,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAC9B,UAAU,OAAO,EACjB,aAAa,sBAAsB,KACjC,WAGF,CAAC"}
+{"version":3,"file":"action_event.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAC,gBAAgB,EAAc,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAWpF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,sBAAsB,EAAE,eAAe,EAAC,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAkB,KAAK,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAclF,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,CACxE,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KACvB,IAAI,CAAC;AAEV;;GAEG;AACH,qBAAa,WAAW,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAClD,KAAK,SAAS,eAAe,GAAG,eAAe;;IAK/C,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,CAAC;IAEnD,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAC,CAEvE;gBAGA,WAAW,EAAE,sBAAsB,EACnC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAOpC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC;IAMvC,OAAO,CAAC,QAAQ,EAAE,yBAAyB,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI;IAKjE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI;IAUvD;;OAEG;IACH,KAAK,IAAI,IAAI;IA8Cb;;OAEG;IAGG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CnC;;OAEG;IACH,WAAW,IAAI,IAAI;IAkCnB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAezC,WAAW,IAAI,OAAO;IAItB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAQ1C,YAAY,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAUpD,gBAAgB,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;CAyKzD;AAGD;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAClE,aAAa,sBAAsB,EACnC,MAAM,eAAe,EACrB,OAAO,OAAO,EACd,gBAAgB,gBAAgB,KAC9B,WAAW,CAAC,OAAO,CAiBrB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAC5E,MAAM,oBAAoB,CAAC,OAAO,CAAC,EACnC,aAAa,sBAAsB,KACjC,WAAW,CAAC,OAAO,CAOrB,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAC9B,UAAU,OAAO,EACjB,aAAa,sBAAsB,KACjC,WAGF,CAAC"}

package/dist/actions/action_event.js

@@ -19,6 +19,13 @@ export class ActionEvent {
     #data;
     #listeners = new Set();
     environment;
+    /**
+     * `method` narrows to `TMethod` so consumers passing a typed `TApi` to
+     * `create_rpc_client` get `event.spec.method` typed as the union of
+     * their API's method names rather than plain `string`. The runtime
+     * value comes from `lookup_action_spec(method)` keyed off the Proxy
+     * get trap, so the narrowing matches the dispatched method.
+     */
     spec;
     get data() {
         return this.#data;

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

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

package/dist/actions/action_event_helpers.js

@@ -85,12 +85,22 @@ export const create_initial_data = (kind, phase, method, executor, input) => ({
 });
 export const extract_action_result = (event) => {
     const { data } = event;
+    // `data.error` populated → error path. This covers two cases:
+    // 1. `step === 'failed'` — explicit terminal failure.
+    // 2. `phase === 'receive_error' | 'send_error'` reached `step === 'handled'`
+    //    because no handler was registered for the error phase. The dispatcher
+    //    silently transitions to `handled` in that case but leaves `data.error`
+    //    populated. Reading `step === 'handled'` first would return
+    //    `{ok: true, value: null}` and surprise every caller that doesn't
+    //    register an error-phase handler. Preferring `data.error` lets
+    //    consumers skip the boilerplate `receive_error` rethrow stub.
+    if (data.error) {
+        return { ok: false, error: data.error };
+    }
     if (data.step === 'handled') {
         return { ok: true, value: data.output };
     }
-    if (data.step === 'failed') {
-        return { ok: false, error: data.error };
-    }
-    // Programming error - event not in terminal state
+    // `step === 'failed'` with `data.error === null` is a malformed event;
+    // type narrowing accepts it, runtime never produces it.
     throw new Error(`cannot extract result: event in non-terminal state (step: ${data.step})`);
 };

package/dist/actions/broadcast_api.d.ts

@@ -94,5 +94,5 @@ export type BroadcastApi = Record<string, (input: never) => Promise<void>>;
  * array in sync. Codegen (`action_collections.gen.ts`) is a natural fit
  * if the consumer already generates per-method type maps.
  */
-export declare const create_broadcast_api: <TApi = BroadcastApi>(options: CreateBroadcastApiOptions) => TApi;
+export declare const create_broadcast_api: <TApi extends object>(options: CreateBroadcastApiOptions) => TApi;
 //# sourceMappingURL=broadcast_api.d.ts.map

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

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

package/dist/actions/frontend_rpc_client.d.ts

@@ -2,39 +2,57 @@
  * Frontend-only typed RPC client factory.
  *
  * Bundles the `ActionRegistry + ActionEventEnvironment + Transports +
- * ActionPeer + create_rpc_client` boilerplate every consumer repeats — plus
- * the `lookup_action_handler: () => undefined` stub (frontend never registers
- * `request_response` handlers; every method dispatches over the wire).
+ * ActionPeer + create_rpc_client + create_throwing_api` boilerplate every
+ * consumer repeats. `lookup_action_handler` defaults to `() => undefined`
+ * (HTTP-only frontends rarely need handlers); pass `options.lookup_action_handler`
+ * to wire WS-pushed `remote_notification` dispatch or a `receive_error` /
+ * `local_call` hook.
  *
- * Generic `TApi` is the consumer's typed Proxy interface. The `as unknown
- * as TApi` double cast happens inside the helper so call sites get a typed
- * return value without the cast hostility.
+ * Returns both Proxy shapes from one factory call:
+ *
+ * - `api` — typed throwing Proxy. `await api.foo(input)` returns the
+ *   unwrapped value or throws an `Error` carrying `{code, data}` from the
+ *   JSON-RPC error. Use at hot-path call sites.
+ * - `api_result` — typed Result-shaped Proxy. `await api_result.foo(input)`
+ *   returns `Result<{value}, {error: JsonrpcErrorObject}>`. Use when call
+ *   sites want to inspect `error.data.reason` without try/catch — and
+ *   anywhere allocating an `Error` per `{ok: false}` is wasteful (e.g.
+ *   reconnect-storm `service_unavailable` paths). Result is the protocol
+ *   primitive; the throwing form is a wrapper over it. Both share the
+ *   same underlying transport — pick per call site, no construction cost.
  *
- * Companion to `create_throwing_api` — typical wiring is two lines:
+ * Generic `TApi` is the consumer's typed Proxy interface. The `as unknown
+ * as TApi` double cast happens inside the helper so call sites get a
+ * typed return value without the cast hostility. `api`'s type is
+ * `ThrowingApi<TApi>` — the mapped type strips the Result wrapper.
  *
  * ```ts
- * const {api: api_raw} = create_frontend_rpc_client<MyActionsApi>({specs: all_specs});
- * const api = create_throwing_api(api_raw);
+ * const {api, api_result} = create_frontend_rpc_client<MyActionsApi>({
+ *   specs: all_specs,
+ * });
+ * // hot path:    await api.account_verify()
+ * // rare branch: const r = await api_result.account_verify(); if (!r.ok) { … }
  * ```
  *
- * Returns the underlying `peer` and `environment` alongside `api` so
- * advanced consumers (zzz-style frontends needing extra transports / WS
- * notification handlers / action-history wiring) can extend without
- * recreating the bundle.
+ * Returns the underlying `peer` and `environment` alongside the two api
+ * shapes so advanced consumers (zzz-style frontends needing extra
+ * transports / WS notification handlers / action-history wiring) can
+ * extend without recreating the bundle.
  *
- * Note: `local_call` specs in `specs` will silently no-op because
- * `lookup_action_handler` always returns `undefined` — the frontend
- * factory is for wire-dispatched actions. Frontend-side `local_call`
- * needs a different wiring shape (custom `environment.lookup_action_handler`).
+ * `local_call` specs in `specs` no-op unless `lookup_action_handler`
+ * resolves a handler for the `'execute'` phase. Frontend-side `local_call`
+ * is uncommon; the factory targets wire-dispatched actions by default.
  *
  * @module
  */
 import { ActionPeer } from './action_peer.js';
 import { type Transport } from './transports.js';
+import { type ThrowingApi, type TransportForMethod } from './rpc_client.js';
+import type { ActionEvent } from './action_event.js';
 import type { ActionEventEnvironment } from './action_event_types.js';
 import type { ActionSpecUnion } from './action_spec.js';
 /** Options for `create_frontend_rpc_client`. */
-export interface CreateFrontendRpcClientOptions {
+export interface CreateFrontendRpcClientOptions<TApi extends object = object> {
     /**
      * Action specs the typed Proxy can dispatch. Methods absent from this
      * list silently return `undefined` from the Proxy — the generic `TApi`
@@ -54,11 +72,62 @@ export interface CreateFrontendRpcClientOptions {
      * WS+HTTP mixed setups.
      */
     transports?: ReadonlyArray<Transport>;
+    /**
+     * Optional per-method transport selector — pure pass-through to
+     * `create_rpc_client`. Return the transport name to use for a given
+     * method, or `undefined` to fall back to the peer's default selection.
+     *
+     * Useful when methods are registered on different backend dispatchers
+     * (e.g. streaming actions on WS, REST RPC on HTTP) — a tx-style mixed
+     * setup. Per-call `RpcClientCallOptions.transport_name` overrides this
+     * for individual dispatches.
+     */
+    transport_for_method?: TransportForMethod;
+    /**
+     * Optional callback fired once per dispatched action — pure pass-through
+     * to `create_rpc_client`. Used by zzz-style consumers that thread the
+     * `ActionEvent` into a reactive cell (`add_from_json` + `listen_to_action_event`)
+     * for `pending` / `failed` / `value` derivations.
+     *
+     * `event.spec.method` and `event.data.method` narrow to
+     * `keyof TApi & string` — drop the `as ActionMethod` cast at the call
+     * site when `TApi` is a generated `ActionsApi` interface.
+     */
+    on_action_event?: (event: ActionEvent<keyof TApi & string>) => void;
+    /**
+     * Optional handler resolver. Wired onto `environment.lookup_action_handler`
+     * — the registry the dispatcher uses to find handlers for inbound
+     * messages and lifecycle phases. Defaults to `() => undefined`, which
+     * is fine for HTTP-only frontends that never receive a server-pushed
+     * notification or register a `receive_error` recovery hook.
+     *
+     * Common reasons to provide this:
+     * - **Server-pushed notifications over WS** — return a handler for
+     *   `(method, 'receive')` so a `remote_notification` arriving on the
+     *   socket dispatches to your subscriber bus (tx-style).
+     * - **Per-method retry / telemetry on errors** — return a handler for
+     *   `(method, 'receive_error')`. Note that as of the
+     *   `extract_action_result` fix, a missing handler already produces
+     *   `{ok: false, error}` — the stub is no longer required just to
+     *   surface server errors.
+     */
+    lookup_action_handler?: ActionEventEnvironment['lookup_action_handler'];
 }
 /** Bundle returned by `create_frontend_rpc_client`. */
 export interface FrontendRpcClient<TApi> {
-    /** Typed Proxy — call `api.method(input)` for `Promise<Result<...>>`. */
-    api: TApi;
+    /**
+     * Typed throwing Proxy. `await api.method(input)` returns the unwrapped
+     * value or throws an `Error` with `{code, data}` from the JSON-RPC
+     * error. Default for call sites that don't inspect errors.
+     */
+    api: ThrowingApi<TApi>;
+    /**
+     * Typed Result-shaped Proxy. `await api_result.method(input)` returns
+     * `Result<{value}, {error: JsonrpcErrorObject}>`. Use when call sites
+     * inspect `error.data.reason` without try/catch, or when Error
+     * allocation per `{ok: false}` would be wasteful.
+     */
+    api_result: TApi;
     /** Underlying peer — exposed for consumers that need to register more transports or send raw messages. */
     peer: ActionPeer;
     /** Action environment — exposed for consumers that need to share it (e.g. attach a notification handler registry). */
@@ -67,8 +136,11 @@ export interface FrontendRpcClient<TApi> {
 /**
  * Build a frontend-only typed RPC client.
  *
- * @param options - `specs` (required), optional `path` / `transports`
- * @returns `{api, peer, environment}` — typed Proxy plus the underlying primitives
+ * @param options - `specs` (required), optional `path` / `transports` /
+ *   `transport_for_method` / `on_action_event`
+ * @returns `{api, api_result, peer, environment}` — both Proxy shapes plus
+ *   the underlying primitives. `api` throws on `{ok: false}`; `api_result`
+ *   returns the Result.
  */
-export declare const create_frontend_rpc_client: <TApi>(options: CreateFrontendRpcClientOptions) => FrontendRpcClient<TApi>;
+export declare const create_frontend_rpc_client: <TApi extends object>(options: CreateFrontendRpcClientOptions<TApi>) => FrontendRpcClient<TApi>;
 //# sourceMappingURL=frontend_rpc_client.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"frontend_rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/frontend_rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAa,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAG3D,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD,gDAAgD;AAChD,MAAM,WAAW,8BAA8B;IAC9C;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACtC;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB,CAAC,IAAI;IACtC,yEAAyE;IACzE,GAAG,EAAE,IAAI,CAAC;IACV,0GAA0G;IAC1G,IAAI,EAAE,UAAU,CAAC;IACjB,sHAAsH;IACtH,WAAW,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GAAI,IAAI,EAC9C,SAAS,8BAA8B,KACrC,iBAAiB,CAAC,IAAI,CAgBxB,CAAC"}
+{"version":3,"file":"frontend_rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/frontend_rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAa,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EAGN,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD,gDAAgD;AAChD,MAAM,WAAW,8BAA8B,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAC3E;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtC;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;IAC1C;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC;IACpE;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,CAAC;CACxE;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB,CAAC,IAAI;IACtC;;;;OAIG;IACH,GAAG,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;OAKG;IACH,UAAU,EAAE,IAAI,CAAC;IACjB,0GAA0G;IAC1G,IAAI,EAAE,UAAU,CAAC;IACjB,sHAAsH;IACtH,WAAW,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,IAAI,SAAS,MAAM,EAC7D,SAAS,8BAA8B,CAAC,IAAI,CAAC,KAC3C,iBAAiB,CAAC,IAAI,CAsBxB,CAAC"}

package/dist/actions/frontend_rpc_client.js

@@ -2,30 +2,46 @@
  * Frontend-only typed RPC client factory.
  *
  * Bundles the `ActionRegistry + ActionEventEnvironment + Transports +
- * ActionPeer + create_rpc_client` boilerplate every consumer repeats — plus
- * the `lookup_action_handler: () => undefined` stub (frontend never registers
- * `request_response` handlers; every method dispatches over the wire).
+ * ActionPeer + create_rpc_client + create_throwing_api` boilerplate every
+ * consumer repeats. `lookup_action_handler` defaults to `() => undefined`
+ * (HTTP-only frontends rarely need handlers); pass `options.lookup_action_handler`
+ * to wire WS-pushed `remote_notification` dispatch or a `receive_error` /
+ * `local_call` hook.
  *
- * Generic `TApi` is the consumer's typed Proxy interface. The `as unknown
- * as TApi` double cast happens inside the helper so call sites get a typed
- * return value without the cast hostility.
+ * Returns both Proxy shapes from one factory call:
+ *
+ * - `api` — typed throwing Proxy. `await api.foo(input)` returns the
+ *   unwrapped value or throws an `Error` carrying `{code, data}` from the
+ *   JSON-RPC error. Use at hot-path call sites.
+ * - `api_result` — typed Result-shaped Proxy. `await api_result.foo(input)`
+ *   returns `Result<{value}, {error: JsonrpcErrorObject}>`. Use when call
+ *   sites want to inspect `error.data.reason` without try/catch — and
+ *   anywhere allocating an `Error` per `{ok: false}` is wasteful (e.g.
+ *   reconnect-storm `service_unavailable` paths). Result is the protocol
+ *   primitive; the throwing form is a wrapper over it. Both share the
+ *   same underlying transport — pick per call site, no construction cost.
  *
- * Companion to `create_throwing_api` — typical wiring is two lines:
+ * Generic `TApi` is the consumer's typed Proxy interface. The `as unknown
+ * as TApi` double cast happens inside the helper so call sites get a
+ * typed return value without the cast hostility. `api`'s type is
+ * `ThrowingApi<TApi>` — the mapped type strips the Result wrapper.
  *
  * ```ts
- * const {api: api_raw} = create_frontend_rpc_client<MyActionsApi>({specs: all_specs});
- * const api = create_throwing_api(api_raw);
+ * const {api, api_result} = create_frontend_rpc_client<MyActionsApi>({
+ *   specs: all_specs,
+ * });
+ * // hot path:    await api.account_verify()
+ * // rare branch: const r = await api_result.account_verify(); if (!r.ok) { … }
  * ```
  *
- * Returns the underlying `peer` and `environment` alongside `api` so
- * advanced consumers (zzz-style frontends needing extra transports / WS
- * notification handlers / action-history wiring) can extend without
- * recreating the bundle.
+ * Returns the underlying `peer` and `environment` alongside the two api
+ * shapes so advanced consumers (zzz-style frontends needing extra
+ * transports / WS notification handlers / action-history wiring) can
+ * extend without recreating the bundle.
  *
- * Note: `local_call` specs in `specs` will silently no-op because
- * `lookup_action_handler` always returns `undefined` — the frontend
- * factory is for wire-dispatched actions. Frontend-side `local_call`
- * needs a different wiring shape (custom `environment.lookup_action_handler`).
+ * `local_call` specs in `specs` no-op unless `lookup_action_handler`
+ * resolves a handler for the `'execute'` phase. Frontend-side `local_call`
+ * is uncommon; the factory targets wire-dispatched actions by default.
  *
  * @module
  */
@@ -33,19 +49,22 @@ import { ActionRegistry } from './action_registry.js';
 import { ActionPeer } from './action_peer.js';
 import { Transports } from './transports.js';
 import { FrontendHttpTransport } from './transports_http.js';
-import { create_rpc_client } from './rpc_client.js';
+import { create_rpc_client, create_throwing_api, } from './rpc_client.js';
 /**
  * Build a frontend-only typed RPC client.
  *
- * @param options - `specs` (required), optional `path` / `transports`
- * @returns `{api, peer, environment}` — typed Proxy plus the underlying primitives
+ * @param options - `specs` (required), optional `path` / `transports` /
+ *   `transport_for_method` / `on_action_event`
+ * @returns `{api, api_result, peer, environment}` — both Proxy shapes plus
+ *   the underlying primitives. `api` throws on `{ok: false}`; `api_result`
+ *   returns the Result.
  */
 export const create_frontend_rpc_client = (options) => {
     const registry = new ActionRegistry([...options.specs]);
     const environment = {
         executor: 'frontend',
         lookup_action_spec: (method) => registry.spec_by_method.get(method),
-        lookup_action_handler: () => undefined,
+        lookup_action_handler: options.lookup_action_handler ?? (() => undefined),
     };
     const transports = new Transports();
     if (options.transports) {
@@ -56,6 +75,12 @@ export const create_frontend_rpc_client = (options) => {
         transports.register_transport(new FrontendHttpTransport(options.path ?? '/api/rpc'));
     }
     const peer = new ActionPeer({ environment, transports });
-    const api = create_rpc_client({ peer, environment });
-    return { api, peer, environment };
+    const api_result = create_rpc_client({
+        peer,
+        environment,
+        on_action_event: options.on_action_event,
+        transport_for_method: options.transport_for_method,
+    });
+    const api = create_throwing_api(api_result);
+    return { api, api_result, peer, environment };
 };