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

package/dist/events/types/deposit.d.ts

@@ -0,0 +1,235 @@
+import { SettlementFailureKind, TxRef } from "../../shared/driver/types.js";
+import { BalanceItemPayload, QuotePayload, SettlementPendingPayload, SettlementSuccessPayload } from "../../flows/deposit/driver/payloads.js";
+import { DepositMethod, DepositStateName, ResolvedOpenInput } from "../../flows/deposit/orchestrator/types.js";
+import { FailurePayloadBase, StridgeEventBase } from "./envelope.js";
+import { TransferCryptoChain, TransferCryptoToken } from "../../flows/deposit/widgets/transfer-crypto/compound/types.js";
+
+//#region src/events/types/deposit.d.ts
+/**
+ * Orchestrator-level input the kit assembled to ask the driver for a deposit quote. Mirrors
+ * the shape of {@link import("#/flows/withdraw/driver").RequestWithdrawalQuoteInput} for the
+ * deposit side — wrapping the request fields in a single `input` field keeps the `payload`
+ * shape symmetric across flows so generic analytics handlers can write
+ * `track("quote_requested", e.payload.input)` for both flows.
+ */
+interface DepositQuoteRequestInput {
+  /** Source-side asset the user picked on the AssetPicker step. */
+  asset: BalanceItemPayload;
+  /** Send amount in display units. */
+  amount: number;
+}
+/**
+ * Phase the deposit flow was in when it was cancelled. Lets consumers distinguish "user
+ * abandoned at amount entry" from "user abandoned during processing wait" without parsing
+ * step names.
+ */
+type DepositCancelPhase = "quoting" | "confirming" | "submitting" | "processing" | "unknown";
+/**
+ * Settlement failure variant — extends the base with settlement-specific structure
+ * (typed `kind`, optional `txHash`) when the failure originates from the gateway's
+ * settlement entity rather than from a generic orchestrator path.
+ */
+interface DepositSettlementFailurePayload extends FailurePayloadBase {
+  /**
+   * Driver-classified failure kind for downstream branching. Bounded enum so consumers can
+   * `switch (e.payload.kind)` exhaustively. The kit also escalates FSM-level failures with
+   * `kind: "unknown"` when no settlement-specific classification applies.
+   */
+  kind: SettlementFailureKind;
+  /** On-chain transaction hash, when one was successfully broadcast before settlement failed. */
+  txHash?: TxRef;
+}
+/**
+ * Orchestrator asked the driver for a quote — either the first request for this asset/amount
+ * pair or a regeneration after expiry or signature decline. The payload carries the inputs
+ * the orchestrator used so consumers can correlate request → response.
+ */
+type DepositQuoteRequestedEvent = StridgeEventBase<"deposit.quote.requested", "deposit", "flow", {
+  input: DepositQuoteRequestInput;
+}>;
+/**
+ * Driver returned a successful quote and the orchestrator transitioned to `ready`. Payload is
+ * the full quote entity; reflect-then-render is safe (the orchestrator will not regenerate
+ * silently between this event and the next user action unless the quote expires).
+ */
+type DepositQuoteResolvedEvent = StridgeEventBase<"deposit.quote.resolved", "deposit", "flow", {
+  quote: QuotePayload;
+}>;
+/**
+ * Quote fetch failed. Payload is the standard {@link FailurePayloadBase} — same shape as every
+ * other `*.failed` event so generic error handlers work without per-event branching.
+ */
+type DepositQuoteFailedEvent = StridgeEventBase<"deposit.quote.failed", "deposit", "flow", FailurePayloadBase>;
+/**
+ * Active quote went stale (TTL elapsed) before the user could submit, and the orchestrator
+ * silently started regenerating it. Payload is empty — the next `deposit.quote.resolved`
+ * carries the replacement quote.
+ */
+type DepositQuoteExpiredEvent = StridgeEventBase<"deposit.quote.expired", "deposit", "flow", Record<string, never>>;
+/**
+ * Wallet broadcast the deposit transaction and the orchestrator transitioned into
+ * `processing`. The on-chain tx hash is now stable; settlement polling has started.
+ */
+type DepositSubmissionBroadcastEvent = StridgeEventBase<"deposit.submission.broadcast", "deposit", "flow", {
+  tx: TxRef;
+}>;
+/**
+ * User refused the wallet signature prompt. Distinct from {@link DepositSubmissionFailedEvent} —
+ * declining is a user choice, not an error. The orchestrator regenerates the quote and lands
+ * the user back on the confirm step.
+ */
+type DepositSubmissionDeclinedEvent = StridgeEventBase<"deposit.submission.declined", "deposit", "flow", Record<string, never>>;
+/**
+ * Submission attempted but couldn't complete — network failure, backend rejection, broken
+ * wallet provider, anything that isn't user-rejection. Carries the standard
+ * {@link FailurePayloadBase}.
+ */
+type DepositSubmissionFailedEvent = StridgeEventBase<"deposit.submission.failed", "deposit", "flow", FailurePayloadBase>;
+/**
+ * Background `fetchActiveSettlement` probe surfaced a pre-existing pending deposit on flow
+ * start — the user hadn't started this flow in this session but a prior unfinished deposit
+ * was detected and resumed. Payload is the settlement entity's pending snapshot.
+ *
+ * Withdraw has no symmetric event: the withdraw driver does not currently probe for
+ * pre-existing pending withdrawals (host-driven submission means the host already knows
+ * when a withdrawal was started). If withdraw later grows an equivalent probe, the
+ * symmetric `withdraw.settlement.resumed` will land at that time.
+ */
+type DepositSettlementResumedEvent = StridgeEventBase<"deposit.settlement.resumed", "deposit", "flow", {
+  settlement: SettlementPendingPayload;
+}>;
+/**
+ * Settlement entity emitted a progressive pending update — confirmations advancing, partial
+ * fill credited, etc. Fires once per update; payload always reflects the current snapshot.
+ */
+type DepositSettlementProgressedEvent = StridgeEventBase<"deposit.settlement.progressed", "deposit", "flow", {
+  settlement: SettlementPendingPayload;
+}>;
+/**
+ * Terminal success — settlement entity reached `ready{kind: "succeeded"}`. The flow is over;
+ * this event closes the session and the `flowId` is retired after it fires.
+ */
+type DepositSettlementSucceededEvent = StridgeEventBase<"deposit.settlement.succeeded", "deposit", "flow", {
+  settlement: SettlementSuccessPayload;
+}>;
+/**
+ * Terminal failure — settlement entity reached `ready{kind: "failed"}` (driver-emitted
+ * classification) or the orchestrator escalated an FSM-level failure to the global error arm.
+ * Payload extends the standard {@link FailurePayloadBase} with settlement-specific fields.
+ */
+type DepositSettlementFailedEvent = StridgeEventBase<"deposit.settlement.failed", "deposit", "flow", DepositSettlementFailurePayload>;
+/**
+ * Flow ended before reaching a terminal state — typically the user closed the dialog
+ * mid-flow, or an AbortSignal fired. `payload.phase` indicates where in the lifecycle the
+ * cancellation happened so consumers can build drop-off funnels without parsing step names.
+ */
+type DepositCancelledEvent = StridgeEventBase<"deposit.cancelled", "deposit", "flow", {
+  phase: DepositCancelPhase;
+}>;
+/** Union of every `deposit.*` `flow:*` event. */
+type DepositFlowEvent = DepositQuoteRequestedEvent | DepositQuoteResolvedEvent | DepositQuoteFailedEvent | DepositQuoteExpiredEvent | DepositSubmissionBroadcastEvent | DepositSubmissionDeclinedEvent | DepositSubmissionFailedEvent | DepositSettlementResumedEvent | DepositSettlementProgressedEvent | DepositSettlementSucceededEvent | DepositSettlementFailedEvent | DepositCancelledEvent;
+/**
+ * Dialog transitioned from `closed` to any open step. Mints the `flowId` (every subsequent
+ * event in this session carries the same `flowId`) and snapshots the `metadata` prop.
+ */
+type DepositOpenedEvent = StridgeEventBase<"deposit.opened", "deposit", "ui", {
+  input: ResolvedOpenInput;
+}>;
+/**
+ * Dialog returned to `closed`. `payload.atStep` is the step name the dialog was on at close
+ * time. Fires after any terminal event (`*.succeeded` / `*.failed`) or `deposit.cancelled`
+ * in the same session.
+ */
+type DepositClosedEvent = StridgeEventBase<"deposit.closed", "deposit", "ui", {
+  atStep: DepositStateName;
+}>;
+/**
+ * Dialog step transitioned. Fires on every logical step change including back-presses.
+ * `from === to` is not emitted; same-step `ctx` changes (e.g. `confirmDeposit` phase shifts)
+ * surface through their respective `flow:*` events instead.
+ */
+type DepositStepChangedEvent = StridgeEventBase<"deposit.step.changed", "deposit", "ui", {
+  from: DepositStateName;
+  to: DepositStateName;
+}>;
+/**
+ * User clicked a deposit method tile (`wallet` / `transfer`) on the entry step. Fires on
+ * commit — picking is the action that advances the FSM.
+ */
+type DepositMethodClickedEvent = StridgeEventBase<"deposit.method.clicked", "deposit", "ui", {
+  method: DepositMethod;
+}>;
+/**
+ * User clicked an asset row on the AssetPicker step. The asset is the driver-shaped balance row;
+ * use {@link BalanceItemPayload}'s `symbol` and `chainId` to identify it.
+ */
+type DepositAssetClickedEvent = StridgeEventBase<"deposit.asset.clicked", "deposit", "ui", {
+  asset: BalanceItemPayload;
+}>;
+/**
+ * User typed in the amount field on the AmountEntry step. Fires per keystroke (no debounce);
+ * `payload.raw` is the literal input string, `payload.numeric` is the parsed value (or `null`
+ * when empty / unparseable). Use this for live UI; use {@link DepositAmountSubmittedEvent} for
+ * commitment.
+ */
+type DepositAmountChangedEvent = StridgeEventBase<"deposit.amount.changed", "deposit", "ui", {
+  raw: string;
+  numeric: number | null;
+}>;
+/**
+ * User clicked the Max preset in the AmountEntry step (fills the amount with the full
+ * available balance). Mirrors {@link import("./withdraw").WithdrawMaxClickedEvent}.
+ */
+type DepositMaxClickedEvent = StridgeEventBase<"deposit.max.clicked", "deposit", "ui", Record<string, never>>;
+/**
+ * User submitted the AmountEntry step. `payload.amount` is the parsed numeric value (the FSM
+ * would not have advanced otherwise). The next event is typically `deposit.quote.requested`.
+ */
+type DepositAmountSubmittedEvent = StridgeEventBase<"deposit.amount.submitted", "deposit", "ui", {
+  amount: number;
+}>;
+/**
+ * User clicked the Confirm button on the ConfirmDeposit step. Fires unconditionally on click —
+ * even when the button is disabled / mid-submit — so analytics can observe intent regardless
+ * of whether the click triggers FSM advance. Mirrors
+ * {@link import("./withdraw").WithdrawSubmitClickedEvent}. Use
+ * {@link DepositSubmissionConfirmedEvent} for the FSM-level "submission accepted" signal.
+ */
+type DepositConfirmClickedEvent = StridgeEventBase<"deposit.confirm.clicked", "deposit", "ui", Record<string, never>>;
+/**
+ * Confirm-step FSM transition to the submitting phase — the wallet prompt is about to fire.
+ * Fires only when the FSM accepts the submission (the click was valid); for the raw click
+ * signal (regardless of validity), subscribe to {@link DepositConfirmClickedEvent}. The
+ * next event is typically `deposit.submission.broadcast`, `deposit.submission.declined`, or
+ * `deposit.submission.failed`.
+ */
+type DepositSubmissionConfirmedEvent = StridgeEventBase<"deposit.submission.confirmed", "deposit", "ui", Record<string, never>>;
+/**
+ * User clicked the Back chevron in the dialog header on a non-root step. `payload.fromStep` is
+ * the step they were leaving. Withdraw has no symmetric event — the withdraw dialog is
+ * single-form with no Back affordance (the dialog X closes the flow instead).
+ */
+type DepositBackClickedEvent = StridgeEventBase<"deposit.back.clicked", "deposit", "ui", {
+  fromStep: DepositStateName;
+}>;
+/**
+ * Inside the TransferCrypto compound, user picked a different source token. The selection
+ * affects which deposit address is shown but does not advance the FSM.
+ */
+type DepositTransferTokenChangedEvent = StridgeEventBase<"deposit.transfer.token.changed", "deposit", "ui", {
+  token: TransferCryptoToken;
+}>;
+/** Inside the TransferCrypto compound, user picked a different source chain. */
+type DepositTransferChainChangedEvent = StridgeEventBase<"deposit.transfer.chain.changed", "deposit", "ui", {
+  chain: TransferCryptoChain;
+}>;
+/** User clicked the copy-address button in the TransferCrypto compound. */
+type DepositTransferAddressCopiedEvent = StridgeEventBase<"deposit.transfer.address.copied", "deposit", "ui", {
+  address: string;
+}>;
+/** Union of every `deposit.*` `ui:*` event. */
+type DepositUiEvent = DepositOpenedEvent | DepositClosedEvent | DepositStepChangedEvent | DepositMethodClickedEvent | DepositAssetClickedEvent | DepositAmountChangedEvent | DepositMaxClickedEvent | DepositAmountSubmittedEvent | DepositConfirmClickedEvent | DepositSubmissionConfirmedEvent | DepositBackClickedEvent | DepositTransferTokenChangedEvent | DepositTransferChainChangedEvent | DepositTransferAddressCopiedEvent;
+/** Union of every `deposit.*` event regardless of tier. */
+type DepositEvent = DepositFlowEvent | DepositUiEvent;
+//#endregion
+export { DepositAmountChangedEvent, DepositAmountSubmittedEvent, DepositAssetClickedEvent, DepositBackClickedEvent, DepositCancelPhase, DepositCancelledEvent, DepositClosedEvent, DepositConfirmClickedEvent, DepositEvent, DepositFlowEvent, DepositMaxClickedEvent, DepositMethodClickedEvent, DepositOpenedEvent, DepositQuoteExpiredEvent, DepositQuoteFailedEvent, DepositQuoteRequestInput, DepositQuoteRequestedEvent, DepositQuoteResolvedEvent, DepositSettlementFailedEvent, DepositSettlementFailurePayload, DepositSettlementProgressedEvent, DepositSettlementResumedEvent, DepositSettlementSucceededEvent, DepositStepChangedEvent, DepositSubmissionBroadcastEvent, DepositSubmissionConfirmedEvent, DepositSubmissionDeclinedEvent, DepositSubmissionFailedEvent, DepositTransferAddressCopiedEvent, DepositTransferChainChangedEvent, DepositTransferTokenChangedEvent, DepositUiEvent };

package/dist/events/types/envelope.d.ts

@@ -0,0 +1,145 @@
+//#region src/events/types/envelope.d.ts
+/**
+ * Envelope, tier, flow, and failure types shared by every event variant in the unified bus.
+ *
+ * # Naming pattern (READ THIS BEFORE ADDING A NEW EVENT)
+ *
+ * Every event type is a string of the form `<flow>.<noun>.<verb-past>` (or
+ * `<flow>.<noun>.<sub-noun>.<verb-past>` for nested concepts):
+ *
+ * - `deposit.quote.resolved`
+ * - `withdraw.settlement.succeeded`
+ * - `deposit.transfer.address.copied`
+ * - `kit.support.opened`
+ *
+ * Rules:
+ *
+ * 1. **Lowercase, dot-segmented.** No camelCase, no colons, no slashes.
+ * 2. **Past-tense final verb.** Events describe things that already happened. `quote.resolved`,
+ *    not `quote.resolve`. Even in-flight signals use past tense (`quote.requested` — the
+ *    request *was made*).
+ * 3. **Same `noun.verb` across flows = same semantic concept.** A consumer who learns deposit
+ *    events should immediately recognise the withdraw equivalents. If a concept exists in both
+ *    flows, the trailing segments must match: `deposit.quote.resolved` ↔ `withdraw.quote.resolved`.
+ * 4. **Flow prefix is required.** Even for events that conceptually exist in both flows, each
+ *    flow gets its own typed variant. The prefix lets TypeScript narrow payloads precisely on
+ *    `e.type ===` checks without needing additional `e.flow ===` guards.
+ *
+ * # Tier rule
+ *
+ * - `tier: "flow"` — orchestrator/driver-emitted domain milestones (quote, submission,
+ *   settlement). Fire whether or not the user sees any UI, as long as the orchestrator is
+ *   running (which today means a dialog is mounted).
+ * - `tier: "ui"` — user-driven affordances and view-state changes from any kit-rendered
+ *   element. Includes dialog lifecycle (open / close / step.changed) and widget interactions
+ *   (keystrokes, selections, copy clicks). Fires only when the relevant kit-rendered component
+ *   is mounted.
+ *
+ * # Envelope shape
+ *
+ * Every event variant ships as a `StridgeEventBase<...>`. Field discipline:
+ *
+ * - `type` — unique string discriminator. Stable across versions; never reshape an existing
+ *   `type`. Adding a new event = adding a new variant to the appropriate union.
+ * - `flow` — duplicated from the `type` prefix for cheap field-based filtering by analytics
+ *   integrations that don't want to string-parse.
+ * - `tier` — duplicated from per-variant convention for filterable inspection.
+ * - `timestamp` — `Date.now()` at emit; wall-clock, not `performance.now()`, because
+ *   consumers want it for logging/funnels.
+ * - `flowId` — session correlation id. Minted at `<flow>.opened`, retired after the terminal
+ *   event (`*.settlement.succeeded` / `*.settlement.failed` / `*.cancelled`, or `activity.closed`
+ *   for the read-only activity surface which has no settlement). Always `string` for `flow:*`
+ *   and `ui:*` events; `null` for `kit:*` events (which have no flow context to belong to).
+ * - `payload` — event-specific data, always an object even when single-field, so future
+ *   fields can be added non-breakingly.
+ * - `metadata` — consumer-attached, snapshotted at `<flow>.opened` and frozen for the
+ *   session. Always present (empty object if the consumer didn't supply any). `Record<string,
+ *   unknown>` — the kit does not validate, normalise, or enforce a schema.
+ *
+ * # What's intentionally NOT in the envelope
+ *
+ * - No `id` per-event uuid — `flowId + type + timestamp` is sufficient correlation.
+ * - No `preventDefault` / `stopPropagation` — events are read-only notifications.
+ * - No `version` field — versioning happens through the union, not at runtime.
+ * - No `source: "user" | "system"` distinction beyond `tier` — adding finer grain invites
+ *   bikeshed without paying for itself.
+ */
+/** Flow identifier — one per orchestrator family, plus `"kit"` for flow-less provider events. */
+type StridgeEventFlow = "deposit" | "withdraw" | "activity" | "kit";
+/** Delivery tier — see envelope JSDoc for the rule. */
+type StridgeEventTier = "flow" | "ui";
+/**
+ * Generic envelope every event variant extends. Concrete variants narrow the four type
+ * parameters so `e.type === "..."` discrimination narrows `flow`, `tier`, and `payload`
+ * in lockstep.
+ */
+interface StridgeEventBase<TType extends string, TFlow extends StridgeEventFlow, TTier extends StridgeEventTier, TPayload> {
+  /** Stable string discriminator. See the naming pattern in this file's top-of-file JSDoc. */
+  type: TType;
+  /** Originating flow. Always derivable from the `type` prefix; duplicated for cheap field-based filtering. */
+  flow: TFlow;
+  /** Delivery tier. */
+  tier: TTier;
+  /** Wall-clock millisecond timestamp at emit. */
+  timestamp: number;
+  /**
+   * Session correlation id. `string` for flow-scoped events, `null` for `kit:*` events
+   * (which have no flow context to belong to).
+   */
+  flowId: TFlow extends "kit" ? null : string;
+  /** Event-specific payload. Always an object even when single-field. */
+  payload: TPayload;
+  /**
+   * Consumer-attached metadata, snapshotted at `<flow>.opened`, frozen for the session.
+   * Empty object when the consumer didn't supply any. Consumer-typed at the consumption
+   * site — the kit does not validate or normalise.
+   */
+  metadata: Record<string, unknown>;
+}
+/**
+ * Stable taxonomy of failure codes carried by every `*.failed` event. Constrained enum (not
+ * free string) because consumers writing `switch(code)` need exhaustiveness and analytics
+ * platforms need bounded cardinality.
+ *
+ * Every internal failure path must map to one of these. Add new codes here when a new
+ * failure category genuinely appears — don't widen the union with overlapping codes.
+ */
+type FailureCode = /** Transport-level fetch failure, DNS error, browser offline. */"network" /** Operation exceeded its deadline before producing a result. */ | "timeout" /** Backend returned 429 / equivalent rate-limit signal. */ | "rate_limited" /** Gateway key invalid, scope mismatch, or session expired. */ | "unauthorized" /** Requested amount exceeds available balance. */ | "insufficient_funds" /** Backend rejected the payload as malformed (validation failure). */ | "invalid_input" /** Quote went stale between request and submit. */ | "quote_expired" /** On-chain transaction reverted. */ | "tx_reverted" /** Transaction replaced or dropped from the mempool before inclusion. */ | "tx_dropped" /** Backend couldn't correlate a settlement to the submitted transaction. */ | "settlement_lost" /** Catch-all for anything else; consumers should treat as opaque. */ | "internal";
+/**
+ * Shape carried by every `*.failed` event in the bus. Common base lets generic error handlers
+ * write `analytics.track("error", e.payload.code, e.payload.reason)` once and have it work
+ * across every flow and every failure point.
+ *
+ * Per-event extensions (e.g. `SettlementFailurePayload`) extend this with richer fields when
+ * the failure has additional structure worth surfacing.
+ *
+ * **`.declined` (user refused a wallet prompt) and `.cancelled` (flow interrupted by close /
+ * AbortSignal) are NOT `.failed`** — they have their own event names with their own (often
+ * empty) payloads. Conflating them would let analytics count user choices as errors.
+ */
+interface FailurePayloadBase {
+  /**
+   * Stable taxonomy code. Drives consumer logic: retry decisions, custom messaging,
+   * error-grouping in analytics dashboards.
+   */
+  code: FailureCode;
+  /**
+   * Human-readable reason, already localised by the kit. Safe to render directly to users.
+   * Consumers who want raw keys for their own messaging branch on {@link code} instead.
+   */
+  reason: string;
+  /**
+   * Whether retrying the same operation could plausibly succeed. `true` for transient
+   * failures (`network`, `timeout`, `rate_limited`); `false` for permanent ones
+   * (`unauthorized`, `invalid_input`, `tx_reverted`).
+   */
+  retryable: boolean;
+  /**
+   * Raw cause for debugging only — typically the underlying `Error`, fetch `Response`, or
+   * wallet-provider error object. Never displayed; safe to log. Consumers must not depend
+   * on its shape.
+   */
+  cause?: unknown;
+}
+//#endregion
+export { FailureCode, FailurePayloadBase, StridgeEventBase, StridgeEventFlow, StridgeEventTier };

package/dist/events/types/index.d.ts

@@ -0,0 +1,32 @@
+import { FailureCode, FailurePayloadBase, StridgeEventBase, StridgeEventFlow, StridgeEventTier } from "./envelope.js";
+import { ActivityClosedEvent, ActivityEvent, ActivityOpenedEvent, ActivitySelectionVia, ActivitySettlementSelectedEvent, ActivityStepChangedEvent, ActivityUiEvent } from "./activity.js";
+import { DepositAmountChangedEvent, DepositAmountSubmittedEvent, DepositAssetClickedEvent, DepositBackClickedEvent, DepositCancelPhase, DepositCancelledEvent, DepositClosedEvent, DepositConfirmClickedEvent, DepositEvent, DepositFlowEvent, DepositMaxClickedEvent, DepositMethodClickedEvent, DepositOpenedEvent, DepositQuoteExpiredEvent, DepositQuoteFailedEvent, DepositQuoteRequestInput, DepositQuoteRequestedEvent, DepositQuoteResolvedEvent, DepositSettlementFailedEvent, DepositSettlementFailurePayload, DepositSettlementProgressedEvent, DepositSettlementResumedEvent, DepositSettlementSucceededEvent, DepositStepChangedEvent, DepositSubmissionBroadcastEvent, DepositSubmissionConfirmedEvent, DepositSubmissionDeclinedEvent, DepositSubmissionFailedEvent, DepositTransferAddressCopiedEvent, DepositTransferChainChangedEvent, DepositTransferTokenChangedEvent, DepositUiEvent } from "./deposit.js";
+import { KitEvent, KitSupportClickedEvent, KitTermsClickedEvent } from "./kit.js";
+import { WithdrawAmountChangedEvent, WithdrawBreakdownClickedEvent, WithdrawCancelPhase, WithdrawCancelledEvent, WithdrawClosedEvent, WithdrawEvent, WithdrawFlowEvent, WithdrawMaxClickedEvent, WithdrawOpenedEvent, WithdrawQuoteExpiredEvent, WithdrawQuoteFailedEvent, WithdrawQuoteRequestedEvent, WithdrawQuoteResolvedEvent, WithdrawReceiveChainChangedEvent, WithdrawReceiveTokenChangedEvent, WithdrawRecipientChangedEvent, WithdrawSettlementFailedEvent, WithdrawSettlementFailurePayload, WithdrawSettlementProgressedEvent, WithdrawSettlementSucceededEvent, WithdrawStepChangedEvent, WithdrawSubmissionBroadcastEvent, WithdrawSubmissionConfirmedEvent, WithdrawSubmissionDeclinedEvent, WithdrawSubmissionFailedEvent, WithdrawSubmitClickedEvent, WithdrawUiEvent } from "./withdraw.js";
+
+//#region src/events/types/index.d.ts
+/**
+ * Every `flow:*` event across all flows. Headless-safe — this is what
+ * `useStridgeFlowEvents` narrows its handler to. Does not include any `ui:*` or `kit:*`
+ * events; consumers who only render the dialog (no widgets, no provider affordances) can
+ * subscribe to this union and never see a UI-noise event in their autocomplete.
+ */
+type FlowEvent = DepositFlowEvent | WithdrawFlowEvent;
+/**
+ * Every `ui:*` event across all flows, plus every `kit:*` provider-scoped event (kit
+ * affordances are user-driven, so they share the `ui` tier today even though they don't
+ * belong to a deposit/withdraw flow). Does NOT include `flow:*` events — for the firehose
+ * union, use {@link StridgeEvent}.
+ */
+type UiEvent = DepositUiEvent | WithdrawUiEvent | ActivityUiEvent | KitEvent;
+/**
+ * Firehose union — every event the kit ever emits. Equivalent to `FlowEvent | UiEvent`.
+ * What `useStridgeEvents` hands to its handler.
+ */
+type StridgeEvent = FlowEvent | UiEvent;
+/** Convenience: every distinct `type` literal across the full union. */
+type StridgeEventType = StridgeEvent["type"];
+type FlowEventType = FlowEvent["type"];
+type UiEventType = UiEvent["type"];
+//#endregion
+export { FlowEvent, FlowEventType, StridgeEvent, StridgeEventType, UiEvent, UiEventType };

package/dist/events/types/kit.d.ts

@@ -0,0 +1,23 @@
+import { SupportOpenContext } from "../../shared/support/types.js";
+import { TermsSelectContext } from "../../shared/terms/types.js";
+import { StridgeEventBase } from "./envelope.js";
+//#region src/events/types/kit.d.ts
+/**
+ * User clicked the support entry point (the "Get help" link / button). Fires regardless of
+ * whether the consumer provided a custom `support.onOpen` handler — the bus event is an
+ * observation channel for analytics, the prop is a behaviour-override contract. Both coexist.
+ */
+type KitSupportClickedEvent = StridgeEventBase<"kit.support.clicked", "kit", "ui", {
+  context: SupportOpenContext;
+}>;
+/**
+ * User clicked a terms link. Fires regardless of whether the consumer provided a custom
+ * `terms.onSelect` handler.
+ */
+type KitTermsClickedEvent = StridgeEventBase<"kit.terms.clicked", "kit", "ui", {
+  context: TermsSelectContext;
+}>;
+/** Union of every `kit.*` event. */
+type KitEvent = KitSupportClickedEvent | KitTermsClickedEvent;
+//#endregion
+export { KitEvent, KitSupportClickedEvent, KitTermsClickedEvent };

package/dist/events/types/withdraw.d.ts

@@ -0,0 +1,150 @@
+import { SettlementFailureKind, TxRef } from "../../shared/driver/types.js";
+import { ReceiveChainPayload, ReceiveTokenOptionPayload, WithdrawalQuotePayload, WithdrawalSettlementPendingPayload, WithdrawalSettlementSuccessPayload } from "../../flows/withdraw/driver/payloads.js";
+import { PrepareWithdrawalInput, RequestWithdrawalQuoteInput } from "../../flows/withdraw/driver/types.js";
+import { FailurePayloadBase, StridgeEventBase } from "./envelope.js";
+import { WithdrawStateName } from "../../flows/withdraw/orchestrator/types.js";
+
+//#region src/events/types/withdraw.d.ts
+/**
+ * Phase the withdraw flow was in when it was cancelled. Mirrors {@link DepositCancelPhase}
+ * for symmetry; same set of values.
+ */
+type WithdrawCancelPhase = "quoting" | "confirming" | "submitting" | "processing" | "unknown";
+/**
+ * Settlement failure variant — extends the base with settlement-specific structure.
+ * Mirrors {@link DepositSettlementFailurePayload}.
+ */
+interface WithdrawSettlementFailurePayload extends FailurePayloadBase {
+  /**
+   * Driver-classified failure kind for downstream branching. Bounded enum so consumers can
+   * `switch (e.payload.kind)` exhaustively. The kit also escalates FSM-level failures with
+   * `kind: "unknown"` when no settlement-specific classification applies.
+   */
+  kind: SettlementFailureKind;
+  /** On-chain transaction hash, when one was surfaced before settlement failed. */
+  txHash?: TxRef;
+}
+/**
+ * Orchestrator asked the driver for a quote — fires after the 400 ms form-input debounce when
+ * the form has a complete, parseable target. Payload is the input envelope sent to the driver.
+ */
+type WithdrawQuoteRequestedEvent = StridgeEventBase<"withdraw.quote.requested", "withdraw", "flow", {
+  input: RequestWithdrawalQuoteInput;
+}>;
+/**
+ * Driver returned a successful quote. Payload is the formatted quote entity ready for
+ * display. Subsequent form changes will trigger a new `withdraw.quote.requested`.
+ */
+type WithdrawQuoteResolvedEvent = StridgeEventBase<"withdraw.quote.resolved", "withdraw", "flow", {
+  quote: WithdrawalQuotePayload;
+}>;
+/** Quote fetch failed. Standard {@link FailurePayloadBase} payload — same shape as deposit. */
+type WithdrawQuoteFailedEvent = StridgeEventBase<"withdraw.quote.failed", "withdraw", "flow", FailurePayloadBase>;
+/**
+ * Active quote went stale before submit and the orchestrator regenerated it. Empty payload;
+ * the next `withdraw.quote.resolved` carries the replacement.
+ */
+type WithdrawQuoteExpiredEvent = StridgeEventBase<"withdraw.quote.expired", "withdraw", "flow", Record<string, never>>;
+/**
+ * Host signaled (via `actions.beginProcessing(tx)` or `actions.setTxHash(tx)` inside
+ * `WithdrawSubmitCallback`) that the withdraw transaction has been broadcast. Orchestrator
+ * has transitioned into `inProgress`; settlement polling has started.
+ */
+type WithdrawSubmissionBroadcastEvent = StridgeEventBase<"withdraw.submission.broadcast", "withdraw", "flow", {
+  input: PrepareWithdrawalInput;
+  tx: TxRef;
+}>;
+/**
+ * Host signaled user-rejection — either explicitly via `actions.decline()` or implicitly by
+ * throwing a wallet-rejection-shaped error from `onSubmit`. Distinct from
+ * {@link WithdrawSubmissionFailedEvent}: declining is a user choice, not an error.
+ */
+type WithdrawSubmissionDeclinedEvent = StridgeEventBase<"withdraw.submission.declined", "withdraw", "flow", Record<string, never>>;
+/**
+ * Host signaled a non-rejection submission failure (via `actions.fail(failure)` or by
+ * throwing a non-rejection error from `onSubmit`). Standard {@link FailurePayloadBase}.
+ */
+type WithdrawSubmissionFailedEvent = StridgeEventBase<"withdraw.submission.failed", "withdraw", "flow", FailurePayloadBase>;
+/** Settlement entity emitted a progressive pending update. Fires once per update. */
+type WithdrawSettlementProgressedEvent = StridgeEventBase<"withdraw.settlement.progressed", "withdraw", "flow", {
+  settlement: WithdrawalSettlementPendingPayload;
+}>;
+/** Terminal success — settlement entity reached `ready{kind: "succeeded"}`. Retires the `flowId`. */
+type WithdrawSettlementSucceededEvent = StridgeEventBase<"withdraw.settlement.succeeded", "withdraw", "flow", {
+  settlement: WithdrawalSettlementSuccessPayload;
+}>;
+/**
+ * Terminal failure — settlement entity reached `ready{kind: "failed"}` or an FSM-level
+ * failure escalated to the global error arm. Extends {@link FailurePayloadBase} with
+ * settlement-specific fields.
+ */
+type WithdrawSettlementFailedEvent = StridgeEventBase<"withdraw.settlement.failed", "withdraw", "flow", WithdrawSettlementFailurePayload>;
+/**
+ * Flow ended before reaching a terminal state. `payload.phase` indicates where in the
+ * lifecycle cancellation happened. Mirrors `deposit.cancelled`.
+ */
+type WithdrawCancelledEvent = StridgeEventBase<"withdraw.cancelled", "withdraw", "flow", {
+  phase: WithdrawCancelPhase;
+}>;
+/** Union of every `withdraw.*` `flow:*` event. */
+type WithdrawFlowEvent = WithdrawQuoteRequestedEvent | WithdrawQuoteResolvedEvent | WithdrawQuoteFailedEvent | WithdrawQuoteExpiredEvent | WithdrawSubmissionBroadcastEvent | WithdrawSubmissionDeclinedEvent | WithdrawSubmissionFailedEvent | WithdrawSettlementProgressedEvent | WithdrawSettlementSucceededEvent | WithdrawSettlementFailedEvent | WithdrawCancelledEvent;
+/** Dialog transitioned from `closed` to any open step. Mints the `flowId` and snapshots `metadata`. */
+type WithdrawOpenedEvent = StridgeEventBase<"withdraw.opened", "withdraw", "ui", Record<string, never>>;
+/** Dialog returned to `closed`. `payload.atStep` is the step the dialog was on at close time. */
+type WithdrawClosedEvent = StridgeEventBase<"withdraw.closed", "withdraw", "ui", {
+  atStep: WithdrawStateName;
+}>;
+/** Dialog step transitioned. Same-step `ctx` changes don't fire this — they surface via `flow:*`. */
+type WithdrawStepChangedEvent = StridgeEventBase<"withdraw.step.changed", "withdraw", "ui", {
+  from: WithdrawStateName;
+  to: WithdrawStateName;
+}>;
+/**
+ * User typed in the recipient field. Fires per keystroke (no debounce); `payload.value` is the
+ * literal input string.
+ */
+type WithdrawRecipientChangedEvent = StridgeEventBase<"withdraw.recipient.changed", "withdraw", "ui", {
+  value: string;
+}>;
+/**
+ * User typed in the amount field. Fires per keystroke; `payload.raw` is the literal input
+ * string, `payload.numeric` is the parsed value (or `null` when empty / unparseable). Mirrors
+ * {@link DepositAmountChangedEvent}.
+ */
+type WithdrawAmountChangedEvent = StridgeEventBase<"withdraw.amount.changed", "withdraw", "ui", {
+  raw: string;
+  numeric: number | null;
+}>;
+/** User clicked the Max pill in the amount field. Empty payload — the amount is reactive form state. */
+type WithdrawMaxClickedEvent = StridgeEventBase<"withdraw.max.clicked", "withdraw", "ui", Record<string, never>>;
+/** User picked a different receive token in the form. */
+type WithdrawReceiveTokenChangedEvent = StridgeEventBase<"withdraw.receive.token.changed", "withdraw", "ui", {
+  token: ReceiveTokenOptionPayload;
+}>;
+/** User picked a different receive chain in the form. */
+type WithdrawReceiveChainChangedEvent = StridgeEventBase<"withdraw.receive.chain.changed", "withdraw", "ui", {
+  chain: ReceiveChainPayload;
+}>;
+/**
+ * User clicked the submit button on the form. This is the UI signal; the FSM commitment is
+ * carried by {@link WithdrawSubmissionConfirmedEvent} immediately after.
+ */
+type WithdrawSubmitClickedEvent = StridgeEventBase<"withdraw.submit.clicked", "withdraw", "ui", Record<string, never>>;
+/**
+ * Form submission triggered the orchestrator transition to `submitting`. Fires just before
+ * the host's `WithdrawSubmitCallback` runs.
+ */
+type WithdrawSubmissionConfirmedEvent = StridgeEventBase<"withdraw.submission.confirmed", "withdraw", "ui", Record<string, never>>;
+/**
+ * User clicked the breakdown card header to toggle it. `payload.open` reflects the new state.
+ * Deposit has no symmetric event — the deposit flow doesn't surface a breakdown card today.
+ */
+type WithdrawBreakdownClickedEvent = StridgeEventBase<"withdraw.breakdown.clicked", "withdraw", "ui", {
+  open: boolean;
+}>;
+/** Union of every `withdraw.*` `ui:*` event. */
+type WithdrawUiEvent = WithdrawOpenedEvent | WithdrawClosedEvent | WithdrawStepChangedEvent | WithdrawRecipientChangedEvent | WithdrawAmountChangedEvent | WithdrawMaxClickedEvent | WithdrawReceiveTokenChangedEvent | WithdrawReceiveChainChangedEvent | WithdrawSubmitClickedEvent | WithdrawSubmissionConfirmedEvent | WithdrawBreakdownClickedEvent;
+/** Union of every `withdraw.*` event regardless of tier. */
+type WithdrawEvent = WithdrawFlowEvent | WithdrawUiEvent;
+//#endregion
+export { WithdrawAmountChangedEvent, WithdrawBreakdownClickedEvent, WithdrawCancelPhase, WithdrawCancelledEvent, WithdrawClosedEvent, WithdrawEvent, WithdrawFlowEvent, WithdrawMaxClickedEvent, WithdrawOpenedEvent, WithdrawQuoteExpiredEvent, WithdrawQuoteFailedEvent, WithdrawQuoteRequestedEvent, WithdrawQuoteResolvedEvent, WithdrawReceiveChainChangedEvent, WithdrawReceiveTokenChangedEvent, WithdrawRecipientChangedEvent, WithdrawSettlementFailedEvent, WithdrawSettlementFailurePayload, WithdrawSettlementProgressedEvent, WithdrawSettlementSucceededEvent, WithdrawStepChangedEvent, WithdrawSubmissionBroadcastEvent, WithdrawSubmissionConfirmedEvent, WithdrawSubmissionDeclinedEvent, WithdrawSubmissionFailedEvent, WithdrawSubmitClickedEvent, WithdrawUiEvent };

package/dist/flows/activity/compound/ActivityFlow.d.ts

@@ -0,0 +1,46 @@
+import { ActivityStateName } from "../orchestrator/types.js";
+import { ActivityBoundary, Props } from "./components/Boundary.js";
+import { ActivitySteps, ActivityStepsProps } from "./components/Steps.js";
+import { ReactNode } from "react";
+
+//#region src/flows/activity/compound/ActivityFlow.d.ts
+interface ActivityFlowStepProps {
+  /** Matches against the standalone activity FSM's effective state name. */
+  name: ActivityStateName;
+  children: ReactNode;
+}
+/**
+ * Flow-coupled compound namespace for the standalone activity surface. Mirrors the
+ * `Deposit.*` / `Withdraw.*` shapes — parts that consume the standalone activity controller
+ * live here. The flow-agnostic presentation primitives (`Activity.Header`, `Activity.List`,
+ * `Activity.Row`, etc.) stay on the shared `Activity` namespace.
+ *
+ * Parts:
+ * - {@link ActivityFlow.Boundary} — error-boundary wired to `useActivity().close()`.
+ * - {@link ActivityFlow.Steps} — slot router reading `useActivityEffectiveState()`.
+ * - {@link ActivityFlow.Step} — declarative slot consumed by `ActivityFlow.Steps`.
+ *
+ * No `Guards` part — activity has no wallet-required / bootstrap-fatal cascade.
+ */
+declare namespace ActivityFlow {
+  type BoundaryProps = Props;
+  type StepsProps = ActivityStepsProps;
+  type StepProps = ActivityFlowStepProps;
+  /**
+   * Error-boundary part. Wires the kit's `GatewayKitBoundary` with activity-flow recovery —
+   * `onReset` calls `useActivity().close()` internally; `onError` is host-supplied.
+   */
+  const Boundary: typeof ActivityBoundary;
+  /**
+   * Slot-routing parent. Reads the activity FSM's effective state and renders only the
+   * matching `<ActivityFlow.Step>` child.
+   */
+  const Steps: typeof ActivitySteps;
+  /**
+   * Slot consumed by {@link ActivityFlow.Steps}. `name` is the FSM state to match; the
+   * matched step's `children` are rendered, every other branch is dropped.
+   */
+  const Step: (props: ActivityFlowStepProps) => null;
+}
+//#endregion
+export { ActivityFlow };

package/dist/flows/activity/compound/ActivityFlow.js

@@ -0,0 +1 @@
+"use client";import{Step as e}from"../../../shared/ui/Steps/Steps.js";import"../../../shared/ui/Steps/index.js";import{ActivityBoundary as t}from"./components/Boundary.js";import{ActivitySteps as n}from"./components/Steps.js";let r;(function(r){r.Boundary=t,r.Steps=n,r.Step=e})(r||={});export{r as ActivityFlow};