@pollar/react 0.11.5 → 0.12.0-rc.2

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { pollarPaths, PollarClient, PollarClientConfig, PollarAdapters, OnStorageDegrade, WalletInfo, PollarLoginOptions, SessionsState, CosignState, PendingConfirmation, TransactionState, TxBuildBody, BuildOutcome, SubmitOutcome, SignOutcome, SendPaymentParams, StellarNetwork, WalletBalanceState, EnabledAssetsState, TrustlineOutcome, TxHistoryState, SwapVenue, SwapToken, SwapQuoteParams, SwapQuote, EarnProviderId, EarnOpportunity, EarnPositionParams, EarnPosition, EarnTxParams, PollarAdapter, PasskeyCeremony, PasskeySigner, WalletChain, CosignRequest, CosignVerification, CosignQuorumReport, CosignDevicesContent, KycStatus as KycStatus$1, RampQuote, WalletId, AuthState, KycProvider, KycStartResponse, RampDirection, RampCountry, RampQuoteRequirement, RampTxStatus, RampDepositInstructions, EnabledAssetRecord, WalletBalanceRecord, SwapProvider, DistributionRulesState, DistributionRule } from '@pollar/core';
+import { pollarPaths, PollarClient, PollarClientConfig, PollarAdapters, OnStorageDegrade, WalletInfo, CosignCustody, PollarLoginOptions, SessionsState, CosignState, RecoveryState, CustodyMigrationState, PendingConfirmation, TransactionState, TxBuildBody, BuildOutcome, SubmitOutcome, SignOutcome, SendPaymentParams, StellarNetwork, WalletBalanceState, EnabledAssetsState, TrustlineOutcome, TxHistoryState, SwapVenue, SwapToken, SwapQuoteParams, SwapQuote, EarnProviderId, EarnOpportunity, EarnPositionParams, EarnPosition, EarnTxParams, PollarAdapter, PasskeyCeremony, PasskeySigner, RecoveryPasskeyCeremony, WalletChain, CosignRequest, CosignVerification, CosignQuorumReport, CosignDevicesContent, KycStatus as KycStatus$1, RampQuote, WalletId, AuthState, KycProvider, KycStartResponse, RampDirection, RampCountry, RampQuoteRequirement, RampTxStatus, RampDepositInstructions, EnabledAssetRecord, WalletBalanceRecord, SwapProvider, DistributionRulesState, DistributionRule, RampSnapshot, RampsTransactionResponse } from '@pollar/core';
 export { AuthProviderContext, PollarAuthProvider, SessionsState } from '@pollar/core';
 import { ReactNode, CSSProperties } from 'react';
 
@@ -43,8 +43,13 @@ interface PollarContextValue {
      * creates none.
      */
     hasWallet: boolean;
-    /** Create the signed-in user's wallet; see `PollarClient.createWallet`. */
-    createWallet: () => Promise<WalletInfo>;
+    /**
+     * Create the signed-in user's wallet; see `PollarClient.createWallet`. An app
+     * whose custody mode is USER_CHOICE needs `custody`: the user's pick.
+     */
+    createWallet: (options?: {
+        custody?: CosignCustody;
+    }) => Promise<WalletInfo>;
     /**
      * `true` once the server has confirmed the session (login / refresh /
      * `/auth/session/resume`). `false` while a cold-start session is still
@@ -60,6 +65,24 @@ interface PollarContextValue {
     cosign: CosignState;
     /** Open the approval prompt of a co-signed wallet. Opens by itself when a request arrives. */
     openCosignModal: () => void;
+    /**
+     * The recovery state of the user's Turnkey wallet: null until read, or for a
+     * session without one. `recoveryLocked` is true while the wallet has no way
+     * to be recovered without this device: it signs nothing but its own setup.
+     */
+    recovery: RecoveryState | null;
+    recoveryLocked: boolean;
+    /** Read the recovery state again (after a method changed elsewhere). */
+    refreshRecovery: () => void;
+    /** Open the recovery methods modal: passkeys, email, devices, export. */
+    openRecoveryModal: () => void;
+    /**
+     * Whether the user's wallet, one Pollar custodies, has to move to this
+     * device because the app keeps its wallets in Turnkey. While `required`, the
+     * provider shows the move and nothing else; null until read.
+     */
+    custodyMigration: CustodyMigrationState | null;
+    refreshCustodyMigration: () => void;
     /** Signing calls waiting for the user under `confirmation: 'prompt'`; the provider shows the first one. */
     confirmations: PendingConfirmation[];
     appConfig: PollarConfig;
@@ -277,6 +300,15 @@ declare const browserPasskeyCeremony: PasskeyCeremony;
  * entry. The secp256r1 key never leaves the device.
  */
 declare const browserPasskeySigner: PasskeySigner;
+/**
+ * Browser passkey ceremonies for a Turnkey wallet's recovery: register a
+ * passkey as a way back in, and sign a Turnkey request with one to add a new
+ * device. rpId is the page's hostname, like the smart-wallet ceremony, so a
+ * passkey made on the app's domain recovers the wallet on that domain.
+ * `challenge` arrives base64url already: for `get()` it is what Turnkey checks
+ * (the hex SHA-256 of the request body).
+ */
+declare const browserRecoveryPasskey: RecoveryPasskeyCeremony;
 
 /**
  * The one place the widget decides whether a wallet can act on-chain, and what
@@ -318,6 +350,13 @@ interface WalletButtonTemplateProps {
      * custom template written before this existed keeps compiling.
      */
     notReadyReason?: string | null;
+    /**
+     * The wallet has no recovery method yet and signs nothing but its own setup.
+     * Shown at the top of the menu with a way to fix it. Optional for custom templates.
+     */
+    recoveryLocked?: boolean;
+    /** Open the recovery methods; the item shows only when set. */
+    onRecovery?: () => void;
     creatingAccount: boolean;
     /**
      * Signed in with no wallet yet (an app that creates wallets on demand, or
@@ -328,7 +367,13 @@ interface WalletButtonTemplateProps {
     signedIn?: boolean;
     creatingWallet?: boolean;
     createWalletError?: string | null;
-    onCreateWallet?: () => void;
+    /**
+     * The app leaves the custody to the user (USER_CHOICE): Create wallet offers
+     * co-signed and self-custody, and calls `onCreateWallet` with the pick. A
+     * self-custody wallet is created only after the user accepts its risks.
+     */
+    custodyChoice?: boolean;
+    onCreateWallet?: (custody?: CosignCustody) => void;
     onToggleOpen: () => void;
     onCreateAccount: () => void;
     onCopy: () => void;
@@ -343,7 +388,7 @@ interface WalletButtonTemplateProps {
     onLogout: () => void;
     onLogin: () => void;
 }
-declare function WalletButtonTemplate({ walletAddress, accentColor, open, copied, dropdownBg, dropdownBorder, itemColor, wrapperRef, isInProgress, showCreateAccount, notReadyReason, creatingAccount, onToggleOpen, onCreateAccount, onCopy, onWalletBalance, onTxHistory, onSend, onReceive, onSessions, onKyc, onRamp, onDistributionRules, onLogout, onLogin, signedIn, creatingWallet, createWalletError, onCreateWallet, }: WalletButtonTemplateProps): react_jsx_runtime.JSX.Element;
+declare function WalletButtonTemplate({ walletAddress, accentColor, open, copied, dropdownBg, dropdownBorder, itemColor, wrapperRef, isInProgress, showCreateAccount, notReadyReason, recoveryLocked, onRecovery, creatingAccount, onToggleOpen, onCreateAccount, onCopy, onWalletBalance, onTxHistory, onSend, onReceive, onSessions, onKyc, onRamp, onDistributionRules, onLogout, onLogin, signedIn, creatingWallet, createWalletError, custodyChoice, onCreateWallet, }: WalletButtonTemplateProps): react_jsx_runtime.JSX.Element;
 
 /**
  * The chain a record lives on, with the legacy shape folded in: sessions and
@@ -418,7 +463,7 @@ interface UseCosignResult {
     reject: (request: CosignRequest) => Promise<CosignRequest>;
     /** The verification a UI can show before the user decides. */
     verify: (request: CosignRequest) => Promise<CosignVerification>;
-    /** Read the sub-organization from Turnkey with the device key and record whether it is the promised 2-of-2. */
+    /** Read the sub-organization from Turnkey with the device key and record whether it is the quorum its custody promises. */
     inspectQuorum: () => Promise<CosignQuorumReport>;
     /** The user's enrolled devices and the quorum state as sdk-api records it. */
     devices: () => Promise<CosignDevicesContent>;
@@ -426,6 +471,8 @@ interface UseCosignResult {
     revokeDevice: (deviceId: string, options?: {
         force?: boolean;
     }) => Promise<CosignDevicesContent>;
+    /** Move the wallet between co-signed and self-custody; only an app in USER_CHOICE custody allows it. */
+    switchCustody: (to: CosignCustody) => Promise<CosignQuorumReport>;
 }
 /**
  * The user's side of a Turnkey co-signed wallet, for an app that renders its
@@ -574,6 +621,18 @@ interface CosignModalProps {
  */
 declare function CosignModal({ onClose }: CosignModalProps): react_jsx_runtime.JSX.Element;
 
+interface RecoveryModalProps {
+    onClose: () => void;
+}
+/**
+ * The recovery methods of a Turnkey wallet: add and remove passkeys, confirm
+ * an email, approve another device, export the recovery phrase, and, on a
+ * device that is not part of the wallet, get back in. Until one method exists
+ * the wallet signs nothing but its own setup, so this is also where a locked
+ * wallet sends the user.
+ */
+declare function RecoveryModal({ onClose }: RecoveryModalProps): react_jsx_runtime.JSX.Element;
+
 interface DistributionRulesModalProps {
     onClose: () => void;
 }
@@ -704,7 +763,7 @@ interface RampFieldSpec {
     key: string;
     label: string;
     type: 'text' | 'email' | 'tel' | 'select';
-    bankType?: 'CLABE' | 'PIX' | 'PSE' | 'ACH' | 'BREB';
+    bankType?: string;
     /** For `type: 'select'` - dropdown choices (e.g. Stereum's Bolivian banks). */
     options?: {
         value: string;
@@ -725,6 +784,8 @@ interface RampFieldSpec {
     hint?: string;
 }
 interface RampWidgetTemplateProps {
+    workflowContent?: React.ReactNode;
+    routeSelector?: React.ReactNode;
     theme: string;
     accentColor: string;
     /** Per-app modal chrome overrides (background, card + button radius). */
@@ -786,6 +847,14 @@ interface RampWidgetTemplateProps {
     depositInstructions: RampDepositInstructions | null;
     canComplete: boolean;
     completing: boolean;
+    savedRamps?: Array<{
+        txId: string;
+        provider: string;
+    }>;
+    onResumeRamp?: (id: string) => void;
+    onDismissRamp?: (id: string) => void;
+    onDismissCurrentRamp?: (() => void) | undefined;
+    onExploreRoutes?: (() => void) | undefined;
     errorMsg: string | null;
     /** Neutral guidance on the route list, e.g. after identity verification sent the user back to it. */
     noticeMsg?: string | null;
@@ -807,7 +876,7 @@ interface RampWidgetTemplateProps {
     onRefresh: () => void;
     onClose: () => void;
 }
-declare function RampWidgetTemplate({ theme, accentColor, styleOverrides, step, flowSteps, flowStepIndex, startingQuoteId, direction, amount, currency, country, requiredFields, fieldValues, countries, countriesLoading, refreshing, quotes, kycRequired, isLoading, provider, txStatus, kycUrl, tosUrl, kycBlocking, onboardingStatus, kycJustApproved, stellarTxHash, txHash, txChain, explorerUrl, fundsInTransit, retrying, onRetryTransit, depositInstructions, canComplete, completing, errorMsg, noticeMsg, onDirectionChange, onAmountChange, onFieldChange, onCountryChange, onFindRoute, onSelectQuote, onVerifyRoute, onContactContinue, onOpenKyc, onOpenTos, onCompleteWithdraw, onBack, onRetry, onRefresh, onClose, }: RampWidgetTemplateProps): react_jsx_runtime.JSX.Element;
+declare function RampWidgetTemplate({ workflowContent, routeSelector, theme, accentColor, styleOverrides, step, flowSteps, flowStepIndex, startingQuoteId, direction, amount, currency, country, requiredFields, fieldValues, countries, countriesLoading, refreshing, quotes, kycRequired, isLoading, provider, txStatus, kycUrl, tosUrl, kycBlocking, onboardingStatus, kycJustApproved, stellarTxHash, txHash, txChain, explorerUrl, fundsInTransit, retrying, onRetryTransit, depositInstructions, canComplete, completing, savedRamps, onResumeRamp, onDismissRamp, onDismissCurrentRamp, onExploreRoutes, errorMsg, noticeMsg, onDirectionChange, onAmountChange, onFieldChange, onCountryChange, onFindRoute, onSelectQuote, onVerifyRoute, onContactContinue, onOpenKyc, onOpenTos, onCompleteWithdraw, onBack, onRetry, onRefresh, onClose, }: RampWidgetTemplateProps): react_jsx_runtime.JSX.Element;
 
 interface TransactionModalTemplateProps {
     theme: string;
@@ -1070,10 +1139,17 @@ interface ReceiveModalTemplateProps {
      * custom template written before this existed keeps compiling.
      */
     notReadyReason?: string | null;
+    /**
+     * The wallet has no way to be recovered without this device yet. The address
+     * stays hidden until the user adds one, so nobody is handed an address whose
+     * funds a lost phone would take with it. Optional for custom templates.
+     */
+    recoveryLocked?: boolean;
+    onSetupRecovery?: () => void;
     onCopy: () => void;
     onClose: () => void;
 }
-declare function ReceiveModalTemplate({ theme, accentColor, styleOverrides, walletAddress, chains, selectedChain, onSelectChain, copied, notReadyReason, onCopy, onClose, }: ReceiveModalTemplateProps): react_jsx_runtime.JSX.Element;
+declare function ReceiveModalTemplate({ theme, accentColor, styleOverrides, walletAddress, chains, selectedChain, onSelectChain, copied, notReadyReason, recoveryLocked, onSetupRecovery, onCopy, onClose, }: ReceiveModalTemplateProps): react_jsx_runtime.JSX.Element;
 
 interface SessionsModalTemplateProps {
     theme: string;
@@ -1117,6 +1193,78 @@ interface CosignModalTemplateProps {
 }
 declare function CosignModalTemplate({ theme, accentColor, styleOverrides, pending, current, verification, busy, error, approveBlocked, lastResolved, explorerUrl, onSelect, onApprove, onReject, onClose, }: CosignModalTemplateProps): react_jsx_runtime.JSX.Element;
 
+interface CustodyMigrationModalProps {
+    state: CustodyMigrationState;
+    /** The wallets moved: the provider reads their state again and asks for a recovery method. */
+    onMoved: () => void;
+    /** A blocked wallet waits for what is pending; the provider stops asking until the next session. */
+    onLater: () => void;
+}
+declare function CustodyMigrationModal({ state, onMoved, onLater }: CustodyMigrationModalProps): react_jsx_runtime.JSX.Element;
+
+interface CustodyMigrationModalTemplateProps {
+    theme: string;
+    accentColor: string;
+    styleOverrides?: ModalStyleOverrides;
+    state: CustodyMigrationState;
+    busy: boolean;
+    error: string | null;
+    /** What still points at a wallet that cannot move yet (an open ramp order, a transaction in flight). */
+    blockedReasons: string[] | null;
+    onMove: (custody?: CosignCustody) => void;
+    /** Only offered while a wallet is blocked: the move waits for what is pending. */
+    onLater: () => void;
+    onLogout: () => void;
+}
+/**
+ * The move of the wallets Pollar custodies to ones the user's device signs for.
+ * It cannot be put off: the app's wallets live in Turnkey now, so the only ways
+ * out are moving or logging out, unless something still pending holds a
+ * wallet back.
+ */
+declare function CustodyMigrationModalTemplate(p: CustodyMigrationModalTemplateProps): react_jsx_runtime.JSX.Element;
+
+type RecoveryView = 'overview' | 'email' | 'export' | 'recover-email';
+interface RecoveryModalTemplateProps {
+    theme: string;
+    accentColor: string;
+    styleOverrides?: ModalStyleOverrides;
+    /** Null while the first read is in flight. */
+    state: RecoveryState | null;
+    devices: CosignDevicesContent | null;
+    thisDeviceKey: string | null;
+    /** Whether this device's key is one of the wallet's credentials. */
+    thisDeviceEnrolled: boolean;
+    /** Whether the runtime can run passkey ceremonies here. */
+    passkeyAvailable: boolean;
+    /** A self-custody wallet of an app that never asked the user to accept its risks. */
+    selfCustodyRisks: boolean;
+    view: RecoveryView;
+    /** The action in flight, by key, for its button's spinner. */
+    busy: string | null;
+    error: string | null;
+    notice: string | null;
+    emailDraft: string;
+    codeSent: boolean;
+    /** The recovery phrase, once exported. */
+    phrase: string | null;
+    onView: (view: RecoveryView) => void;
+    onEmailDraft: (email: string) => void;
+    onAddPasskey: () => void;
+    onRemovePasskey: (authenticatorId: string) => void;
+    onSendEmailCode: () => void;
+    onConfirmEmail: (code: string) => void;
+    onApproveDevice: (enrollmentId: string) => void;
+    onRejectDevice: (enrollmentId: string) => void;
+    onRequestEnrollment: () => void;
+    onRecoverWithPasskey: () => void;
+    onSendRecoveryCode: () => void;
+    onRecoverWithCode: (code: string) => void;
+    onExport: () => void;
+    onClose: () => void;
+}
+declare function RecoveryModalTemplate(p: RecoveryModalTemplateProps): react_jsx_runtime.JSX.Element;
+
 interface DistributionRulesModalTemplateProps {
     theme: string;
     accentColor: string;
@@ -1132,4 +1280,11 @@ interface DistributionRulesModalTemplateProps {
 }
 declare function DistributionRulesModalTemplate({ theme, accentColor, styleOverrides, state, claimingId, claimErrors, claimedIds, onRefresh, onClaim, onClose, }: DistributionRulesModalTemplateProps): react_jsx_runtime.JSX.Element;
 
-export { type AuthModalProps, CardModal, ChainSelect, type ChainSelectProps, CosignModal, CosignModalTemplate, type CosignModalTemplateProps, type CustomTrustlineModalTemplateProps, DistributionRulesModal, DistributionRulesModalTemplate, EarnModal, EnabledAssetsModal, EnabledAssetsModalTemplate, type EnabledAssetsModalTemplateProps, KycModal, KycModalTemplate, KycStatus, type KycStep, type LoginButtonProps, LoginModalTemplate, type ModalChrome, type ModalStyleOverrides, type ModalVariant, type PollarConfig, PollarProvider, type PollarStyles, ProviderRegistrationModal, type RampStep, RampWidget, RampWidgetTemplate, ReceiveModal, ReceiveModalTemplate, type ReceiveModalTemplateProps, RegistryCheckModal, RequirementFormModal, RouteDisplay, type SendMemoType, SendModal, SendModalTemplate, type SendModalTemplateProps, SessionsModal, SessionsModalTemplate, type SessionsModalTemplateProps, type SwapAssetOption, SwapModal, SwapModalTemplate, type SwapModalTemplateProps, TransactionModalTemplate, type TransactionModalTemplateProps, TxHistoryModalTemplate, TxStatusView, type TxStatusViewProps, type UseChainsResult, type UseCosignResult, WalletBalanceModal, WalletBalanceModalTemplate, type WalletBalanceModalTemplateProps, WalletButton, WalletButtonTemplate, type WalletButtonTemplateProps, addressForChain, browserPasskeyCeremony, browserPasskeySigner, buildModalCssVars, chainsOf, createPollarAdapterHook, modalChrome, readableTextOn, resolveChain, useChains, useCosign, usePollar, walletNotReadyReason };
+declare function RampWorkflow({ client, snapshot, onChange, onBusyChange, }: {
+    client: PollarClient;
+    snapshot: RampSnapshot;
+    onChange: (next: RampsTransactionResponse) => void;
+    onBusyChange?: (busy: boolean) => void;
+}): react_jsx_runtime.JSX.Element;
+
+export { type AuthModalProps, CardModal, ChainSelect, type ChainSelectProps, CosignModal, CosignModalTemplate, type CosignModalTemplateProps, CustodyMigrationModal, CustodyMigrationModalTemplate, type CustodyMigrationModalTemplateProps, type CustomTrustlineModalTemplateProps, DistributionRulesModal, DistributionRulesModalTemplate, EarnModal, EnabledAssetsModal, EnabledAssetsModalTemplate, type EnabledAssetsModalTemplateProps, KycModal, KycModalTemplate, KycStatus, type KycStep, type LoginButtonProps, LoginModalTemplate, type ModalChrome, type ModalStyleOverrides, type ModalVariant, type PollarConfig, PollarProvider, type PollarStyles, ProviderRegistrationModal, type RampStep, RampWidget, RampWidgetTemplate, RampWorkflow, ReceiveModal, ReceiveModalTemplate, type ReceiveModalTemplateProps, RecoveryModal, RecoveryModalTemplate, type RecoveryModalTemplateProps, type RecoveryView, RegistryCheckModal, RequirementFormModal, RouteDisplay, type SendMemoType, SendModal, SendModalTemplate, type SendModalTemplateProps, SessionsModal, SessionsModalTemplate, type SessionsModalTemplateProps, type SwapAssetOption, SwapModal, SwapModalTemplate, type SwapModalTemplateProps, TransactionModalTemplate, type TransactionModalTemplateProps, TxHistoryModalTemplate, TxStatusView, type TxStatusViewProps, type UseChainsResult, type UseCosignResult, WalletBalanceModal, WalletBalanceModalTemplate, type WalletBalanceModalTemplateProps, WalletButton, WalletButtonTemplate, type WalletButtonTemplateProps, addressForChain, browserPasskeyCeremony, browserPasskeySigner, browserRecoveryPasskey, buildModalCssVars, chainsOf, createPollarAdapterHook, modalChrome, readableTextOn, resolveChain, useChains, useCosign, usePollar, walletNotReadyReason };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { pollarPaths, PollarClient, PollarClientConfig, PollarAdapters, OnStorageDegrade, WalletInfo, PollarLoginOptions, SessionsState, CosignState, PendingConfirmation, TransactionState, TxBuildBody, BuildOutcome, SubmitOutcome, SignOutcome, SendPaymentParams, StellarNetwork, WalletBalanceState, EnabledAssetsState, TrustlineOutcome, TxHistoryState, SwapVenue, SwapToken, SwapQuoteParams, SwapQuote, EarnProviderId, EarnOpportunity, EarnPositionParams, EarnPosition, EarnTxParams, PollarAdapter, PasskeyCeremony, PasskeySigner, WalletChain, CosignRequest, CosignVerification, CosignQuorumReport, CosignDevicesContent, KycStatus as KycStatus$1, RampQuote, WalletId, AuthState, KycProvider, KycStartResponse, RampDirection, RampCountry, RampQuoteRequirement, RampTxStatus, RampDepositInstructions, EnabledAssetRecord, WalletBalanceRecord, SwapProvider, DistributionRulesState, DistributionRule } from '@pollar/core';
+import { pollarPaths, PollarClient, PollarClientConfig, PollarAdapters, OnStorageDegrade, WalletInfo, CosignCustody, PollarLoginOptions, SessionsState, CosignState, RecoveryState, CustodyMigrationState, PendingConfirmation, TransactionState, TxBuildBody, BuildOutcome, SubmitOutcome, SignOutcome, SendPaymentParams, StellarNetwork, WalletBalanceState, EnabledAssetsState, TrustlineOutcome, TxHistoryState, SwapVenue, SwapToken, SwapQuoteParams, SwapQuote, EarnProviderId, EarnOpportunity, EarnPositionParams, EarnPosition, EarnTxParams, PollarAdapter, PasskeyCeremony, PasskeySigner, RecoveryPasskeyCeremony, WalletChain, CosignRequest, CosignVerification, CosignQuorumReport, CosignDevicesContent, KycStatus as KycStatus$1, RampQuote, WalletId, AuthState, KycProvider, KycStartResponse, RampDirection, RampCountry, RampQuoteRequirement, RampTxStatus, RampDepositInstructions, EnabledAssetRecord, WalletBalanceRecord, SwapProvider, DistributionRulesState, DistributionRule, RampSnapshot, RampsTransactionResponse } from '@pollar/core';
 export { AuthProviderContext, PollarAuthProvider, SessionsState } from '@pollar/core';
 import { ReactNode, CSSProperties } from 'react';
 
@@ -43,8 +43,13 @@ interface PollarContextValue {
      * creates none.
      */
     hasWallet: boolean;
-    /** Create the signed-in user's wallet; see `PollarClient.createWallet`. */
-    createWallet: () => Promise<WalletInfo>;
+    /**
+     * Create the signed-in user's wallet; see `PollarClient.createWallet`. An app
+     * whose custody mode is USER_CHOICE needs `custody`: the user's pick.
+     */
+    createWallet: (options?: {
+        custody?: CosignCustody;
+    }) => Promise<WalletInfo>;
     /**
      * `true` once the server has confirmed the session (login / refresh /
      * `/auth/session/resume`). `false` while a cold-start session is still
@@ -60,6 +65,24 @@ interface PollarContextValue {
     cosign: CosignState;
     /** Open the approval prompt of a co-signed wallet. Opens by itself when a request arrives. */
     openCosignModal: () => void;
+    /**
+     * The recovery state of the user's Turnkey wallet: null until read, or for a
+     * session without one. `recoveryLocked` is true while the wallet has no way
+     * to be recovered without this device: it signs nothing but its own setup.
+     */
+    recovery: RecoveryState | null;
+    recoveryLocked: boolean;
+    /** Read the recovery state again (after a method changed elsewhere). */
+    refreshRecovery: () => void;
+    /** Open the recovery methods modal: passkeys, email, devices, export. */
+    openRecoveryModal: () => void;
+    /**
+     * Whether the user's wallet, one Pollar custodies, has to move to this
+     * device because the app keeps its wallets in Turnkey. While `required`, the
+     * provider shows the move and nothing else; null until read.
+     */
+    custodyMigration: CustodyMigrationState | null;
+    refreshCustodyMigration: () => void;
     /** Signing calls waiting for the user under `confirmation: 'prompt'`; the provider shows the first one. */
     confirmations: PendingConfirmation[];
     appConfig: PollarConfig;
@@ -277,6 +300,15 @@ declare const browserPasskeyCeremony: PasskeyCeremony;
  * entry. The secp256r1 key never leaves the device.
  */
 declare const browserPasskeySigner: PasskeySigner;
+/**
+ * Browser passkey ceremonies for a Turnkey wallet's recovery: register a
+ * passkey as a way back in, and sign a Turnkey request with one to add a new
+ * device. rpId is the page's hostname, like the smart-wallet ceremony, so a
+ * passkey made on the app's domain recovers the wallet on that domain.
+ * `challenge` arrives base64url already: for `get()` it is what Turnkey checks
+ * (the hex SHA-256 of the request body).
+ */
+declare const browserRecoveryPasskey: RecoveryPasskeyCeremony;
 
 /**
  * The one place the widget decides whether a wallet can act on-chain, and what
@@ -318,6 +350,13 @@ interface WalletButtonTemplateProps {
      * custom template written before this existed keeps compiling.
      */
     notReadyReason?: string | null;
+    /**
+     * The wallet has no recovery method yet and signs nothing but its own setup.
+     * Shown at the top of the menu with a way to fix it. Optional for custom templates.
+     */
+    recoveryLocked?: boolean;
+    /** Open the recovery methods; the item shows only when set. */
+    onRecovery?: () => void;
     creatingAccount: boolean;
     /**
      * Signed in with no wallet yet (an app that creates wallets on demand, or
@@ -328,7 +367,13 @@ interface WalletButtonTemplateProps {
     signedIn?: boolean;
     creatingWallet?: boolean;
     createWalletError?: string | null;
-    onCreateWallet?: () => void;
+    /**
+     * The app leaves the custody to the user (USER_CHOICE): Create wallet offers
+     * co-signed and self-custody, and calls `onCreateWallet` with the pick. A
+     * self-custody wallet is created only after the user accepts its risks.
+     */
+    custodyChoice?: boolean;
+    onCreateWallet?: (custody?: CosignCustody) => void;
     onToggleOpen: () => void;
     onCreateAccount: () => void;
     onCopy: () => void;
@@ -343,7 +388,7 @@ interface WalletButtonTemplateProps {
     onLogout: () => void;
     onLogin: () => void;
 }
-declare function WalletButtonTemplate({ walletAddress, accentColor, open, copied, dropdownBg, dropdownBorder, itemColor, wrapperRef, isInProgress, showCreateAccount, notReadyReason, creatingAccount, onToggleOpen, onCreateAccount, onCopy, onWalletBalance, onTxHistory, onSend, onReceive, onSessions, onKyc, onRamp, onDistributionRules, onLogout, onLogin, signedIn, creatingWallet, createWalletError, onCreateWallet, }: WalletButtonTemplateProps): react_jsx_runtime.JSX.Element;
+declare function WalletButtonTemplate({ walletAddress, accentColor, open, copied, dropdownBg, dropdownBorder, itemColor, wrapperRef, isInProgress, showCreateAccount, notReadyReason, recoveryLocked, onRecovery, creatingAccount, onToggleOpen, onCreateAccount, onCopy, onWalletBalance, onTxHistory, onSend, onReceive, onSessions, onKyc, onRamp, onDistributionRules, onLogout, onLogin, signedIn, creatingWallet, createWalletError, custodyChoice, onCreateWallet, }: WalletButtonTemplateProps): react_jsx_runtime.JSX.Element;
 
 /**
  * The chain a record lives on, with the legacy shape folded in: sessions and
@@ -418,7 +463,7 @@ interface UseCosignResult {
     reject: (request: CosignRequest) => Promise<CosignRequest>;
     /** The verification a UI can show before the user decides. */
     verify: (request: CosignRequest) => Promise<CosignVerification>;
-    /** Read the sub-organization from Turnkey with the device key and record whether it is the promised 2-of-2. */
+    /** Read the sub-organization from Turnkey with the device key and record whether it is the quorum its custody promises. */
     inspectQuorum: () => Promise<CosignQuorumReport>;
     /** The user's enrolled devices and the quorum state as sdk-api records it. */
     devices: () => Promise<CosignDevicesContent>;
@@ -426,6 +471,8 @@ interface UseCosignResult {
     revokeDevice: (deviceId: string, options?: {
         force?: boolean;
     }) => Promise<CosignDevicesContent>;
+    /** Move the wallet between co-signed and self-custody; only an app in USER_CHOICE custody allows it. */
+    switchCustody: (to: CosignCustody) => Promise<CosignQuorumReport>;
 }
 /**
  * The user's side of a Turnkey co-signed wallet, for an app that renders its
@@ -574,6 +621,18 @@ interface CosignModalProps {
  */
 declare function CosignModal({ onClose }: CosignModalProps): react_jsx_runtime.JSX.Element;
 
+interface RecoveryModalProps {
+    onClose: () => void;
+}
+/**
+ * The recovery methods of a Turnkey wallet: add and remove passkeys, confirm
+ * an email, approve another device, export the recovery phrase, and, on a
+ * device that is not part of the wallet, get back in. Until one method exists
+ * the wallet signs nothing but its own setup, so this is also where a locked
+ * wallet sends the user.
+ */
+declare function RecoveryModal({ onClose }: RecoveryModalProps): react_jsx_runtime.JSX.Element;
+
 interface DistributionRulesModalProps {
     onClose: () => void;
 }
@@ -704,7 +763,7 @@ interface RampFieldSpec {
     key: string;
     label: string;
     type: 'text' | 'email' | 'tel' | 'select';
-    bankType?: 'CLABE' | 'PIX' | 'PSE' | 'ACH' | 'BREB';
+    bankType?: string;
     /** For `type: 'select'` - dropdown choices (e.g. Stereum's Bolivian banks). */
     options?: {
         value: string;
@@ -725,6 +784,8 @@ interface RampFieldSpec {
     hint?: string;
 }
 interface RampWidgetTemplateProps {
+    workflowContent?: React.ReactNode;
+    routeSelector?: React.ReactNode;
     theme: string;
     accentColor: string;
     /** Per-app modal chrome overrides (background, card + button radius). */
@@ -786,6 +847,14 @@ interface RampWidgetTemplateProps {
     depositInstructions: RampDepositInstructions | null;
     canComplete: boolean;
     completing: boolean;
+    savedRamps?: Array<{
+        txId: string;
+        provider: string;
+    }>;
+    onResumeRamp?: (id: string) => void;
+    onDismissRamp?: (id: string) => void;
+    onDismissCurrentRamp?: (() => void) | undefined;
+    onExploreRoutes?: (() => void) | undefined;
     errorMsg: string | null;
     /** Neutral guidance on the route list, e.g. after identity verification sent the user back to it. */
     noticeMsg?: string | null;
@@ -807,7 +876,7 @@ interface RampWidgetTemplateProps {
     onRefresh: () => void;
     onClose: () => void;
 }
-declare function RampWidgetTemplate({ theme, accentColor, styleOverrides, step, flowSteps, flowStepIndex, startingQuoteId, direction, amount, currency, country, requiredFields, fieldValues, countries, countriesLoading, refreshing, quotes, kycRequired, isLoading, provider, txStatus, kycUrl, tosUrl, kycBlocking, onboardingStatus, kycJustApproved, stellarTxHash, txHash, txChain, explorerUrl, fundsInTransit, retrying, onRetryTransit, depositInstructions, canComplete, completing, errorMsg, noticeMsg, onDirectionChange, onAmountChange, onFieldChange, onCountryChange, onFindRoute, onSelectQuote, onVerifyRoute, onContactContinue, onOpenKyc, onOpenTos, onCompleteWithdraw, onBack, onRetry, onRefresh, onClose, }: RampWidgetTemplateProps): react_jsx_runtime.JSX.Element;
+declare function RampWidgetTemplate({ workflowContent, routeSelector, theme, accentColor, styleOverrides, step, flowSteps, flowStepIndex, startingQuoteId, direction, amount, currency, country, requiredFields, fieldValues, countries, countriesLoading, refreshing, quotes, kycRequired, isLoading, provider, txStatus, kycUrl, tosUrl, kycBlocking, onboardingStatus, kycJustApproved, stellarTxHash, txHash, txChain, explorerUrl, fundsInTransit, retrying, onRetryTransit, depositInstructions, canComplete, completing, savedRamps, onResumeRamp, onDismissRamp, onDismissCurrentRamp, onExploreRoutes, errorMsg, noticeMsg, onDirectionChange, onAmountChange, onFieldChange, onCountryChange, onFindRoute, onSelectQuote, onVerifyRoute, onContactContinue, onOpenKyc, onOpenTos, onCompleteWithdraw, onBack, onRetry, onRefresh, onClose, }: RampWidgetTemplateProps): react_jsx_runtime.JSX.Element;
 
 interface TransactionModalTemplateProps {
     theme: string;
@@ -1070,10 +1139,17 @@ interface ReceiveModalTemplateProps {
      * custom template written before this existed keeps compiling.
      */
     notReadyReason?: string | null;
+    /**
+     * The wallet has no way to be recovered without this device yet. The address
+     * stays hidden until the user adds one, so nobody is handed an address whose
+     * funds a lost phone would take with it. Optional for custom templates.
+     */
+    recoveryLocked?: boolean;
+    onSetupRecovery?: () => void;
     onCopy: () => void;
     onClose: () => void;
 }
-declare function ReceiveModalTemplate({ theme, accentColor, styleOverrides, walletAddress, chains, selectedChain, onSelectChain, copied, notReadyReason, onCopy, onClose, }: ReceiveModalTemplateProps): react_jsx_runtime.JSX.Element;
+declare function ReceiveModalTemplate({ theme, accentColor, styleOverrides, walletAddress, chains, selectedChain, onSelectChain, copied, notReadyReason, recoveryLocked, onSetupRecovery, onCopy, onClose, }: ReceiveModalTemplateProps): react_jsx_runtime.JSX.Element;
 
 interface SessionsModalTemplateProps {
     theme: string;
@@ -1117,6 +1193,78 @@ interface CosignModalTemplateProps {
 }
 declare function CosignModalTemplate({ theme, accentColor, styleOverrides, pending, current, verification, busy, error, approveBlocked, lastResolved, explorerUrl, onSelect, onApprove, onReject, onClose, }: CosignModalTemplateProps): react_jsx_runtime.JSX.Element;
 
+interface CustodyMigrationModalProps {
+    state: CustodyMigrationState;
+    /** The wallets moved: the provider reads their state again and asks for a recovery method. */
+    onMoved: () => void;
+    /** A blocked wallet waits for what is pending; the provider stops asking until the next session. */
+    onLater: () => void;
+}
+declare function CustodyMigrationModal({ state, onMoved, onLater }: CustodyMigrationModalProps): react_jsx_runtime.JSX.Element;
+
+interface CustodyMigrationModalTemplateProps {
+    theme: string;
+    accentColor: string;
+    styleOverrides?: ModalStyleOverrides;
+    state: CustodyMigrationState;
+    busy: boolean;
+    error: string | null;
+    /** What still points at a wallet that cannot move yet (an open ramp order, a transaction in flight). */
+    blockedReasons: string[] | null;
+    onMove: (custody?: CosignCustody) => void;
+    /** Only offered while a wallet is blocked: the move waits for what is pending. */
+    onLater: () => void;
+    onLogout: () => void;
+}
+/**
+ * The move of the wallets Pollar custodies to ones the user's device signs for.
+ * It cannot be put off: the app's wallets live in Turnkey now, so the only ways
+ * out are moving or logging out, unless something still pending holds a
+ * wallet back.
+ */
+declare function CustodyMigrationModalTemplate(p: CustodyMigrationModalTemplateProps): react_jsx_runtime.JSX.Element;
+
+type RecoveryView = 'overview' | 'email' | 'export' | 'recover-email';
+interface RecoveryModalTemplateProps {
+    theme: string;
+    accentColor: string;
+    styleOverrides?: ModalStyleOverrides;
+    /** Null while the first read is in flight. */
+    state: RecoveryState | null;
+    devices: CosignDevicesContent | null;
+    thisDeviceKey: string | null;
+    /** Whether this device's key is one of the wallet's credentials. */
+    thisDeviceEnrolled: boolean;
+    /** Whether the runtime can run passkey ceremonies here. */
+    passkeyAvailable: boolean;
+    /** A self-custody wallet of an app that never asked the user to accept its risks. */
+    selfCustodyRisks: boolean;
+    view: RecoveryView;
+    /** The action in flight, by key, for its button's spinner. */
+    busy: string | null;
+    error: string | null;
+    notice: string | null;
+    emailDraft: string;
+    codeSent: boolean;
+    /** The recovery phrase, once exported. */
+    phrase: string | null;
+    onView: (view: RecoveryView) => void;
+    onEmailDraft: (email: string) => void;
+    onAddPasskey: () => void;
+    onRemovePasskey: (authenticatorId: string) => void;
+    onSendEmailCode: () => void;
+    onConfirmEmail: (code: string) => void;
+    onApproveDevice: (enrollmentId: string) => void;
+    onRejectDevice: (enrollmentId: string) => void;
+    onRequestEnrollment: () => void;
+    onRecoverWithPasskey: () => void;
+    onSendRecoveryCode: () => void;
+    onRecoverWithCode: (code: string) => void;
+    onExport: () => void;
+    onClose: () => void;
+}
+declare function RecoveryModalTemplate(p: RecoveryModalTemplateProps): react_jsx_runtime.JSX.Element;
+
 interface DistributionRulesModalTemplateProps {
     theme: string;
     accentColor: string;
@@ -1132,4 +1280,11 @@ interface DistributionRulesModalTemplateProps {
 }
 declare function DistributionRulesModalTemplate({ theme, accentColor, styleOverrides, state, claimingId, claimErrors, claimedIds, onRefresh, onClaim, onClose, }: DistributionRulesModalTemplateProps): react_jsx_runtime.JSX.Element;
 
-export { type AuthModalProps, CardModal, ChainSelect, type ChainSelectProps, CosignModal, CosignModalTemplate, type CosignModalTemplateProps, type CustomTrustlineModalTemplateProps, DistributionRulesModal, DistributionRulesModalTemplate, EarnModal, EnabledAssetsModal, EnabledAssetsModalTemplate, type EnabledAssetsModalTemplateProps, KycModal, KycModalTemplate, KycStatus, type KycStep, type LoginButtonProps, LoginModalTemplate, type ModalChrome, type ModalStyleOverrides, type ModalVariant, type PollarConfig, PollarProvider, type PollarStyles, ProviderRegistrationModal, type RampStep, RampWidget, RampWidgetTemplate, ReceiveModal, ReceiveModalTemplate, type ReceiveModalTemplateProps, RegistryCheckModal, RequirementFormModal, RouteDisplay, type SendMemoType, SendModal, SendModalTemplate, type SendModalTemplateProps, SessionsModal, SessionsModalTemplate, type SessionsModalTemplateProps, type SwapAssetOption, SwapModal, SwapModalTemplate, type SwapModalTemplateProps, TransactionModalTemplate, type TransactionModalTemplateProps, TxHistoryModalTemplate, TxStatusView, type TxStatusViewProps, type UseChainsResult, type UseCosignResult, WalletBalanceModal, WalletBalanceModalTemplate, type WalletBalanceModalTemplateProps, WalletButton, WalletButtonTemplate, type WalletButtonTemplateProps, addressForChain, browserPasskeyCeremony, browserPasskeySigner, buildModalCssVars, chainsOf, createPollarAdapterHook, modalChrome, readableTextOn, resolveChain, useChains, useCosign, usePollar, walletNotReadyReason };
+declare function RampWorkflow({ client, snapshot, onChange, onBusyChange, }: {
+    client: PollarClient;
+    snapshot: RampSnapshot;
+    onChange: (next: RampsTransactionResponse) => void;
+    onBusyChange?: (busy: boolean) => void;
+}): react_jsx_runtime.JSX.Element;
+
+export { type AuthModalProps, CardModal, ChainSelect, type ChainSelectProps, CosignModal, CosignModalTemplate, type CosignModalTemplateProps, CustodyMigrationModal, CustodyMigrationModalTemplate, type CustodyMigrationModalTemplateProps, type CustomTrustlineModalTemplateProps, DistributionRulesModal, DistributionRulesModalTemplate, EarnModal, EnabledAssetsModal, EnabledAssetsModalTemplate, type EnabledAssetsModalTemplateProps, KycModal, KycModalTemplate, KycStatus, type KycStep, type LoginButtonProps, LoginModalTemplate, type ModalChrome, type ModalStyleOverrides, type ModalVariant, type PollarConfig, PollarProvider, type PollarStyles, ProviderRegistrationModal, type RampStep, RampWidget, RampWidgetTemplate, RampWorkflow, ReceiveModal, ReceiveModalTemplate, type ReceiveModalTemplateProps, RecoveryModal, RecoveryModalTemplate, type RecoveryModalTemplateProps, type RecoveryView, RegistryCheckModal, RequirementFormModal, RouteDisplay, type SendMemoType, SendModal, SendModalTemplate, type SendModalTemplateProps, SessionsModal, SessionsModalTemplate, type SessionsModalTemplateProps, type SwapAssetOption, SwapModal, SwapModalTemplate, type SwapModalTemplateProps, TransactionModalTemplate, type TransactionModalTemplateProps, TxHistoryModalTemplate, TxStatusView, type TxStatusViewProps, type UseChainsResult, type UseCosignResult, WalletBalanceModal, WalletBalanceModalTemplate, type WalletBalanceModalTemplateProps, WalletButton, WalletButtonTemplate, type WalletButtonTemplateProps, addressForChain, browserPasskeyCeremony, browserPasskeySigner, browserRecoveryPasskey, buildModalCssVars, chainsOf, createPollarAdapterHook, modalChrome, readableTextOn, resolveChain, useChains, useCosign, usePollar, walletNotReadyReason };