@openreceive/browser 0.2.4 → 0.3.0

package/dist/headless.js

@@ -6,6 +6,7 @@ import {
   OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS,
   OPENRECEIVE_CHECKOUT_ELEMENT_PARTS,
   OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS,
+  OPENRECEIVE_CHECKOUT_ELEMENT_SLOTS,
   OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME,
   OPENRECEIVE_COPY_FEEDBACK_MS,
   OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS,
@@ -23,7 +24,6 @@ import {
   buildMethodGridEntries,
   checkoutElementStyles,
   checkoutLabels,
-  checkoutRoutes,
   copyInvoice,
   createBlockExplorerUrl,
   createCheckoutActionEvent,
@@ -36,7 +36,7 @@ import {
   createCheckoutStatusModel,
   createDetailExternalLink,
   createLightningInvoiceDecodeUrl,
-  createPaymentDataEntries,
+  createMethodGridDisplay,
   createPaymentWizardController,
   createPaymentWizardModel,
   createPaymentWizardSelection,
@@ -57,9 +57,7 @@ import {
   enterCheckoutResumePath,
   escapeHtml,
   findReusableLightningInvoice,
-  findSwapGridGroup,
   formatAmountCaption,
-  formatChooseNetworkHeading,
   formatDepositAmount,
   formatFiatAmount,
   formatMsats,
@@ -69,6 +67,7 @@ import {
   getExplorerNetwork,
   getNetworkIcon,
   getPaymentMethodIcon,
+  getRouteIconPath,
   getRouteNetworkLabel,
   getSwapOptionIcon,
   getSwapRefundFormError,
@@ -82,10 +81,9 @@ import {
   networkCheckClasses,
   networkMobileRevealClasses,
   networkSummaryIconClasses,
+  normalizeSwapStartInvoice,
   openWallet,
-  optionalSafeInteger,
   orClasses,
-  overlaySwapRefundStaging,
   parseBooleanAttribute,
   parseMethodPickerKey,
   parseOptionalInteger,
@@ -96,25 +94,22 @@ import {
   paymentIconPaths,
   paymentIconUrls,
   paymentMethods,
+  postJson,
   prepareCheckout,
-  readJsonResponse,
   requestCheckout,
-  requestHeaders,
-  resolveBrowserLogger,
-  resolvePreservedNetworkSelection,
+  requestSwapRefund,
   resolveTransactionDetailRows,
-  sanitizeBrowserLogEntry,
+  resolveWizardSelection,
   selectCheckoutDisplayInvoice,
+  selectCurrentSwapInvoice,
+  startSwapRequest,
   swapAssetMatchesRoute,
   swapDepositRisk,
-  swapGroupLimitOption,
   swapOptionLimitMessage,
   swapOptionLimitSentence,
   swapPickerKey,
-  updatePaymentWizardSelection,
-  updateSelectedSwapNetworks,
-  wizardNetworkGroupIds
-} from "./chunk-GA4FMG7L.js";
+  updatePaymentWizardSelection
+} from "./chunk-NVEGYGZ5.js";
 
 // src/internal/checkout-props.ts
 var CREATE_MODE_ONLY_PROPS = [
@@ -144,201 +139,11 @@ function validateCheckoutProps(props) {
 }
 
 // src/internal/checkout-session.ts
-import { recordOrEmpty as recordOrEmpty2 } from "@openreceive/core";
-
-// src/internal/swap-http.ts
-import { nonEmptyString, recordOrEmpty } from "@openreceive/core";
-async function postJson(options) {
-  const { body } = options;
-  const routes = checkoutRoutes(options.prefix);
-  const reference = nonEmptyString(body.reference);
-  const action = nonEmptyString(body.action);
-  if (action !== void 0 && action !== "swap_quote" && action !== "refund_swap") {
-    throw new Error(`Unrecognized checkout action ${action}.`);
-  }
-  emitSwapActionLog(options.logger, "requested", body);
-  try {
-    const result = action === "swap_quote" ? await requestJson(options, routes.swapsQuote, {
-      reference,
-      pay_in_asset: body.pay_in_asset
-    }) : action === "refund_swap" ? await refundRequest(options, routes, body, reference) : await requestJson(options, routes.paymentsCheck, withoutAction(body));
-    if (action === "refund_swap") {
-      emitSwapActionLog(options.logger, "succeeded", body, swapActionResultFields(result));
-    }
-    return result;
-  } catch (error) {
-    emitSwapActionLog(options.logger, "failed", body, {
-      error_message: error instanceof Error ? error.message : String(error)
-    });
-    throw error;
-  }
-}
-function normalizeSwapStartInvoice(body) {
-  const outer = recordOrEmpty(body);
-  const swap = recordOrEmpty(outer.swap ?? body);
-  const checkout = recordOrEmpty(swap.checkout);
-  const paymentHash = nonEmptyString(swap.payment_hash ?? checkout.payment_hash);
-  if (paymentHash === void 0 || nonEmptyString(swap.provider) === void 0 || nonEmptyString(swap.pay_in_asset) === void 0 || nonEmptyString(swap.deposit_address) === void 0 || nonEmptyString(swap.deposit_amount) === void 0 || nonEmptyString(swap.provider_state) === void 0 || typeof swap.provider_expires_at !== "number") {
-    throw new Error("Swap response did not include provider instructions.");
-  }
-  const amountMsats = optionalSafeInteger(checkout.amount_msats, "amount_msats");
-  return {
-    invoice_id: paymentHash,
-    rail: "swap",
-    payment_hash: paymentHash,
-    ...amountMsats === void 0 ? {} : { amount_msats: amountMsats },
-    transaction_state: "pending",
-    workflow_state: "invoice_created",
-    expires_at: swap.provider_expires_at,
-    swap: {
-      provider: swap.provider,
-      pay_in_asset: swap.pay_in_asset,
-      deposit_address: swap.deposit_address,
-      deposit_amount: swap.deposit_amount,
-      provider_state: swap.provider_state,
-      provider_expires_at: swap.provider_expires_at,
-      ...copyOptionalSwapFields(swap)
-    }
-  };
-}
-async function startSwapRequest(options) {
-  const logBody = {
-    action: "start_swap",
-    reference: options.reference,
-    pay_in_asset: options.payInAsset
-  };
-  emitSwapActionLog(options.logger, "requested", logBody);
-  try {
-    const body = await requestJson(options, checkoutRoutes(options.prefix).swaps, {
-      reference: options.reference,
-      pay_in_asset: options.payInAsset
-    });
-    emitSwapActionLog(options.logger, "succeeded", logBody, swapActionResultFields(body));
-    return normalizeSwapStartInvoice(body);
-  } catch (error) {
-    emitSwapActionLog(options.logger, "failed", logBody, {
-      error_message: error instanceof Error ? error.message : String(error)
-    });
-    throw error;
-  }
-}
-async function requestSwapRefund(options) {
-  const payment = options.invoices.find(
-    (invoice) => invoice != null && (invoice.swap?.attempt_id ?? invoice.invoice_id) === options.attemptId
-  );
-  if (payment?.payment_hash === void 0) {
-    throw new Error("Swap refund requires the original payment hash.");
-  }
-  const body = await postJson({
-    fetch: options.fetch,
-    prefix: options.prefix,
-    ...options.logger === void 0 ? {} : { logger: options.logger },
-    ...options.headers === void 0 ? {} : { headers: options.headers },
-    body: {
-      ...options.reference === void 0 ? {} : { reference: options.reference },
-      payment_hash: payment.payment_hash,
-      action: "refund_swap",
-      attempt_id: options.attemptId,
-      refund_address: options.refundAddress,
-      confirm: options.confirm
-    }
-  });
-  return normalizeSwapStartInvoice(body);
-}
-async function refundRequest(options, routes, body, reference) {
-  if (reference === void 0) throw new Error("Swap refund requires reference.");
-  const refundAddress = nonEmptyString(body.refund_address);
-  if (refundAddress === void 0) throw new Error("Swap refund requires refund_address.");
-  const paymentHash = nonEmptyString(body.payment_hash);
-  if (paymentHash === void 0) throw new Error("Swap refund requires payment_hash.");
-  if (body.confirm === true) {
-    const status2 = recordOrEmpty(
-      await requestJson(options, routes.swapsRefunds, {
-        reference,
-        payment_hash: paymentHash,
-        refund_address: refundAddress
-      })
-    );
-    return { swap: status2 };
-  }
-  const status = recordOrEmpty(
-    await requestJson(options, routes.swapsStatus, {
-      reference,
-      payment_hash: paymentHash
-    })
-  );
-  return { swap: { ...status, refund_address: refundAddress } };
-}
-function withoutAction(body) {
-  const { action: _action, ...rest } = body;
-  return rest;
-}
-async function requestJson(options, url, body) {
-  const fetcher = options.fetch;
-  const response = await fetcher(url, {
-    method: "POST",
-    headers: requestHeaders(options.headers),
-    body: JSON.stringify(body)
-  });
-  return readJsonResponse(response, "OpenReceive request failed.");
-}
-function copyOptionalSwapFields(swap) {
-  const output = {};
-  for (const key of [
-    "deposit_memo",
-    "deposit_tx_id",
-    "payout_tx_id",
-    "refund_tx_id",
-    "refund_reason",
-    "refund_amount",
-    "attention",
-    "attempt_id",
-    "provider_order_id",
-    "refund_address",
-    "attention_reason",
-    "deposit_received_amount",
-    "fee"
-  ]) {
-    if (swap[key] !== void 0) output[key] = swap[key];
-  }
-  return output;
-}
-function emitSwapActionLog(logger, outcome, body, extra = {}) {
-  const sink = resolveBrowserLogger(logger);
-  if (sink === void 0) return;
-  const action = nonEmptyString(body.action);
-  if (action !== "start_swap" && action !== "refund_swap") return;
-  const event = action === "start_swap" ? `swap.start.${outcome}` : `swap.refund.${outcome}`;
-  const level = outcome === "failed" ? "warn" : outcome === "requested" ? "debug" : "info";
-  try {
-    sink(
-      sanitizeBrowserLogEntry({
-        level,
-        event,
-        message: `${action === "start_swap" ? "Swap start" : "Swap refund"} ${outcome}.`,
-        reference: nonEmptyString(body.reference),
-        pay_in_asset: nonEmptyString(body.pay_in_asset),
-        ...action === "refund_swap" ? { confirm: body.confirm === true } : {},
-        ...extra
-      })
-    );
-  } catch {
-  }
-}
-function swapActionResultFields(body) {
-  const swap = recordOrEmpty(recordOrEmpty(body).swap ?? body);
-  return {
-    payment_hash: nonEmptyString(swap.payment_hash),
-    provider_state: nonEmptyString(swap.provider_state),
-    attention: typeof swap.attention === "boolean" ? swap.attention : void 0
-  };
-}
-
-// src/internal/checkout-session.ts
+import { recordOrEmpty } from "@openreceive/core";
 var SWAP_START_FAILED = "Could not prepare the payment address. Please try again.";
 var MINT_FAILED = "Could not create the Lightning invoice. Please try again.";
 function normalizeSwapQuote(body) {
-  const quote = recordOrEmpty2(recordOrEmpty2(body).quote ?? body);
+  const quote = recordOrEmpty(recordOrEmpty(body).quote ?? body);
   const payInAsset = quote.pay_in_asset ?? quote.pay_asset;
   return typeof payInAsset === "string" ? { ...quote, pay_in_asset: payInAsset } : void 0;
 }
@@ -610,6 +415,9 @@ function sharedElementAttributes(options) {
   if (options.decodeLinkUrl !== void 0) {
     attributes[OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES.decodeLinkUrl] = options.decodeLinkUrl;
   }
+  if (isSet(options.assetBaseUrl)) {
+    attributes[OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES.assetBaseUrl] = options.assetBaseUrl;
+  }
   if (options.polling !== void 0) {
     attributes[OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES.polling] = String(options.polling);
   }
@@ -768,6 +576,9 @@ function createCheckoutShell(snapshot, options = {}) {
     themeToggle
   };
 }
+
+// src/headless.ts
+import { createAssetBaseUrlResolver } from "@openreceive/provider-data";
 export {
   BrowserRequestError,
   OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES,
@@ -776,6 +587,7 @@ export {
   OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS,
   OPENRECEIVE_CHECKOUT_ELEMENT_PARTS,
   OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS,
+  OPENRECEIVE_CHECKOUT_ELEMENT_SLOTS,
   OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME,
   OPENRECEIVE_COPY_FEEDBACK_MS,
   OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS,
@@ -795,6 +607,7 @@ export {
   checkoutElementStyles,
   checkoutLabels,
   copyInvoice,
+  createAssetBaseUrlResolver,
   createBlockExplorerUrl,
   createCheckoutActionEvent,
   createCheckoutController,
@@ -811,7 +624,7 @@ export {
   createCheckoutStatusModel,
   createDetailExternalLink,
   createLightningInvoiceDecodeUrl,
-  createPaymentDataEntries,
+  createMethodGridDisplay,
   createPaymentWizardController,
   createPaymentWizardModel,
   createPaymentWizardSelection,
@@ -835,9 +648,7 @@ export {
   deriveStatus,
   enterCheckoutResumePath,
   escapeHtml,
-  findSwapGridGroup,
   formatAmountCaption,
-  formatChooseNetworkHeading,
   formatDepositAmount,
   formatFiatAmount,
   formatMsats,
@@ -847,6 +658,7 @@ export {
   getExplorerNetwork,
   getNetworkIcon,
   getPaymentMethodIcon,
+  getRouteIconPath,
   getRouteNetworkLabel,
   getSwapOptionIcon,
   getSwapRefundFormError,
@@ -861,7 +673,6 @@ export {
   normalizeSwapStartInvoice,
   openWallet,
   orClasses,
-  overlaySwapRefundStaging,
   parseBooleanAttribute,
   parseMethodPickerKey,
   parseOptionalInteger,
@@ -877,21 +688,19 @@ export {
   readThemePreference,
   requestCheckout,
   requestSwapRefund,
-  resolvePreservedNetworkSelection,
   resolveTransactionDetailRows,
+  resolveWizardSelection,
   selectCheckoutDisplayInvoice,
+  selectCurrentSwapInvoice,
   startSwapRequest,
   swapAssetMatchesRoute,
   swapDepositRisk,
-  swapGroupLimitOption,
   swapOptionLimitMessage,
   swapOptionLimitSentence,
   swapPickerKey,
   syncStoredThemeControls,
   toggleStoredThemeControls,
   updatePaymentWizardSelection,
-  updateSelectedSwapNetworks,
   validateCheckoutProps,
-  wizardNetworkGroupIds,
   writeThemePreference
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { aK as BrowserLogLevel } from './status-D3VhJsUp.js';
-export { aL as BrowserLogEntry, X as BrowserLogger, B as BrowserLoggerOption, Y as BrowserRequestError, Z as CheckoutController, _ as CheckoutControllerOptions, l as CheckoutSnapshot, i as CheckoutState, aM as CopyInvoiceOptions, aN as GuestCheckoutResumeController, aO as GuestCheckoutResumeOptions, aP as OpenWalletOptions, aQ as PrepareCheckoutOptions, aR as QrOptions, aS as RequestCheckoutOptions, ak as Status, aT as StatusInvoiceLike, U as UnixSeconds, an as copyInvoice, ap as createCheckoutController, aU as createGuestCheckoutResume, aV as createGuestOrderFetcher, aW as createLightningUri, aX as createQrPngDataUrl, au as createQrSvg, ay as deriveStatus, az as enterCheckoutResumePath, aH as openWallet, aI as prepareCheckout, aJ as requestCheckout } from './status-D3VhJsUp.js';
+import { aM as BrowserLogLevel } from './status-C-zvqBau.js';
+export { aN as BrowserLogEntry, V as BrowserLogger, B as BrowserLoggerOption, X as BrowserRequestError, Y as CheckoutController, Z as CheckoutControllerOptions, g as CheckoutSnapshot, i as CheckoutState, aO as CopyInvoiceOptions, aP as GuestCheckoutResumeController, aQ as GuestCheckoutResumeOptions, aR as OpenWalletOptions, aS as PrepareCheckoutOptions, aT as QrOptions, aU as RequestCheckoutOptions, ak as Status, aV as StatusInvoiceLike, U as UnixSeconds, ap as copyInvoice, ar as createCheckoutController, aW as createGuestCheckoutResume, aX as createGuestOrderFetcher, aY as createLightningUri, aZ as createQrPngDataUrl, aw as createQrSvg, aA as deriveStatus, aB as enterCheckoutResumePath, aJ as openWallet, aK as prepareCheckout, aL as requestCheckout } from './status-C-zvqBau.js';
 import '@openreceive/provider-data';
 import '@openreceive/core';
 

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   openWallet,
   prepareCheckout,
   requestCheckout
-} from "./chunk-GA4FMG7L.js";
+} from "./chunk-NVEGYGZ5.js";
 export {
   BrowserRequestError,
   copyInvoice,

package/dist/{status-D3VhJsUp.d.ts → status-C-zvqBau.d.ts}

@@ -174,6 +174,8 @@ declare const OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES: {
     readonly meta: "data-openreceive-meta";
     readonly state: "data-openreceive-state";
     readonly actions: "data-openreceive-actions";
+    /** What the payer is buying, when the host's amount hook named it. */
+    readonly orderDescription: "data-openreceive-order-description";
     readonly theme: "data-openreceive-theme";
     readonly themeToggle: "data-openreceive-theme-toggle";
 };
@@ -183,6 +185,7 @@ declare const OPENRECEIVE_CHECKOUT_DATA_SELECTORS: {
     readonly meta: "[data-openreceive-meta]";
     readonly state: "[data-openreceive-state]";
     readonly actions: "[data-openreceive-actions]";
+    readonly orderDescription: "[data-openreceive-order-description]";
     readonly theme: "[data-openreceive-theme]";
     readonly themeToggle: "[data-openreceive-theme-toggle]";
 };
@@ -190,6 +193,17 @@ declare const OPENRECEIVE_CHECKOUT_ELEMENT_PARTS: {
     readonly copy: "copy";
     readonly startOver: "start-over";
 };
+/**
+ * Named slots the checkout element projects host light-DOM children into.
+ *
+ * `order` is the element's answer to React's render-prop `children`: a line-item
+ * strip, a thumbnail, a "you are buying" summary, drawn from the order
+ * OpenReceive does not own. It is projected through a `<slot>` in the shadow
+ * root, so it survives every re-render of the shell's `innerHTML` untouched.
+ */
+declare const OPENRECEIVE_CHECKOUT_ELEMENT_SLOTS: {
+    readonly order: "order";
+};
 declare const OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS: {
     readonly copy: "[part=\"copy\"]";
     readonly startOver: "[part=\"start-over\"]";
@@ -259,6 +273,17 @@ declare const OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES: {
      * default), no decode link is rendered and the invoice never leaves the page.
      */
     readonly decodeLinkUrl: "decode-link-url";
+    /**
+     * Where this app serves the packages' `dist/assets` trees, as one base URL —
+     * the string form of the `resolveAssetUrl` seam, so plain markup and the
+     * Vue/Svelte/Angular wrappers can reach it (a function cannot cross an HTML
+     * attribute). Every packaged key is a relative path under one `assets/` root,
+     * so the value is joined to it directly: `asset-base-url="/openreceive-assets"`
+     * makes `assets/icons/btc.svg` load from
+     * `/openreceive-assets/assets/icons/btc.svg`. A `resolveAssetUrl` passed to
+     * `defineElements` wins over it.
+     */
+    readonly assetBaseUrl: "asset-base-url";
     /** `polling="false"` renders the snapshot without status polling (no POST /payments/check). */
     readonly polling: "polling";
     /** Status poll cadence in milliseconds; defaults to OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS. */
@@ -390,6 +415,15 @@ interface SwapFeeBreakdown {
     /** The fee as a percentage of the cart total, e.g. "5.9%", when computable. */
     readonly feePercent?: string;
 }
+/** One value the payer has to reproduce, with the affordance that lets them. */
+interface SwapCopyRow {
+    readonly label: string;
+    readonly value: string;
+    /** The untruncated string a copy button writes, when it differs from `value`. */
+    readonly copyValue?: string;
+    /** Render the value in a selectable field rather than a code block. */
+    readonly selectable: boolean;
+}
 /**
  * How a deposit on this rail can actually go missing, which is what decides how
  * loud the deposit panel should be.
@@ -448,7 +482,22 @@ interface SwapDisplayModel {
     readonly networkWarning: string;
     readonly depositAddress: string;
     readonly depositMemo?: string;
+    /**
+     * BARE, with no asset symbol appended: it pastes into a wallet's amount field,
+     * where "0.032664 SOL" is not a number. Join the symbol at the point of
+     * display if a sentence needs it.
+     */
     readonly depositAmount: string;
+    /**
+     * Every value the payer must reproduce, as labelled rows: the deposit address,
+     * the memo where the rail has one, and the amount. The amount is the one that
+     * gets left out and the one that costs money — on token rails (USDT_TRON,
+     * USDT_ETH, USDC_ETH) the QR encodes the bare address and carries NO amount,
+     * so the payer types it off the screen, and a short send against a fixed-rate
+     * swap order is an underpayment: `refund_required`, a refund form, and a payer
+     * who has to come back.
+     */
+    readonly copyRows: readonly SwapCopyRow[];
     readonly providerStateLabel: string;
     readonly providerStateDetail: string;
     readonly state: "creating" | "deposit" | "progress" | "settled" | "expired" | "refund_required" | "refund_pending" | "refunded" | "attention" | "failed";
@@ -490,6 +539,11 @@ interface CheckoutInvoiceSnapshot {
     readonly expires_at?: number;
     readonly settled_at?: number;
     readonly swap?: CheckoutInvoiceSwapSnapshot;
+    /**
+     * What the payer is buying, carried through from the snapshot. Data, not a
+     * derived label, so it survives `normalizeCheckoutState`.
+     */
+    readonly description?: string;
 }
 interface CheckoutPaymentMethod {
     readonly pay_in_asset: string;
@@ -524,6 +578,13 @@ interface CheckoutSnapshot {
     readonly active?: CheckoutInvoiceSnapshot;
     readonly invoices: readonly CheckoutInvoiceSnapshot[];
     readonly payment_methods?: readonly CheckoutPaymentMethod[];
+    /**
+     * What the payer is buying, in the host's own words — one display string the
+     * host returned from `amountFor` / `amount_for`. OpenReceive owns no line
+     * items, so this is the whole of what it carries; a richer summary is the
+     * host's own markup (React `children`, the element's `order` slot).
+     */
+    readonly description?: string;
 }
 interface CheckoutElementAttributeOptions {
     /**
@@ -563,6 +624,14 @@ interface CheckoutElementAttributeOptions {
      * renders no "Decode" link and the invoice is never sent to a third party.
      */
     readonly decodeLinkUrl?: string;
+    /**
+     * Where this app serves the packages' `dist/assets` trees, as one base URL.
+     * The string form of the `resolveAssetUrl` seam: every packaged asset key is a
+     * relative path under one `assets/` root, so the value is joined to it
+     * directly. Emitted as the element's `asset-base-url` attribute, which is how
+     * the Vue/Svelte/Angular wrappers reach a seam a function cannot cross.
+     */
+    readonly assetBaseUrl?: string;
     /** False renders the snapshot without status polling (no POST /payments/check). */
     readonly polling?: boolean;
     /** Status poll cadence in milliseconds; defaults to OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS. */
@@ -737,12 +806,49 @@ interface CheckoutControllerOptions extends Omit<CheckoutWatcherOptions, "onStat
      * to render a snapshot without polling.
      */
     readonly prefix?: string;
+    /**
+     * False renders the snapshot without a status fetcher of its own. `prefix`
+     * still names the mount, so the swap-refund calls keep working — polling and
+     * "where the routes live" are two questions.
+     */
+    readonly polling?: boolean;
     readonly fetch?: typeof globalThis.fetch;
     readonly statusHeaders?: Readonly<Record<string, string>>;
     readonly clipboard?: Pick<Clipboard, "writeText">;
     readonly open?: (uri: string) => void;
 }
-interface CheckoutController {
+/**
+ * The two-step swap refund, and the staging that makes it survive polling. The
+ * controller implements it; a renderer that is handed one (React's
+ * `PaymentWizard`) takes exactly this much of it.
+ */
+interface SwapRefundStaging {
+    /**
+     * Step one: post `/swaps/status` and hold the address the payer typed so the
+     * panel can show it back for confirmation. It touches no refund route —
+     * nothing is submitted until {@link confirmSwapRefund}.
+     *
+     * The staged address is folded into every later snapshot, so polling cannot
+     * wipe what the payer is reviewing. `attemptId` is
+     * `SwapDisplayModel.attemptId`; the payment hash is resolved from the
+     * snapshot already in hand.
+     */
+    stageSwapRefund(options: {
+        readonly attemptId: string;
+        readonly refundAddress: string;
+    }): Promise<CheckoutInvoiceSnapshot>;
+    /** Step two: the only call that posts `/swaps/refunds`. */
+    confirmSwapRefund(options: {
+        readonly attemptId: string;
+        readonly refundAddress: string;
+    }): Promise<CheckoutInvoiceSnapshot>;
+    /**
+     * Drop the staged address. The payer leaving the swap for Lightning is the one
+     * exit that is not a submitted refund.
+     */
+    clearSwapRefundStaging(): void;
+}
+interface CheckoutController extends SwapRefundStaging {
     start(): CheckoutState;
     stop(): void;
     getState(): CheckoutState | undefined;
@@ -863,6 +969,8 @@ interface WizardRouteAssetDisplay {
     readonly label: string;
     readonly subtitle: string;
     readonly icon: string;
+    /** The packaged key behind `icon`, for a host serving the files itself. */
+    readonly iconPath: string;
     readonly selected: boolean;
 }
 interface WizardProviderTutorialDisplay {
@@ -1071,4 +1179,4 @@ declare function deriveStatus(invoice: StatusInvoiceLike, options?: {
     readonly now?: UnixSeconds;
 }): Status;
 
-export { type CheckoutPhase as $, type ThemeToggleElementAttributeOptions as A, type BrowserLoggerOption as B, type CheckoutInvoiceSnapshot as C, type ThemeToggleElementAttributes as D, type StoredThemeModelOptions as E, type ThemeModel as F, type ThemeModelOptions as G, type ReadThemePreferenceOptions as H, type ThemeControlTargets as I, type ThemeStorageOptions as J, type PaymentWizardControllerOptions as K, type PaymentWizardController as L, type PaymentWizardSelection as M, type PaymentWizardModel as N, type WizardRouteDisplay as O, type ParseOpenReceiveOptionalIntegerOptions as P, type PaymentWizardSelectionAction as Q, type ResolvedTheme as R, type SwapDisplayModel as S, type ThemePreference as T, type UnixSeconds as U, type BrowserLogContext as V, type WizardRouteAssetDisplay as W, type BrowserLogger as X, BrowserRequestError as Y, type CheckoutController as Z, type CheckoutControllerOptions as _, type PaymentMethod as a, type CheckoutStatusRefresh as a0, OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES as a1, OPENRECEIVE_CHECKOUT_DATA_SELECTORS as a2, OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES as a3, OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS as a4, OPENRECEIVE_CHECKOUT_ELEMENT_PARTS as a5, OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS as a6, OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME as a7, OPENRECEIVE_COPY_FEEDBACK_MS as a8, OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS as a9, escapeHtml as aA, formatAmountCaption as aB, formatDepositAmount as aC, formatFiatAmount as aD, formatMsats as aE, formatSwapLimit as aF, formatUnixTime as aG, openWallet as aH, prepareCheckout as aI, requestCheckout as aJ, type BrowserLogLevel as aK, type BrowserLogEntry as aL, type CopyInvoiceOptions as aM, type GuestCheckoutResumeController as aN, type GuestCheckoutResumeOptions as aO, type OpenWalletOptions as aP, type PrepareCheckoutOptions as aQ, type QrOptions as aR, type RequestCheckoutOptions as aS, type StatusInvoiceLike as aT, createGuestCheckoutResume as aU, createGuestOrderFetcher as aV, createLightningUri as aW, createQrPngDataUrl as aX, OPENRECEIVE_DEFAULT_PREFIX as aa, OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES as ab, OPENRECEIVE_PAYMENT_WIZARD_SELECTORS as ac, OPENRECEIVE_THEME_STORAGE_KEY as ad, OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES as ae, OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS as af, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS as ag, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS as ah, OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME as ai, type QrEncoder as aj, type Status as ak, type WizardProviderDisplay as al, assertDisplayInvoice as am, copyInvoice as an, createCheckoutActionEvent as ao, createCheckoutController as ap, createCheckoutErrorEvent as aq, createCheckoutProviderCopyEvent as ar, createCheckoutStateEvent as as, createQrPayloadSvg as at, createQrSvg as au, createStatusFetcher as av, createThemeChangeEvent as aw, deriveCheckoutStateLabels as ax, deriveStatus as ay, enterCheckoutResumePath as az, type PaymentMethodOption as b, type TickingValueOptions as c, type TickingValueController as d, type TransientFeedbackOptions as e, type TransientFeedbackController as f, type SwapDepositRisk as g, type CheckoutInvoiceSwapSnapshot as h, type CheckoutState as i, type TransactionDetailsInput as j, type TransactionDetailRow as k, type CheckoutSnapshot as l, type CreateCheckoutStateOptions as m, type CheckoutStatusModelInput as n, type CheckoutStatusModel as o, type CheckoutPaymentMethod as p, type ThemeAttributeTarget as q, type CheckoutElementAttributes as r, type CheckoutElementAttributeOptions as s, type CheckoutElementEventHandlers as t, type CheckoutElementListeners as u, type CreateCheckoutShellOptions as v, type CheckoutShellElements as w, type CheckoutShellOptions as x, type CheckoutShellModel as y, type CreateOpenReceiveThemeToggleElementOptions as z };
+export { type CheckoutStatusRefresh as $, type ThemeToggleElementAttributes as A, type BrowserLoggerOption as B, type CheckoutInvoiceSnapshot as C, type StoredThemeModelOptions as D, type ThemeModel as E, type ThemeModelOptions as F, type ReadThemePreferenceOptions as G, type ThemeControlTargets as H, type ThemeStorageOptions as I, type PaymentWizardControllerOptions as J, type PaymentWizardController as K, type PaymentWizardSelection as L, type PaymentWizardModel as M, type WizardRouteDisplay as N, type PaymentWizardSelectionAction as O, type ParseOpenReceiveOptionalIntegerOptions as P, type BrowserLogContext as Q, type ResolvedTheme as R, type SwapDisplayModel as S, type ThemePreference as T, type UnixSeconds as U, type BrowserLogger as V, type WizardRouteAssetDisplay as W, BrowserRequestError as X, type CheckoutController as Y, type CheckoutControllerOptions as Z, type CheckoutPhase as _, type PaymentMethod as a, OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES as a0, OPENRECEIVE_CHECKOUT_DATA_SELECTORS as a1, OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES as a2, OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS as a3, OPENRECEIVE_CHECKOUT_ELEMENT_PARTS as a4, OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS as a5, OPENRECEIVE_CHECKOUT_ELEMENT_SLOTS as a6, OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME as a7, OPENRECEIVE_COPY_FEEDBACK_MS as a8, OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS as a9, deriveStatus as aA, enterCheckoutResumePath as aB, escapeHtml as aC, formatAmountCaption as aD, formatDepositAmount as aE, formatFiatAmount as aF, formatMsats as aG, formatSwapLimit as aH, formatUnixTime as aI, openWallet as aJ, prepareCheckout as aK, requestCheckout as aL, type BrowserLogLevel as aM, type BrowserLogEntry as aN, type CopyInvoiceOptions as aO, type GuestCheckoutResumeController as aP, type GuestCheckoutResumeOptions as aQ, type OpenWalletOptions as aR, type PrepareCheckoutOptions as aS, type QrOptions as aT, type RequestCheckoutOptions as aU, type StatusInvoiceLike as aV, createGuestCheckoutResume as aW, createGuestOrderFetcher as aX, createLightningUri as aY, createQrPngDataUrl as aZ, OPENRECEIVE_DEFAULT_PREFIX as aa, OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES as ab, OPENRECEIVE_PAYMENT_WIZARD_SELECTORS as ac, OPENRECEIVE_THEME_STORAGE_KEY as ad, OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES as ae, OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS as af, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS as ag, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS as ah, OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME as ai, type QrEncoder as aj, type Status as ak, type SwapCopyRow as al, type SwapRefundStaging as am, type WizardProviderDisplay as an, assertDisplayInvoice as ao, copyInvoice as ap, createCheckoutActionEvent as aq, createCheckoutController as ar, createCheckoutErrorEvent as as, createCheckoutProviderCopyEvent as at, createCheckoutStateEvent as au, createQrPayloadSvg as av, createQrSvg as aw, createStatusFetcher as ax, createThemeChangeEvent as ay, deriveCheckoutStateLabels as az, type PaymentMethodOption as b, type TickingValueOptions as c, type TickingValueController as d, type TransientFeedbackOptions as e, type TransientFeedbackController as f, type CheckoutSnapshot as g, type SwapDepositRisk as h, type CheckoutState as i, type TransactionDetailsInput as j, type TransactionDetailRow as k, type CreateCheckoutStateOptions as l, type CheckoutStatusModelInput as m, type CheckoutStatusModel as n, type CheckoutPaymentMethod as o, type ThemeAttributeTarget as p, type CheckoutElementAttributes as q, type CheckoutElementAttributeOptions as r, type CheckoutElementEventHandlers as s, type CheckoutElementListeners as t, type CreateCheckoutShellOptions as u, type CheckoutShellElements as v, type CheckoutShellOptions as w, type CheckoutShellModel as x, type CreateOpenReceiveThemeToggleElementOptions as y, type ThemeToggleElementAttributeOptions as z };