@stridge/kit 0.1.0-alpha.6 → 0.1.0-alpha.60

package/dist/flows/withdraw/orchestrator/controller.js

@@ -1 +1 @@
-"use client";import{useLingui as e}from"../../../shared/i18n/useLingui.js";import"../../../i18n/index.js";import{toFailure as t}from"../../../shared/orchestrator/toFailure.js";import{useDriverSettlementListener as n}from"../../../shared/orchestrator/useDriverSettlementListener.js";import{useEffectiveState as r}from"../../../shared/orchestrator/useEffectiveState.js";import{useSettlementWatcher as i}from"../../../shared/orchestrator/useSettlementWatcher.js";import"../../../shared/orchestrator/index.js";import{useWithdrawDriverInstance as a}from"../driver/context.js";import{initialState as o,reducer as s}from"./reducer.js";import{createContext as c,use as l,useCallback as u,useMemo as d,useReducer as f,useRef as p}from"react";import{jsx as m}from"react/jsx-runtime";const h={id:`ldK3jJ`,message:`Failed to submit withdrawal.`},g={id:`kUFhUv`,message:`Withdrawal failed.`},_=c(null);_.displayName=`WithdrawControllerContext`;function v(){let e=l(_);if(!e)throw Error(`useWithdraw / WithdrawControllerProvider must be used inside <KitProvider withdraw={…} />. Mount KitProvider once at the host's app root with a withdraw driver.`);return e}function y(){return v().state}function b(){return v().effectiveState}function x(){return v().actions}function S({children:e}){let t=a(),[n,c]=f(s,o),l=w(n,c,t);i(t,n.name===`inProgress`?n.ctx.tx:void 0),T(n,c,t);let u=r(n),p=C(c,l);return m(_,{value:d(()=>({state:n,effectiveState:u,dispatch:c,controller:p,actions:l}),[n,u,p,l]),children:e})}function C(e,t){let n=u(()=>{e({type:`OPEN`})},[e]),r=u(()=>{e({type:`CLOSE`})},[e]);return d(()=>({open:n,close:r,actions:t}),[n,r,t])}function w(n,r,i){let a=p(n);a.current=n;let o=p(i);o.current=i;let s=p(r);s.current=r;let{i18n:c}=e(),l=p(c);l.current=c;let f=u(e=>{let n=o.current;s.current({type:`SUBMIT`,input:e});let r=new AbortController,i={sourceAssetSymbol:e.sourceAssetSymbol,sourceChainId:e.sourceChainId,amount:e.amount,receiveTokenSymbol:e.receiveTokenSymbol,receiveChainId:e.receiveChainId,recipientAddress:e.recipientAddress};n.submitWithdrawal(i,r.signal).then(e=>{r.signal.aborted||s.current({type:`SUBMIT_CONFIRMED`,tx:e})}).catch(n=>{r.signal.aborted||s.current({type:`SUBMIT_FAILED`,failure:t(n,l.current._(h)),input:e})})},[]),m=u(()=>{s.current({type:`CLOSE`})},[]),g=u(()=>{s.current({type:`RESET`})},[]),_=u(()=>{s.current({type:`CLEAR_NOTICE`})},[]);return d(()=>({submit:f,close:m,reset:g,clearNotice:_}),[f,m,g,_])}function T(t,r,i){let a=p(t);a.current=t;let{i18n:o}=e(),s=p(o);s.current=o,n(i,(e,t)=>{if(a.current.name===`inProgress`){if(e===`succeeded`){r({type:`SETTLEMENT_SUCCEEDED`});return}if(e===`failed`){let e=t.settlement,n=e.status===`ready`||e.status===`stale`?e.payload:null,i=n&&n.kind===`failed`?{reason:s.current._(g),code:n.failureKind}:void 0;r({type:`SETTLEMENT_FAILED`,...i?{failure:i}:{}})}}})}export{S as WithdrawControllerProvider,v as useControllerContext,x as useWithdrawActions,b as useWithdrawEffectiveState,y as useWithdrawState};
+"use client";import{useOptionalActivityDriverInstance as e}from"../../activity/driver/context.js";import{useLingui as t}from"../../../shared/i18n/useLingui.js";import"../../../i18n/index.js";import{toFailure as n}from"../../../shared/orchestrator/toFailure.js";import{useDriverSettlementListener as r}from"../../../shared/orchestrator/useDriverSettlementListener.js";import{useEffectiveState as i}from"../../../shared/orchestrator/useEffectiveState.js";import{useSettlementWatcher as a}from"../../../shared/orchestrator/useSettlementWatcher.js";import"../../../shared/orchestrator/index.js";import{useWithdrawBindingsRef as o}from"../bindings/WithdrawBindings.js";import"../bindings/index.js";import{useWithdrawDriverInstance as s}from"../driver/context.js";import{initialState as c,reducer as l}from"./reducer.js";import{createContext as u,use as d,useCallback as f,useEffect as p,useMemo as m,useReducer as h,useRef as g}from"react";import{jsx as _}from"react/jsx-runtime";const v={id:`ldK3jJ`,message:`Failed to submit withdrawal.`},y={id:`kUFhUv`,message:`Withdrawal failed.`},b={id:`srsA0x`,message:`Withdrawal declined.`},x=u(null);x.displayName=`WithdrawControllerContext`;function S(){let e=d(x);if(!e)throw Error(`useWithdraw / WithdrawControllerProvider must be used inside <KitProvider withdraw={…} />. Mount KitProvider once at the host's app root with a withdraw driver.`);return e}function C(){return d(x)}function w(){return S().state}function T(){return S().effectiveState}function E(){return S().actions}function D({children:t}){let n=s(),r=e(),[o,u]=h(l,c),d=k(o,u,n,r),f=o.name===`inProgress`?{form:o.ctx.input,submittedAt:o.ctx.submittedAt,...o.ctx.tx?{tx:o.ctx.tx}:{}}:void 0;a(n,f,f?`${f.submittedAt}|${f.tx?.hash??``}`:void 0),A(r,o.name===`activityList`||o.name===`activityDetail`),j(o,u,n);let p=i(o),g=O(u,d,n);return _(x,{value:m(()=>({state:o,effectiveState:p,dispatch:u,controller:g,actions:d}),[o,p,g,d]),children:t})}function O(e,t,n){let r=g(n);r.current=n;let i=f(t=>(r.current.arm(),e({type:`OPEN`}),!0),[e]),a=f(()=>{e({type:`CLOSE`})},[e]);return m(()=>({open:i,close:a,actions:t}),[i,a,t])}function k(e,r,i,a){let s=g(e);s.current=e;let c=g(i);c.current=i;let l=g(a);l.current=a;let u=g(r);u.current=r;let{i18n:d}=t(),p=g(d);p.current=d;let h=o(),_=f(e=>{let t=c.current;u.current({type:`SUBMIT`,input:e});let r=new AbortController,i={sourceAssetSymbol:e.sourceAssetSymbol,sourceChainId:e.sourceChainId,amount:e.amount,receiveTokenSymbol:e.receiveTokenSymbol,receiveChainId:e.receiveChainId,recipientAddress:e.recipientAddress},a={beginProcessing(e){u.current({type:`BEGIN_PROCESSING`,submittedAt:Date.now(),...e?{tx:e}:{}});try{l.current?.invalidateActivity?.()}catch{}},setTxHash(e){u.current({type:`SET_TX_HASH`,tx:e,submittedAt:Date.now()})},fail(e){u.current({type:`MARK_FAILED`,...e?{failure:e}:{}})},decline(){u.current({type:`SUBMIT_FAILED`,failure:{reason:p.current._(b),code:`UserRejectedRequestError`},input:e})},succeed(){u.current({type:`MARK_SUCCEEDED`})}};t.prepareWithdrawal(i,r.signal).then(i=>{if(r.signal.aborted)return;let o=h.current.onSubmit;if(!o){u.current({type:`SUBMIT_FAILED`,failure:n(Error(`WithdrawDialog onSubmit is missing.`),p.current._(v)),input:e});return}let s=t.getSnapshot().quote,c=s.status===`ready`||s.status===`stale`?s.payload:void 0;try{let t=o({form:e,depositTarget:i.depositTarget,correlation:i.correlation,...c?{quote:c}:{}},a,r.signal);t&&typeof t.catch==`function`&&t.catch(t=>{r.signal.aborted||u.current({type:`SUBMIT_FAILED`,failure:n(t,p.current._(v)),input:e})})}catch(t){if(r.signal.aborted)return;u.current({type:`SUBMIT_FAILED`,failure:n(t,p.current._(v)),input:e})}}).catch(t=>{r.signal.aborted||u.current({type:`SUBMIT_FAILED`,failure:n(t,p.current._(v)),input:e})})},[]),y=f(()=>{u.current({type:`CLOSE`})},[]),x=f(()=>{u.current({type:`RESET`})},[]),S=f(()=>{u.current({type:`CLEAR_NOTICE`})},[]),C=f(()=>{u.current({type:`BACK`})},[]),w=f(()=>{if(l.current==null){process.env.NODE_ENV!==`production`&&console.warn("[@stridge/kit] useWithdrawActions().openActivity() was called but no activity driver is mounted. Wrap the host with `<KitProvider activity={…}>` (or `<StridgeProvider>` with any flow enabled) to enable the activity surface.");return}s.current.name===`form`&&u.current({type:`OPEN_ACTIVITY`})},[]),T=f(e=>{u.current({type:`SELECT_SETTLEMENT`,settlementId:e})},[]);return m(()=>({submit:_,close:y,reset:x,clearNotice:S,back:C,openActivity:w,selectSettlement:T}),[_,y,x,S,C,w,T])}function A(e,t){p(()=>{if(!t||!e)return;let n=new AbortController;return e.watchActivity(n.signal),()=>n.abort()},[t,e])}function j(e,n,i){let a=g(e);a.current=e;let{i18n:o}=t(),s=g(o);s.current=o,r(i,(e,t)=>{if(a.current.name===`inProgress`){if(e===`succeeded`){n({type:`SETTLEMENT_SUCCEEDED`});return}if(e===`failed`){let e=t.settlement,r=e.status===`ready`||e.status===`stale`?e.payload:null,i=r&&r.kind===`failed`?{reason:s.current._(y),code:r.failureKind}:void 0;n({type:`SETTLEMENT_FAILED`,...i?{failure:i}:{}})}}})}export{D as WithdrawControllerProvider,S as useControllerContext,C as useOptionalControllerContext,E as useWithdrawActions,T as useWithdrawEffectiveState,w as useWithdrawState};

package/dist/flows/withdraw/orchestrator/index.d.ts

@@ -1,4 +1,4 @@
 import { FailureInfo } from "../../../shared/orchestrator/types.js";
 import { WithdrawActions, WithdrawController, WithdrawEvent, WithdrawState, WithdrawStateName, WithdrawalFormSnapshot } from "./types.js";
 import { useWithdrawState } from "./controller.js";
-import { useWithdraw } from "./useWithdraw.js";
+import { useOptionalWithdraw, usePrefetchWithdraw, useWithdraw } from "./useWithdraw.js";

package/dist/flows/withdraw/orchestrator/reducer.js

@@ -1 +1 @@
-import{isUserRejectionFailure as e}from"../../../shared/orchestrator/userRejection.js";import"../../../shared/orchestrator/index.js";const t={name:`closed`};function n(e,t){switch(e.name){case`closed`:return r(t);case`form`:return i(e,t);case`submitting`:return a(e,t);case`inProgress`:return o(e,t);case`success`:return s(e,t);case`error`:return c(e,t);default:return l(e)}}function r(e){return e.type===`OPEN`?{name:`form`}:{name:`closed`}}function i(e,t){switch(t.type){case`SUBMIT`:return{name:`submitting`,ctx:{input:t.input}};case`CLEAR_NOTICE`:return e.ctx?.notice?{name:`form`}:e;case`CLOSE`:return{name:`closed`};default:return e}}function a(t,n){switch(n.type){case`SUBMIT_CONFIRMED`:return{name:`inProgress`,ctx:{input:t.ctx.input,tx:n.tx}};case`SUBMIT_FAILED`:return e(n.failure)?{name:`form`,ctx:{notice:n.failure.reason}}:{name:`error`,ctx:{input:n.input,failure:n.failure}};case`CLOSE`:return{name:`closed`};default:return t}}function o(e,t){switch(t.type){case`SETTLEMENT_SUCCEEDED`:return{name:`success`,ctx:{input:e.ctx.input,tx:e.ctx.tx}};case`SETTLEMENT_FAILED`:return{name:`error`,ctx:{input:e.ctx.input,tx:e.ctx.tx,...t.failure?{failure:t.failure}:{}}};case`CLOSE`:return{name:`closed`};default:return e}}function s(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function c(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function l(e){throw Error(`Unhandled withdraw state: ${JSON.stringify(e)}`)}export{t as initialState,n as reducer};
+import{createActivityReducers as e}from"../../../shared/orchestrator/createActivityReducers.js";import{isUserRejectionFailure as t}from"../../../shared/orchestrator/userRejection.js";import"../../../shared/orchestrator/index.js";import{assertNever as n}from"../../../shared/utils/assertNever.js";const r={name:`closed`},{reduceFromActivityList:i,reduceFromActivityDetail:a}=e({activityList:e=>({name:`activityList`,ctx:{backTarget:e}}),activityDetail:(e,t,n)=>({name:`activityDetail`,ctx:{settlementId:e,backTarget:t,viaList:n}}),closed:()=>({name:`closed`}),restoreFromBackTarget:e=>p(e)});function o(e,t){switch(e.name){case`closed`:return s(t);case`form`:return c(e,t);case`submitting`:return l(e,t);case`inProgress`:return u(e,t);case`success`:return d(e,t);case`error`:return f(e,t);case`activityList`:return i(e,t);case`activityDetail`:return a(e,t);default:return n(e)}}function s(e){return e.type===`OPEN`?{name:`form`}:{name:`closed`}}function c(e,t){switch(t.type){case`SUBMIT`:return{name:`submitting`,ctx:{input:t.input}};case`CLEAR_NOTICE`:return e.ctx?.notice?{name:`form`}:e;case`OPEN_ACTIVITY`:return{name:`activityList`,ctx:{backTarget:{kind:`form`,...e.ctx?.notice?{notice:e.ctx.notice}:{}}}};case`CLOSE`:return{name:`closed`};default:return e}}function l(e,n){switch(n.type){case`BEGIN_PROCESSING`:return{name:`inProgress`,ctx:{input:e.ctx.input,submittedAt:n.submittedAt,...n.tx?{tx:n.tx}:{}}};case`SET_TX_HASH`:return{name:`inProgress`,ctx:{input:e.ctx.input,submittedAt:n.submittedAt,tx:n.tx}};case`MARK_SUCCEEDED`:return{name:`success`,ctx:{input:e.ctx.input}};case`MARK_FAILED`:return{name:`error`,ctx:{input:e.ctx.input,...n.failure?{failure:n.failure}:{}}};case`SUBMIT_FAILED`:return t(n.failure)?{name:`form`,ctx:{notice:n.failure.reason}}:{name:`error`,ctx:{input:n.input,failure:n.failure}};case`CLOSE`:return{name:`closed`};default:return e}}function u(e,t){switch(t.type){case`SET_TX_HASH`:return{name:`inProgress`,ctx:{...e.ctx,tx:t.tx}};case`BEGIN_PROCESSING`:return{name:`inProgress`,ctx:{input:e.ctx.input,submittedAt:e.ctx.submittedAt,...e.ctx.tx?{tx:e.ctx.tx}:t.tx?{tx:t.tx}:{}}};case`MARK_SUCCEEDED`:return{name:`success`,ctx:{input:e.ctx.input,...e.ctx.tx?{tx:e.ctx.tx}:{}}};case`MARK_FAILED`:return{name:`error`,ctx:{input:e.ctx.input,...e.ctx.tx?{tx:e.ctx.tx}:{},...t.failure?{failure:t.failure}:{}}};case`SETTLEMENT_SUCCEEDED`:return{name:`success`,ctx:{input:e.ctx.input,...e.ctx.tx?{tx:e.ctx.tx}:{}}};case`SETTLEMENT_FAILED`:return{name:`error`,ctx:{input:e.ctx.input,...e.ctx.tx?{tx:e.ctx.tx}:{},...t.failure?{failure:t.failure}:{}}};case`CLOSE`:return{name:`closed`};default:return e}}function d(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function f(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function p(e){return e.notice?{name:`form`,ctx:{notice:e.notice}}:{name:`form`}}export{r as initialState,o as reducer};

package/dist/flows/withdraw/orchestrator/types.d.ts

@@ -1,6 +1,7 @@
 import { TxRef } from "../../../shared/driver/types.js";
 import { FailureInfo } from "../../../shared/orchestrator/types.js";
-
+import { WithdrawalQuotePayload } from "../driver/payloads.js";
+import { WithdrawPreparation } from "../driver/types.js";
 //#region src/flows/withdraw/orchestrator/types.d.ts
 /**
  * Form values captured at submit time. The orchestrator carries this snapshot through every
@@ -20,24 +21,43 @@ interface WithdrawalFormSnapshot {
   receiveTokenSymbol: string;
   /** Receive-side chain id (EIP-155 numeric). */
   receiveChainId: number;
+  /**
+   * Pre-formatted USD figure the form displayed under the amount input at submit time. Carried
+   * through the FSM so the in-progress / success heroes can render the same dollar value the
+   * user just saw on the form, before the indexer prices the settlement legs. Optional because
+   * the form's USD computation already returns `undefined` for invalid amounts; the snapshot
+   * mirrors that. Pre-formatted (locale-aware) — the orchestrator does not re-format.
+   */
+  amountUsd?: string;
+}
+/**
+ * Where `BACK` lands when the user exits the activity surface. Encoded once at `OPEN_ACTIVITY`
+ * time — the in-flow header icon is the only way into withdraw activity now (direct-entry
+ * migrated to `useActivity()`), so the form is always the source step.
+ */
+interface ActivityBackTarget {
+  kind: "form";
+  notice?: string;
 }
 /**
- * State machine state for the orchestrated withdraw dialog. Per-state discriminated `ctx` narrows
- * what data is available — illegal states (e.g. `inProgress` without a tx ref) are
- * unrepresentable.
+ * State machine state for the orchestrated withdraw dialog. Per-state discriminated `ctx`
+ * narrows what data is available.
  *
- * The reducer carries navigation intent only — entity-derived data (quote payload, settlement
- * payload, balances) lives on the driver and is read directly by widgets.
+ * **Host-paced lifecycle** (different from the old wagmi-signed model): the kit stays in
+ * `submitting` until the host's `onSubmit` callback calls one of the controller's actions
+ * (`beginProcessing`, `fail`, `succeed`). `inProgress` accepts an optional `tx` — the host may
+ * move the user into processing before a broadcast tx hash exists; the kit polls
+ * `gateway/{owner}` and best-matches the relevant settlement (destination tuple + amount +
+ * submit-time window) until the host supplies a tx hash via `setTxHash`. `success` / `error`
+ * similarly accept optional `tx` since the host may declare a terminal verdict directly.
  */
 type WithdrawState = {
   name: "closed";
 } | {
   name: "form";
   /**
-   * Optional notice rendered inline near the submit footer. Currently set when the user
-   * declines the wallet signature: the FSM lands the user back on the form (preserving
-   * recipient + amount + receive selection) with `notice = "Signature declined…"` so they
-   * can retry without losing context. Cleared on the next SUBMIT or CLOSE.
+   * Optional notice rendered inline near the submit footer. Cleared on the next SUBMIT
+   * or CLOSE.
    */
   ctx?: {
     notice?: string;
@@ -50,27 +70,56 @@ type WithdrawState = {
 } | {
   name: "inProgress";
   ctx: {
-    input: WithdrawalFormSnapshot;
-    tx: TxRef;
+    input: WithdrawalFormSnapshot; /** Unix-ms timestamp the host moved the FSM into processing (drives best-match windowing). */
+    submittedAt: number;
+    /**
+     * Source-chain broadcast hash, when the host has surfaced one via
+     * `actions.setTxHash`. Absent while the kit relies on the best-match heuristic.
+     */
+    tx?: TxRef;
   };
 } | {
   name: "success";
   ctx: {
     input: WithdrawalFormSnapshot;
-    tx: TxRef;
+    tx?: TxRef;
   };
 } | {
   name: "error";
   ctx: {
     /**
      * Form snapshot captured at submit time. Set when error follows a submit attempt;
-     * absent when the error path was reached without a known prior submit (currently
-     * unreachable in V2 — kept optional so resume-style entries can re-use the slot).
+     * absent when the error path was reached without a known prior submit.
      */
-    input?: WithdrawalFormSnapshot; /** Optional non-settlement failure (quote / submission rejection). */
+    input?: WithdrawalFormSnapshot; /** Optional non-settlement failure (quote / submission rejection, host-supplied failure). */
     failure?: FailureInfo; /** Source-chain broadcast tx hash when the error followed a successful broadcast. */
     tx?: TxRef;
   };
+} | {
+  /**
+   * Activity list — reachable from `form` via the header icon. `backTarget`
+   * snapshots the source state (including any inline notice) at `OPEN_ACTIVITY` time so
+   * the back chevron can restore it lossless.
+   */
+  name: "activityList";
+  ctx: {
+    backTarget: ActivityBackTarget;
+  };
+} | {
+  /**
+   * Activity per-settlement detail — reached from `activityList` via
+   * `SELECT_SETTLEMENT`. Carries the selected row's id, the same `backTarget` so `BACK`
+   * collapses through `activityList` to the original source step, and a `viaList` flag
+   * that disambiguates "reached via the list" from "reached imperatively"; the latter
+   * skips the list interlude on `BACK`. For direct-entry into the activity surface,
+   * see {@link useActivity}.
+   */
+  name: "activityDetail";
+  ctx: {
+    settlementId: string;
+    backTarget: ActivityBackTarget;
+    viaList: boolean;
+  };
 };
 /**
  * Public state-name discriminator — useful for analytics and React-side gating without unwrapping
@@ -79,21 +128,41 @@ type WithdrawState = {
 type WithdrawStateName = WithdrawState["name"];
 /**
  * Reducer event union. Strict discriminated; no stringly-typed transitions.
+ *
+ * The host-paced lifecycle splits the old `SUBMIT_CONFIRMED { tx }` event into three pieces so
+ * the host can move the user forward at whichever step their backend actually completes:
+ *
+ * - `BEGIN_PROCESSING { tx?, submittedAt }` — host accepted the request; move to inProgress with
+ *   or without a tx hash.
+ * - `SET_TX_HASH { tx }` — host surfaced a broadcast hash later; upgrade best-match polling to
+ *   tx-anchored.
+ * - `MARK_SUCCEEDED` / `MARK_FAILED { failure? }` — host short-circuits to a terminal verdict
+ *   (e.g. their own settlement verification ran independently of Stridge's poll).
  */
 type WithdrawEvent = {
-  type: "OPEN";
+  /** Lifecycle entry. Always lands the FSM on `form`. */type: "OPEN";
 } | {
   type: "CLOSE";
 } | {
   type: "SUBMIT";
   input: WithdrawalFormSnapshot;
 } | {
-  type: "SUBMIT_CONFIRMED";
+  type: "BEGIN_PROCESSING";
+  submittedAt: number;
+  tx?: TxRef;
+} | {
+  type: "SET_TX_HASH";
   tx: TxRef;
+  submittedAt: number;
 } | {
   type: "SUBMIT_FAILED";
   failure: FailureInfo;
   input: WithdrawalFormSnapshot;
+} | {
+  type: "MARK_SUCCEEDED";
+} | {
+  type: "MARK_FAILED";
+  failure?: FailureInfo;
 } | {
   type: "SETTLEMENT_SUCCEEDED";
 } | {
@@ -101,24 +170,48 @@ type WithdrawEvent = {
   failure?: FailureInfo;
 } | {
   type: "RESET";
-}
-/**
- * Drops the inline notice on the `form` state. Dispatched by the form widget when the user
- * starts editing again after a wallet-rejection landed them back on `form{notice}`. Mirror of
- * deposit's `regenerating → ready` transition (where the notice clears as a side-effect of
- * the next quote resolving) — withdraw's form has no FSM-driven phase to ride on, so the
- * widget signals it explicitly.
- */
-| {
+} | {
   type: "CLEAR_NOTICE";
+} | {
+  /**
+   * User tapped the back chevron. Legal only from `activityList` / `activityDetail` today —
+   * the form step has no source to return to (closing the dialog is `CLOSE`). Two-step
+   * collapse: `activityDetail → activityList → source`.
+   */
+  type: "BACK";
+} | {
+  /**
+   * User tapped the header activity icon. Legal from `form`; ignored elsewhere. Snapshots
+   * the source state into a {@link ActivityBackTarget} so the back chevron can restore it
+   * lossless (including any inline notice surfaced after a recent submit failure).
+   */
+  type: "OPEN_ACTIVITY";
+} | {
+  /**
+   * User tapped a row in the activity list. Legal only from `activityList`; transitions
+   * to `activityDetail` carrying the selected `settlementId`.
+   */
+  type: "SELECT_SETTLEMENT";
+  settlementId: string;
 };
+/**
+ * Public open-input variant accepted by `useWithdraw().open()`. Today the withdraw flow has no
+ * `{ method }` arm — opening always lands on `form`.
+ *
+ * For direct-entry into the activity surface, see {@link useActivity}.
+ */
+type WithdrawOpenInput = undefined;
 /**
  * Imperative controller returned by `useWithdraw()`. Mirrors {@link import("#/flows/deposit/orchestrator").DepositController}'s
  * surface so hosts can drive both flows symmetrically. Stable across re-renders.
  */
 interface WithdrawController {
-  /** Open the withdraw dialog. Idempotent. */
-  open(): void;
+  /**
+   * Open the withdraw dialog on `form`. Returns `true` whenever the open() call advanced the
+   * dialog past its guards — there is no per-method disable lever on withdraw, so the only
+   * `false` path is reserved for forward compatibility. Idempotent.
+   */
+  open(input?: WithdrawOpenInput): boolean;
   /** Close the withdraw dialog. Idempotent. */
   close(): void;
   /**
@@ -134,9 +227,11 @@ interface WithdrawController {
  */
 interface WithdrawActions {
   /**
-   * Submits the withdrawal through the driver. Dispatches `SUBMIT` synchronously (so the form
-   * flips to the loading-button state) and then `SUBMIT_CONFIRMED` / `SUBMIT_FAILED` based on
-   * the driver's `submitWithdrawal` resolution.
+   * Submits the withdrawal. Dispatches `SUBMIT` synchronously (so the form flips to the
+   * loading-button state) and then fires the host's `<WithdrawDialog onSubmit>` callback with
+   * the prepared UDA target + a `WithdrawSubmitActions` handle. The kit stays in `submitting`
+   * until the host calls one of those actions (`beginProcessing`, `setTxHash`, `decline`,
+   * `fail`, `succeed`).
    */
   submit(input: WithdrawalFormSnapshot): void;
   /** Close the dialog. Idempotent. */
@@ -147,10 +242,98 @@ interface WithdrawActions {
    */
   reset(): void;
   /**
-   * Clear the form's inline notice (typically the post-rejection "Signature declined." hint).
-   * No-op when there's no notice or the FSM isn't on `form`.
+   * Clear the form's inline notice. No-op when there's no notice or the FSM isn't on `form`.
    */
   clearNotice(): void;
+  /**
+   * Back-chevron action. Today the chevron is only rendered on the activity step
+   * (detail → list → source); other steps either render no chevron or close directly via
+   * {@link close}.
+   */
+  back(): void;
+  /**
+   * Header-icon entry into the activity surface. Legal from `form`; ignored elsewhere.
+   * Snapshots the current state into a {@link ActivityBackTarget} so `back()` can restore it
+   * lossless. No-ops with a dev-mode warning when no activity driver is mounted (host wired the
+   * action without `<KitProvider activity={…}>`).
+   */
+  openActivity(): void;
+  /**
+   * Open the detail view for a settlement listed on the activity surface. Legal only from
+   * `activityList`; transitions the FSM to `activityDetail`.
+   */
+  selectSettlement(settlementId: string): void;
+}
+/**
+ * Payload the kit hands to the host's `<WithdrawDialog onSubmit>` callback. Carries everything
+ * the host needs to broadcast the source-chain transfer to the UDA (or to validate the request
+ * server-side before broadcasting / queueing).
+ */
+interface WithdrawSubmitInput {
+  /** What the user picked on the form (recipient, amount, receive token + chain). */
+  form: WithdrawalFormSnapshot;
+  /** Where the host should send brand-currency funds to trigger the bridge. */
+  depositTarget: WithdrawPreparation["depositTarget"];
+  /** Stridge correlation slot — useful for backend logs / cross-system traces. */
+  correlation: WithdrawPreparation["correlation"];
+  /** Active quote payload at submit time, when one is available. */
+  quote?: WithdrawalQuotePayload;
 }
+/**
+ * Imperative handles the host's `onSubmit` callback receives. Each action advances the kit's
+ * FSM at the point the host's backend reaches the matching state. All actions are optional —
+ * the host calls only what fits their flow (e.g. backend pre-validates and accepts ⇒
+ * `beginProcessing()`; later the broadcast lands ⇒ `setTxHash({ hash })`; settlement watching
+ * via Stridge takes over from there). The kit also exposes a `signal` for cancellation when
+ * the user closes the dialog mid-submit.
+ */
+interface WithdrawSubmitActions {
+  /**
+   * Move the FSM into `inProgress`. Pass `tx` if a broadcast hash already exists at this point;
+   * otherwise omit — the kit polls `gateway/{owner}` with a best-match heuristic until you
+   * call {@link setTxHash}. Idempotent — calling more than once is a no-op.
+   */
+  beginProcessing(tx?: TxRef): void;
+  /**
+   * Surface a broadcast hash mid-processing. Upgrades the watcher from best-match to
+   * tx-anchored. Legal from `inProgress` or `submitting` (auto-promotes to `inProgress`).
+   */
+  setTxHash(tx: TxRef): void;
+  /**
+   * Mark the withdraw failed. Legal from `submitting` (pre-broadcast rejection) and
+   * `inProgress` (post-broadcast failure). The optional `failure` carries a localized
+   * reason + machine code for analytics; omit when the host has nothing meaningful to
+   * report and just needs to terminate the flow.
+   *
+   * For user-rejection (the user said no in their wallet), prefer {@link decline} so the
+   * kit can emit `withdraw.submission.declined` instead of `withdraw.submission.failed`.
+   */
+  fail(failure?: FailureInfo): void;
+  /**
+   * Mark the withdraw as user-declined. Use when the user explicitly refused a wallet
+   * prompt or backed out of a host-side confirmation step. The kit routes the FSM back to
+   * `form{notice}` (same as the wallet-rejection heuristic) and emits
+   * `withdraw.submission.declined` on the unified bus — distinct from `*.failed` because
+   * declining is a user choice, not an error. Analytics that count `.failed` events stay
+   * accurate.
+   *
+   * Legal from `submitting`. When the host doesn't call this explicitly, the kit's
+   * built-in rejection heuristic still classifies wallet-rejection-shaped errors as
+   * declines automatically.
+   */
+  decline(): void;
+  /**
+   * Mark the withdraw succeeded directly. Useful when the host runs their own settlement
+   * verification independently of Stridge's poll. Legal from `submitting` and `inProgress`.
+   */
+  succeed(): void;
+}
+/**
+ * Host-supplied callback fired when the user submits the withdrawal form. The kit hands the
+ * callback the resolved {@link WithdrawSubmitInput} plus a {@link WithdrawSubmitActions} handle
+ * the host calls to advance the FSM. The kit does NOT await the callback's promise — the host
+ * is in control of pacing via the actions. The `signal` aborts when the user closes the dialog.
+ */
+type WithdrawSubmitCallback = (input: WithdrawSubmitInput, actions: WithdrawSubmitActions, signal: AbortSignal) => void | Promise<void>;
 //#endregion
-export { WithdrawActions, WithdrawController, WithdrawEvent, WithdrawState, WithdrawStateName, WithdrawalFormSnapshot };
+export { WithdrawActions, WithdrawController, WithdrawEvent, WithdrawState, WithdrawStateName, WithdrawSubmitActions, WithdrawSubmitCallback, WithdrawSubmitInput, WithdrawalFormSnapshot };

package/dist/flows/withdraw/orchestrator/useWithdraw.d.ts

@@ -19,5 +19,40 @@ import { WithdrawController } from "./types.js";
  * ```
  */
 declare function useWithdraw(): WithdrawController;
+/**
+ * Non-throwing variant of {@link useWithdraw} — returns `null` when called outside a
+ * `<KitProvider withdraw={…} />`. Lets hosts mount `<StridgeProvider />` conditionally
+ * (e.g. only after a wallet is connected) without descendants crashing the moment they render
+ * before the provider exists.
+ *
+ * @example
+ * ```tsx
+ * const withdraw = useOptionalWithdraw();
+ * return (
+ *     <button onClick={() => withdraw?.open()} disabled={!withdraw}>
+ *         Withdraw
+ *     </button>
+ * );
+ * ```
+ */
+declare function useOptionalWithdraw(): WithdrawController | null;
+/**
+ * Headless prefetch handle for the withdraw driver. Returns a stable function that arms the
+ * driver — kicks off the deferred `supportedAssets` + initial `balance/onchain` bootstrap.
+ * Calling it before the user opens the dialog warms the cache so the subsequent
+ * `useWithdraw().open()` lands on populated data without a perceptible loading window.
+ *
+ * Fire-and-forget: returns `void`. Observe bootstrap state via
+ * `useWithdrawSnapshot().receiveOptions.status` if needed.
+ *
+ * ```tsx
+ * const withdraw = useWithdraw();
+ * const prefetchWithdraw = usePrefetchWithdraw();
+ * <button onMouseEnter={prefetchWithdraw} onClick={() => withdraw.open()}>Withdraw</button>;
+ * ```
+ *
+ * Idempotent — subsequent calls are no-ops while the driver is already armed.
+ */
+declare function usePrefetchWithdraw(): () => void;
 //#endregion
-export { useWithdraw };
+export { useOptionalWithdraw, usePrefetchWithdraw, useWithdraw };

package/dist/flows/withdraw/orchestrator/useWithdraw.js

@@ -1 +1 @@
-"use client";import{useControllerContext as e}from"./controller.js";function t(){return e().controller}export{t as useWithdraw};
+"use client";import{useWithdrawDriverInstance as e}from"../driver/context.js";import{useControllerContext as t,useOptionalControllerContext as n}from"./controller.js";import{useCallback as r}from"react";function i(){return t().controller}function a(){return n()?.controller??null}function o(){let t=e();return r(()=>{t.arm()},[t])}export{a as useOptionalWithdraw,o as usePrefetchWithdraw,i as useWithdraw};

package/dist/flows/withdraw/widgets/activity/WithdrawActivityDetail.d.ts

@@ -0,0 +1,39 @@
+import { ReactNode } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/flows/withdraw/widgets/activity/WithdrawActivityDetail.d.ts
+interface WithdrawActivityDetailOwnProps {
+  /**
+   * Optional custom composition forwarded to the underlying `<ActivityDetail>`
+   * compound. Defaults to mounting all three per-kind parts.
+   */
+  children?: ReactNode;
+}
+/**
+ * Orchestrated activity detail wrapper for the withdraw dialog. Mirrors
+ * {@link import("#/flows/deposit/widgets/activity").DepositActivityDetail}. Renders
+ * `null` while the FSM is not on `activityDetail`.
+ */
+declare function WithdrawActivityDetail({
+  children
+}: WithdrawActivityDetailOwnProps): _$react_jsx_runtime0.JSX.Element | null;
+declare namespace WithdrawActivityDetail {
+  type Props = WithdrawActivityDetailOwnProps;
+  const Processing: ({
+    children
+  }: {
+    children?: ReactNode;
+  }) => _$react_jsx_runtime0.JSX.Element | null;
+  const Succeeded: ({
+    children
+  }: {
+    children?: ReactNode;
+  }) => _$react_jsx_runtime0.JSX.Element | null;
+  const Failed: ({
+    children
+  }: {
+    children?: ReactNode;
+  }) => _$react_jsx_runtime0.JSX.Element | null;
+}
+//#endregion
+export { WithdrawActivityDetail };

package/dist/flows/withdraw/widgets/activity/WithdrawActivityDetail.js

@@ -0,0 +1 @@
+"use client";import{ActivitySourceProvider as e}from"../../../../shared/widgets/activity/compound/context.js";import{ActivityDetail as t}from"../../../../shared/widgets/activity/compound/ActivityDetail.js";import"../../../../shared/widgets/activity/compound/index.js";import{useWithdrawActivitySource as n}from"./useWithdrawActivitySource.js";import{jsx as r}from"react/jsx-runtime";function i({children:i}){let{sourceValue:a,step:o}=n();return o!==`activityDetail`||!a?null:r(e,{value:a,children:r(t,{children:i})})}(function(e){e.Processing=t.Processing,e.Succeeded=t.Succeeded,e.Failed=t.Failed})(i||={});export{i as WithdrawActivityDetail};

package/dist/flows/withdraw/widgets/activity/WithdrawActivityList.d.ts

@@ -0,0 +1,36 @@
+import { ActivityHeader, ActivityListHeader } from "../../../../shared/widgets/activity/compound/components/ActivityHeader.js";
+import { ActivityEmpty } from "../../../../shared/widgets/activity/compound/components/Empty.js";
+import { ActivityErrorView } from "../../../../shared/widgets/activity/compound/components/ErrorView.js";
+import { ActivityList } from "../../../../shared/widgets/activity/compound/components/List.js";
+import { ActivityRow } from "../../../../shared/widgets/activity/compound/components/Row.js";
+import { ComponentProps, ReactNode } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/flows/withdraw/widgets/activity/WithdrawActivityList.d.ts
+interface WithdrawActivityListOwnProps {
+  /**
+   * Optional custom composition forwarded to the underlying `<Activity>` compound.
+   * Defaults to the compound's `<Header /> + <List />` shape.
+   */
+  children?: ReactNode;
+}
+/**
+ * Orchestrated activity list wrapper for the withdraw dialog. Mirrors
+ * {@link import("#/flows/deposit/widgets/activity").DepositActivityList}. Renders
+ * `null` while the FSM is not on `activityList`.
+ */
+declare function WithdrawActivityList({
+  children,
+  ...props
+}: ComponentProps<"div"> & WithdrawActivityListOwnProps): _$react_jsx_runtime0.JSX.Element | null;
+declare namespace WithdrawActivityList {
+  type Props = ComponentProps<"div"> & WithdrawActivityListOwnProps;
+  const Header: typeof ActivityHeader;
+  const ListHeader: typeof ActivityListHeader;
+  const List: typeof ActivityList;
+  const Row: typeof ActivityRow;
+  const Empty: typeof ActivityEmpty;
+  const ErrorView: typeof ActivityErrorView;
+}
+//#endregion
+export { WithdrawActivityList };

package/dist/flows/withdraw/widgets/activity/WithdrawActivityList.js

@@ -0,0 +1 @@
+"use client";import{ActivitySourceProvider as e}from"../../../../shared/widgets/activity/compound/context.js";import{Activity as t}from"../../../../shared/widgets/activity/compound/Activity.js";import"../../../../shared/widgets/activity/compound/index.js";import{useWithdrawActivitySource as n}from"./useWithdrawActivitySource.js";import{jsx as r}from"react/jsx-runtime";function i({children:i,...a}){let{sourceValue:o,step:s}=n();return s!==`activityList`||!o?null:r(e,{value:o,children:r(t,{...a,children:i})})}(function(e){e.Header=t.Header,e.ListHeader=t.ListHeader,e.List=t.List,e.Row=t.Row,e.Empty=t.Empty,e.ErrorView=t.ErrorView})(i||={});export{i as WithdrawActivityList};

package/dist/flows/withdraw/widgets/activity/index.d.ts

@@ -0,0 +1,2 @@
+import { WithdrawActivityDetail } from "./WithdrawActivityDetail.js";
+import { WithdrawActivityList } from "./WithdrawActivityList.js";

package/dist/flows/withdraw/widgets/activity/index.js

@@ -0,0 +1 @@
+import"./WithdrawActivityDetail.js";import"./WithdrawActivityList.js";

package/dist/flows/withdraw/widgets/activity/useWithdrawActivitySource.js

@@ -0,0 +1 @@
+"use client";import{useOptionalActivityDriverInstance as e,useOptionalActivitySnapshot as t}from"../../../activity/driver/context.js";import{useLingui as n}from"../../../../shared/i18n/useLingui.js";import"../../../../i18n/index.js";import{useWithdrawActions as r,useWithdrawEffectiveState as i}from"../../orchestrator/controller.js";import"../../orchestrator/index.js";import{defaultBlockExplorers as a}from"../../../../shared/utils/explorers.js";import{useCallback as o,useMemo as s}from"react";function c(){let c=r(),l=e(),u=t(),d=i(),{i18n:f}=n(),p=o(e=>{l?.refreshActivity(e)},[l]),m=d.name===`activityList`||d.name===`activityDetail`,h=d.name===`activityDetail`?d.ctx.settlementId:void 0,g=m;return{sourceValue:s(()=>{if(!m||!u)return null;let e=u.activity,t=e.status===`ready`||e.status===`stale`?e.response.owner:`0x0000000000000000000000000000000000000000`,n=e.status===`ready`||e.status===`stale`?e.payload.brandName:void 0,r={i18n:f,sourceWallet:{name:`Wallet`,address:t},explorers:a(),...n?{brandName:n}:{}};return{entity:u.activity,refresh:p,selectSettlement:c.selectSettlement,...g?{back:c.back}:{},...h===void 0?{}:{settlementId:h},settlementContext:r}},[u,c,m,h,f,p,g]),settlementId:h,step:d.name===`activityList`?`activityList`:d.name===`activityDetail`?`activityDetail`:`other`}}export{c as useWithdrawActivitySource};

package/dist/flows/withdraw/widgets/withdraw/compound/Withdraw.d.ts

@@ -0,0 +1,60 @@
+import { WithdrawStateName } from "../../../orchestrator/types.js";
+import { Props, WithdrawBoundary } from "./components/Boundary.js";
+import { Props as Props$1, WithdrawGuards } from "./components/Guards.js";
+import { WithdrawSteps, WithdrawStepsProps } from "./components/Steps.js";
+import { ReactNode } from "react";
+
+//#region src/flows/withdraw/widgets/withdraw/compound/Withdraw.d.ts
+interface WithdrawStepProps {
+  /**
+   * Matches against the withdraw FSM's effective state name (with `submitting` collapsed
+   * to `form`). Declaring `name="submitting"` never matches — use `name="form"` and the
+   * widget stays mounted across both states.
+   */
+  name: WithdrawStateName;
+  children: ReactNode;
+}
+/**
+ * Top-level `Withdraw` compound namespace. Today exposes the slot-routing primitives that
+ * let hosts compose multi-screen withdraw flows; the namespace exists at this position so
+ * future `Withdraw.*` parts (Header, Body, …) can extend it without churning the import path.
+ *
+ * Hosts wire it like the deposit equivalent:
+ *
+ * ```tsx
+ * <Withdraw.Steps>
+ *   <Withdraw.Step name="form"><WithdrawForm /></Withdraw.Step>
+ *   <Withdraw.Step name="inProgress"><WithdrawInProgress /></Withdraw.Step>
+ *   <Withdraw.Step name="success"><WithdrawSuccess /></Withdraw.Step>
+ *   <Withdraw.Step name="error"><WithdrawError /></Withdraw.Step>
+ * </Withdraw.Steps>
+ * ```
+ *
+ * Rendered directly (`<Withdraw />`) the component is a no-op — reach into the sub-parts.
+ */
+declare function Withdraw(): null;
+declare namespace Withdraw {
+  type StepsProps = WithdrawStepsProps;
+  type StepProps = WithdrawStepProps;
+  type GuardsProps = Props$1;
+  type BoundaryProps = Props;
+  const Steps: typeof WithdrawSteps;
+  /**
+   * Slot consumed by {@link Withdraw.Steps}. `name` is the FSM state to match; the matched
+   * step's `children` are rendered, every other branch is dropped.
+   */
+  const Step: (props: WithdrawStepProps) => null;
+  /**
+   * Bootstrap-loading guard. While `gateway/start` is in flight on the form / submitting
+   * step pair, renders a centered spinner instead of empty form chrome. Falls through to
+   * children for every other state.
+   */
+  const Guards: typeof WithdrawGuards;
+  /**
+   * Error-boundary part. Wires the kit's `GatewayKitBoundary` with withdraw-flow recovery —
+   * `onReset` calls `useWithdraw().close()` internally; `onError` is host-supplied.
+   */
+  const Boundary: typeof WithdrawBoundary;
+}
+//#endregion
+export { Withdraw };

package/dist/flows/withdraw/widgets/withdraw/compound/Withdraw.js

@@ -0,0 +1 @@
+"use client";import{Step as e}from"../../../../../shared/ui/Steps/Steps.js";import"../../../../../shared/ui/Steps/index.js";import{WithdrawBoundary as t}from"./components/Boundary.js";import{WithdrawGuards as n}from"./components/Guards.js";import{WithdrawSteps as r}from"./components/Steps.js";function i(){return null}(function(i){i.Steps=r,i.Step=e,i.Guards=n,i.Boundary=t})(i||={});export{i as Withdraw};

package/dist/flows/withdraw/widgets/withdraw/compound/Withdraw.slots.d.ts

@@ -0,0 +1,13 @@
+//#region src/flows/withdraw/widgets/withdraw/compound/Withdraw.slots.d.ts
+/**
+ * `<Withdraw.*>` slot vocabulary. Today the namespace only houses `Withdraw.Steps` /
+ * `Withdraw.Step`, both of which route their slot attribute through the shared `Steps`
+ * primitive. The constant exists so future `Withdraw.*` parts (Header, Body, …) have a
+ * canonical slot map ready when they land.
+ */
+declare const WITHDRAW_SLOTS: {
+  readonly root: "withdraw-root";
+};
+type WithdrawSlot = (typeof WITHDRAW_SLOTS)[keyof typeof WITHDRAW_SLOTS];
+//#endregion
+export { WITHDRAW_SLOTS, WithdrawSlot };

package/dist/flows/withdraw/widgets/withdraw/compound/Withdraw.slots.js

@@ -0,0 +1 @@
+const e={root:`withdraw-root`};export{e as WITHDRAW_SLOTS};