@swype-org/deposit 0.3.26 → 0.3.32

package/dist/index.cjs

@@ -106,21 +106,84 @@ function parseCapabilities(value) {
   }
   return value.filter((entry) => typeof entry === "string");
 }
-function buildViewportMessage(viewportLvh, safeAreaBottom) {
-  return { type: "blink:viewport", viewportLvh, safeAreaBottom };
+function buildViewportMessage(viewportLvh, safeAreaBottom, embedMaxHeightPx) {
+  return {
+    type: "blink:viewport",
+    viewportLvh,
+    safeAreaBottom,
+    ...embedMaxHeightPx === void 0 ? {} : { embedMaxHeightPx }
+  };
+}
+var MAX_CONTENT_HEIGHT_PX = 2e4;
+function parseContentHeight(data) {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const msg = data;
+  if (msg.type !== "blink:content-height") {
+    return null;
+  }
+  const raw = msg.heightPx;
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    return null;
+  }
+  const heightPx = Math.round(raw);
+  if (heightPx <= 0 || heightPx > MAX_CONTENT_HEIGHT_PX) {
+    return null;
+  }
+  return {
+    type: "blink:content-height",
+    heightPx,
+    ...parseWidthHint("preferredWidthPx", msg.preferredWidthPx),
+    ...parseWidthHint("minWidthPx", msg.minWidthPx)
+  };
+}
+function parseWidthHint(key, value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return {};
+  const px = Math.round(value);
+  if (px <= 0 || px > MAX_CONTENT_HEIGHT_PX) return {};
+  return { [key]: px };
 }
 function buildRevealMessage() {
   return { type: "blink:reveal" };
 }
-function buildSignedPayloadMessage(merchantId, payload, signature) {
+function buildSignedPayloadMessage(merchantId, payload, signature, balance) {
   return {
     type: "blink:signed-payload",
     merchantId,
     payload,
-    signature
+    signature,
+    ...balance === void 0 ? {} : { balance }
   };
 }
 
+// src/brandParam.ts
+var BRAND_COLOR_PARAM_KEYS = {
+  colorPrimary: "p",
+  colorBackground: "bg",
+  colorText: "t",
+  colorDanger: "d",
+  colorBorder: "b"
+};
+function normalizeBrandHex(value) {
+  if (typeof value !== "string") return null;
+  const hex = value.trim().toLowerCase();
+  if (!/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/.test(hex)) return null;
+  const digits = hex.slice(1);
+  if (digits.length === 6) return `#${digits}`;
+  return `#${digits[0]}${digits[0]}${digits[1]}${digits[1]}${digits[2]}${digits[2]}`;
+}
+
+// src/balanceParam.ts
+var MAX_BALANCE_USD = 1e12;
+function normalizeDisplayBalance(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  if (value < 0 || value >= MAX_BALANCE_USD) return null;
+  const cents = Math.floor(Number((value * 100).toPrecision(15)));
+  if (cents < 0 || cents >= MAX_BALANCE_USD * 100) return null;
+  return (cents / 100).toFixed(2);
+}
+
 // src/walletBridge/discover.ts
 function createWalletDiscoverer() {
   if (typeof window === "undefined") {
@@ -552,6 +615,84 @@ function measureViewportMetrics() {
   }
 }
 
+// src/iframeCore.ts
+function createFrameElement(url) {
+  const iframe = document.createElement("iframe");
+  iframe.src = url;
+  const iframeOrigin = new URL(url).origin;
+  iframe.allow = `publickey-credentials-get ${iframeOrigin}; publickey-credentials-create ${iframeOrigin}; clipboard-write ${iframeOrigin}; web-share ${iframeOrigin}`;
+  return { iframe, iframeOrigin };
+}
+function attachFrameBridges(options) {
+  const { iframe, iframeOrigin, postViewport, getEmbedMaxHeightPx, shouldRevealOnLoad } = options;
+  let detached = false;
+  const discoverer = createWalletDiscoverer();
+  let rpcHostHandle = null;
+  const attachBridge = () => {
+    if (rpcHostHandle) return;
+    if (!iframe.contentWindow) return;
+    rpcHostHandle = attachRpcHost({
+      iframeWindow: iframe.contentWindow,
+      iframeOrigin,
+      discoverer
+    });
+  };
+  attachBridge();
+  iframe.addEventListener("load", attachBridge);
+  function postReveal() {
+    if (detached) return;
+    iframe.contentWindow?.postMessage(buildRevealMessage(), iframeOrigin);
+  }
+  function postViewportMetrics() {
+    if (detached || !postViewport) return;
+    const metrics = measureViewportMetrics();
+    if (metrics.viewportLvh <= 0) return;
+    iframe.contentWindow?.postMessage(
+      buildViewportMessage(
+        metrics.viewportLvh,
+        metrics.safeAreaBottom,
+        getEmbedMaxHeightPx?.()
+      ),
+      iframeOrigin
+    );
+  }
+  let viewportPostScheduled = false;
+  const onViewportChange = () => {
+    if (viewportPostScheduled) return;
+    viewportPostScheduled = true;
+    requestAnimationFrame(() => {
+      viewportPostScheduled = false;
+      postViewportMetrics();
+    });
+  };
+  if (postViewport) {
+    window.addEventListener("resize", onViewportChange);
+    window.addEventListener("orientationchange", onViewportChange);
+  }
+  const onLoadReveal = () => {
+    postViewportMetrics();
+    if (shouldRevealOnLoad()) postReveal();
+  };
+  iframe.addEventListener("load", onLoadReveal);
+  return {
+    postReveal,
+    postViewportMetrics,
+    detach() {
+      if (detached) return;
+      detached = true;
+      iframe.removeEventListener("load", attachBridge);
+      iframe.removeEventListener("load", onLoadReveal);
+      window.removeEventListener("resize", onViewportChange);
+      window.removeEventListener("orientationchange", onViewportChange);
+      if (rpcHostHandle) {
+        rpcHostHandle.detach();
+        rpcHostHandle = null;
+      }
+      discoverer.destroy();
+    }
+  };
+}
+
 // src/iframe.ts
 var STYLE_ID = "blink-deposit-styles";
 var CLOSE_DURATION_MS = 280;
@@ -593,60 +734,20 @@ function createIframe(url, containerElement, options) {
   }
   const container = document.createElement("div");
   container.setAttribute("data-blink-container", "");
-  const iframe = document.createElement("iframe");
-  iframe.src = url;
-  const iframeOrigin = new URL(url).origin;
-  iframe.allow = `publickey-credentials-get ${iframeOrigin}; publickey-credentials-create ${iframeOrigin}; clipboard-write ${iframeOrigin}`;
+  const { iframe, iframeOrigin } = createFrameElement(url);
   const handle = document.createElement("div");
   container.appendChild(handle);
   container.appendChild(iframe);
   overlay.appendChild(container);
   const mountTarget = containerElement ?? document.body;
   mountTarget.appendChild(overlay);
-  const discoverer = createWalletDiscoverer();
-  let rpcHostHandle = null;
-  const attachBridge = () => {
-    if (rpcHostHandle) return;
-    if (!iframe.contentWindow) return;
-    rpcHostHandle = attachRpcHost({
-      iframeWindow: iframe.contentWindow,
-      iframeOrigin,
-      discoverer
-    });
-  };
-  attachBridge();
-  iframe.addEventListener("load", attachBridge);
-  function postReveal() {
-    if (closed) return;
-    iframe.contentWindow?.postMessage(buildRevealMessage(), iframeOrigin);
-  }
-  function postViewportMetrics() {
-    if (closed || !options?.fluid) return;
-    const metrics = measureViewportMetrics();
-    if (metrics.viewportLvh <= 0) return;
-    iframe.contentWindow?.postMessage(
-      buildViewportMessage(metrics.viewportLvh, metrics.safeAreaBottom),
-      iframeOrigin
-    );
-  }
-  let viewportPostScheduled = false;
-  const onViewportChange = () => {
-    if (viewportPostScheduled) return;
-    viewportPostScheduled = true;
-    requestAnimationFrame(() => {
-      viewportPostScheduled = false;
-      postViewportMetrics();
-    });
-  };
-  if (options?.fluid) {
-    window.addEventListener("resize", onViewportChange);
-    window.addEventListener("orientationchange", onViewportChange);
-  }
-  const onLoadReveal = () => {
-    postViewportMetrics();
-    if (!hidden) postReveal();
-  };
-  iframe.addEventListener("load", onLoadReveal);
+  const bridges = attachFrameBridges({
+    iframe,
+    iframeOrigin,
+    // Only fluid needs them: the legacy fixed overlay sizes the iframe itself.
+    postViewport: options?.fluid === true,
+    shouldRevealOnLoad: () => !hidden
+  });
   let savedOverflow = "";
   let scrollLocked = false;
   const onBackdropClick = (event) => {
@@ -677,8 +778,6 @@ function createIframe(url, containerElement, options) {
     overlay.removeEventListener("click", onBackdropClick);
     overlay.removeEventListener("touchmove", onTouchMove);
     document.removeEventListener("keydown", onKeyDown);
-    window.removeEventListener("resize", onViewportChange);
-    window.removeEventListener("orientationchange", onViewportChange);
   }
   function unlockScroll() {
     if (!scrollLocked) return;
@@ -689,7 +788,7 @@ function createIframe(url, containerElement, options) {
     if (closed) return;
     closed = true;
     removeListeners();
-    detachBridge();
+    bridges.detach();
     overlay.setAttribute("data-blink-closing", "");
     let removed = false;
     const removeOverlay = () => {
@@ -702,15 +801,6 @@ function createIframe(url, containerElement, options) {
     container.addEventListener("animationend", removeOverlay, { once: true });
     setTimeout(removeOverlay, CLOSE_DURATION_MS + 50);
   }
-  function detachBridge() {
-    iframe.removeEventListener("load", attachBridge);
-    iframe.removeEventListener("load", onLoadReveal);
-    if (rpcHostHandle) {
-      rpcHostHandle.detach();
-      rpcHostHandle = null;
-    }
-    discoverer.destroy();
-  }
   return {
     get contentWindow() {
       return iframe.contentWindow;
@@ -735,15 +825,17 @@ function createIframe(url, containerElement, options) {
       overlay.style.display = "";
       lockScroll();
       attachDismissalListeners();
-      postViewportMetrics();
-      postReveal();
+      bridges.postViewportMetrics();
+      bridges.postReveal();
     },
     postReveal() {
-      postReveal();
+      bridges.postReveal();
     },
     downgradeToFixed() {
       overlay.removeAttribute("data-blink-fluid");
     },
+    applyContentHeight() {
+    },
     onClose(callback) {
       closeCallback = callback;
     },
@@ -752,7 +844,7 @@ function createIframe(url, containerElement, options) {
       if (!closed) {
         closed = true;
         removeListeners();
-        detachBridge();
+        bridges.detach();
         overlay.remove();
         unlockScroll();
       }
@@ -789,6 +881,117 @@ function shouldUseMobileSheetLayout() {
   return shortestScreenSide > 0 && shortestScreenSide <= MOBILE_SHEET_MAX_SCREEN_PX;
 }
 
+// src/embeddedIframe.ts
+var EMBED_STYLE_ID = "blink-deposit-embed-styles";
+var EMBED_STYLES = `
+[data-blink-embed]{display:block;width:100%;position:relative}
+[data-blink-embed][data-blink-embed-hidden]{height:0;overflow:hidden;visibility:hidden;pointer-events:none}
+[data-blink-embed] iframe{display:block;width:100%;height:0;border:none;background:transparent;color-scheme:light}
+`;
+function createEmbeddedIframe(url, containerElement, options) {
+  ensureEmbedStyles();
+  if (!containerElement.isConnected) {
+    console.warn(
+      "[blink] The containerElement passed to Deposit is not in the document. Embedded mode renders into it for the life of the instance, so it must be a stable node \u2014 render the slot once and hide it with `visibility: hidden` (NOT `display: none`, which removes its layout and leaves the warming flow unable to measure itself) instead of unmounting it, or construct a new Deposit against the new node."
+    );
+  }
+  let closed = false;
+  let hidden = options?.hidden === true;
+  let closeCallback = null;
+  const readEmbedMaxHeightPx = () => typeof options?.embedMaxHeightPx === "function" ? options.embedMaxHeightPx() : options?.embedMaxHeightPx;
+  const wrapper = document.createElement("div");
+  wrapper.setAttribute("data-blink-embed", "");
+  if (hidden) {
+    wrapper.setAttribute("data-blink-embed-hidden", "");
+  }
+  const { iframe, iframeOrigin } = createFrameElement(url);
+  iframe.setAttribute("scrolling", "no");
+  const initialBudget = readEmbedMaxHeightPx();
+  if (initialBudget !== void 0) {
+    iframe.style.height = `${initialBudget}px`;
+  }
+  wrapper.appendChild(iframe);
+  containerElement.appendChild(wrapper);
+  const bridges = attachFrameBridges({
+    iframe,
+    iframeOrigin,
+    // Embedded always needs them: the flow has no usable viewport of its own,
+    // so the basis it sizes against can only come from here.
+    postViewport: true,
+    getEmbedMaxHeightPx: readEmbedMaxHeightPx,
+    shouldRevealOnLoad: () => !hidden
+  });
+  function teardown() {
+    closed = true;
+    bridges.detach();
+    wrapper.remove();
+  }
+  return {
+    get contentWindow() {
+      return iframe.contentWindow;
+    },
+    close() {
+      if (closed) return;
+      teardown();
+      closeCallback?.();
+    },
+    isClosed() {
+      return closed;
+    },
+    isHidden() {
+      return hidden;
+    },
+    reveal() {
+      if (closed || !hidden) return;
+      hidden = false;
+      wrapper.removeAttribute("data-blink-embed-hidden");
+      warnIfContainerNotRendered(containerElement);
+      bridges.postViewportMetrics();
+      bridges.postReveal();
+    },
+    postReveal() {
+      bridges.postReveal();
+    },
+    downgradeToFixed() {
+    },
+    applyContentHeight(heightPx) {
+      if (closed) return;
+      const budget = readEmbedMaxHeightPx();
+      const capped = budget === void 0 ? heightPx : Math.min(heightPx, budget);
+      iframe.style.height = `${Math.max(0, Math.round(capped))}px`;
+    },
+    onClose(callback) {
+      closeCallback = callback;
+    },
+    destroy() {
+      closeCallback = null;
+      if (!closed) teardown();
+    }
+  };
+}
+function warnIfContainerNotRendered(containerElement) {
+  if (typeof containerElement.getBoundingClientRect !== "function") return;
+  const rect = containerElement.getBoundingClientRect();
+  if (rect.width > 0 || rect.height > 0) return;
+  const display = typeof getComputedStyle === "function" ? getComputedStyle(containerElement).display : "";
+  console.warn(
+    `[blink] The containerElement has no layout at the moment the flow is revealed${display === "none" ? " (display: none)" : ""}. A display:none subtree cannot be measured, so the flow may report no height and the panel stays blank at its budget height. Hide the slot with \`visibility: hidden\` (plus \`height: 0; overflow: hidden\`) instead of \`display: none\`, so it keeps its box while it warms up.`
+  );
+}
+function ensureEmbedStyles() {
+  const existingStyle = document.getElementById(EMBED_STYLE_ID);
+  if (existingStyle) {
+    if (existingStyle.textContent !== EMBED_STYLES) {
+      existingStyle.textContent = EMBED_STYLES;
+    }
+    return;
+  }
+  const style = document.createElement("style");
+  style.id = EMBED_STYLE_ID;
+  style.textContent = EMBED_STYLES;
+  document.head.appendChild(style);
+}
+
 // src/signer.ts
 var DEFAULT_SIGNER_TIMEOUT_MS = 15e3;
 async function callSigner(signer, request, timeoutMs) {
@@ -919,6 +1122,13 @@ var SANDBOX_WEBVIEW_BASE_URL = "https://pay-sandbox.blink.cash";
 var IFRAME_READY_TIMEOUT_MS = 2e3;
 var WARM_IFRAME_READY_TIMEOUT_MS = 6e4;
 var LAYOUT_FLUID_CAPABILITY = "layout-fluid";
+var DEFAULT_EMBED_MAX_HEIGHT_FRACTION = 0.9;
+function dismissedError() {
+  return new DepositError(
+    "DEPOSIT_DISMISSED",
+    "The deposit was dismissed before the transfer completed."
+  );
+}
 var IFRAME_NOT_READY = { ready: false, fluidCapable: false };
 function resolveWebviewBaseUrl(config) {
   if (config.webviewBaseUrl) return config.webviewBaseUrl;
@@ -939,11 +1149,20 @@ var Deposit = class {
   warmIframe = null;
   warmIframeReady = null;
   warmIframeReadyCancel = null;
+  /** Resolved embedded-vs-overlay decision; see {@link Deposit.isEmbedded}. */
+  embeddedResolved = null;
+  /**
+   * Settles the in-flight `requestDeposit()` as a dismissal. Non-null exactly
+   * while a flow is in progress, so {@link Deposit.close} can reject the promise
+   * the caller is awaiting instead of tearing the frame down under it.
+   */
+  dismissActiveFlow = null;
   listeners = {
     complete: /* @__PURE__ */ new Set(),
     error: /* @__PURE__ */ new Set(),
     close: /* @__PURE__ */ new Set(),
-    "status-change": /* @__PURE__ */ new Set()
+    "status-change": /* @__PURE__ */ new Set(),
+    resize: /* @__PURE__ */ new Set()
   };
   /** Current phase of the deposit flow. */
   get status() {
@@ -961,10 +1180,40 @@ var Deposit = class {
   get isActive() {
     return this._status === "signer-loading" || this._status === "iframe-active";
   }
+  /**
+   * How this instance will actually present: `'embedded'` renders inline in
+   * `containerElement`, `'overlay'` covers the page.
+   *
+   * Not simply an echo of the config — a host that asked for `'embedded'` gets
+   * `'overlay'` on mobile, where a phone-sized method panel cannot hold the
+   * flow (see {@link Deposit.isEmbedded}). Read it when laying out the panel:
+   * on `'overlay'` no `resize` event ever fires, so a panel sized from those
+   * reports would sit empty behind the overlay — collapse or skip it.
+   *
+   * Live until the SDK builds its first (warm-up) frame and fixed from then on,
+   * so re-read it on resize rather than caching it at mount.
+   */
+  get presentation() {
+    return this.isEmbedded() ? "embedded" : "overlay";
+  }
   constructor(config) {
     if (!config.signer || typeof config.signer !== "string" && typeof config.signer !== "function") {
       throw new DepositError("INVALID_REQUEST", "DepositConfig.signer is required (URL string or SignerFunction).");
     }
+    if (config.presentation === "embedded") {
+      if (!config.containerElement) {
+        throw new DepositError(
+          "INVALID_REQUEST",
+          'DepositConfig.containerElement is required when presentation is "embedded".'
+        );
+      }
+      if (config.layout === "fixed") {
+        throw new DepositError(
+          "INVALID_REQUEST",
+          'DepositConfig.layout "fixed" is an overlay-only escape hatch and cannot be combined with presentation "embedded".'
+        );
+      }
+    }
     this.config = config;
     this.log("Deposit instance created", {
       signer: typeof config.signer === "string" ? config.signer : "<function>"
@@ -990,10 +1239,7 @@ var Deposit = class {
     const webviewBaseUrl = resolveWebviewBaseUrl(this.config);
     this.hostedOrigin = this.config.hostedFlowOrigin ?? new URL(webviewBaseUrl).origin;
     const preloadUrl = this.buildPreloadUrl(webviewBaseUrl);
-    const iframe = createIframe(preloadUrl, this.config.containerElement, {
-      hidden: true,
-      fluid: this.isFluidLayout()
-    });
+    const iframe = this.createPresentedIframe(preloadUrl, { hidden: true });
     const ready = this.waitForIframeReady(iframe, WARM_IFRAME_READY_TIMEOUT_MS);
     this.warmIframe = iframe;
     this.warmIframeReady = ready.promise;
@@ -1022,6 +1268,83 @@ var Deposit = class {
       window.addEventListener("load", whenIdle, { once: true });
     }
   }
+  /**
+   * Whether the flow renders inline in the host's element rather than as an
+   * overlay.
+   *
+   * `presentation: 'embedded'` is a request, not a guarantee: **on mobile the
+   * flow presents as the normal overlay** even for an embedded host. An
+   * aggregator's method panel is a narrow, short column on a phone, and the
+   * flow inside it is a payment journey with a keypad, wallet lists and a QR
+   * code — it needs the screen. The overlay is exactly what a phone user gets
+   * from every other Blink integration, and the host's own dialog stays behind
+   * it. Desktop keeps the inline card, where the panel has room.
+   *
+   * **The decision lives with the frame.** Read live until a frame is built,
+   * then committed for good ({@link Deposit.createPresentedIframe}) — `preload()`
+   * warms a frame from these same predicates and the flow that later adopts it
+   * must agree, because a frame warmed at `layout=embed` handed to the overlay
+   * presenter (or the reverse) is a blank modal. Committing at frame creation
+   * rather than at construction matters: a host that constructs `Deposit` before
+   * layout settles — a widget mounting inside a transition, a background or
+   * prerendered tab — reports a zero-width viewport, and `(max-width: 640px)`
+   * matches at zero, so caching then would lock a desktop user into the overlay
+   * over a viewport that never existed. The warm-up already waits for `load`
+   * plus an idle callback, so by the time it commits the measurement is real.
+   */
+  isEmbedded() {
+    if (this.config.presentation !== "embedded") return false;
+    if (this.embeddedResolved !== null) return this.embeddedResolved;
+    if (typeof window === "undefined") return true;
+    const viewportWidth = window.visualViewport?.width ?? window.innerWidth;
+    if (!(viewportWidth > 0)) return true;
+    return !shouldUseMobileSheetLayout();
+  }
+  /**
+   * The host's height budget for the inline iframe. Explicit config wins;
+   * otherwise most of the host viewport, which keeps a tall flow from
+   * outgrowing the page it is embedded in.
+   */
+  resolveEmbedMaxHeightPx() {
+    if (this.config.embedMaxHeightPx !== void 0) return this.config.embedMaxHeightPx;
+    if (typeof window === "undefined") return void 0;
+    const derived = Math.round(window.innerHeight * DEFAULT_EMBED_MAX_HEIGHT_FRACTION);
+    return derived > 0 ? derived : void 0;
+  }
+  /** Build the iframe for the configured presentation. */
+  createPresentedIframe(url, options) {
+    if (this.config.presentation === "embedded" && this.embeddedResolved === null) {
+      this.embeddedResolved = this.isEmbedded();
+      if (!this.embeddedResolved) {
+        this.log("Mobile device: presenting the embedded flow as an overlay");
+      }
+    }
+    if (this.isEmbedded()) {
+      return createEmbeddedIframe(url, this.config.containerElement, {
+        hidden: options.hidden,
+        // A getter, not a value: the default is derived from the host
+        // viewport, which changes on rotation and window resize.
+        embedMaxHeightPx: () => this.resolveEmbedMaxHeightPx()
+      });
+    }
+    return createIframe(url, this.overlayMountTarget(), {
+      hidden: options.hidden,
+      fluid: this.isFluidLayout()
+    });
+  }
+  /**
+   * Where the overlay mounts. `containerElement` means two different things by
+   * presentation: an overlay mount point (`presentation: 'overlay'`) or the
+   * aggregator's inline panel slot (`'embedded'`). When an embedded flow
+   * presents as an overlay on mobile, that slot must NOT be the mount point —
+   * `position: fixed` resolves against the nearest transformed/filtered/
+   * contained ancestor, and an aggregator's animated dialog is exactly that, so
+   * the "full-screen" overlay would end up positioned inside their panel.
+   * Falls through to `document.body`.
+   */
+  overlayMountTarget() {
+    return this.config.presentation === "embedded" ? void 0 : this.config.containerElement;
+  }
   buildPreloadUrl(webviewBaseUrl) {
     const preloadUrl = new URL(webviewBaseUrl);
     preloadUrl.searchParams.set("preload", "true");
@@ -1087,6 +1410,7 @@ var Deposit = class {
       const settle = (fn) => {
         if (this.requestId !== currentRequestId || settled) return;
         settled = true;
+        this.dismissActiveFlow = null;
         fn();
       };
       const onComplete = (result) => {
@@ -1112,6 +1436,12 @@ var Deposit = class {
           reject(error);
         });
       };
+      this.dismissActiveFlow = () => {
+        settle(() => {
+          this.cleanup();
+          reject(dismissedError());
+        });
+      };
       if (this.config.flowTimeoutMs != null && this.config.flowTimeoutMs > 0) {
         this.flowTimer = setTimeout(() => {
           onError(
@@ -1138,9 +1468,29 @@ var Deposit = class {
   /** No-op — retained for API compatibility with the popup-based SDK. */
   focus() {
   }
-  /** Close the deposit iframe without waiting for completion. */
+  /**
+   * Close the deposit iframe without waiting for completion — the host's own
+   * back button or dialog chrome.
+   *
+   * This **settles a flow in progress** by rejecting its `requestDeposit()`
+   * promise with `DEPOSIT_DISMISSED`, exactly as the flow's own close control
+   * does. It has to: `cleanup()` destroys the frame through `destroy()`, which
+   * drops the handle's close callback on purpose, so without this the caller's
+   * `await` never returns. An aggregator whose back button awaited that promise
+   * to restore its method list was left showing an empty panel — the flow gone,
+   * its own list still not rendered, and no error to explain why.
+   *
+   * The rejection code is the same `DEPOSIT_DISMISSED` the in-flow control
+   * produces, so a host writes one dismissal branch rather than one per
+   * affordance. What it deliberately does not do is report an error: no `error`
+   * event, and `status` lands on 'idle' as it always has, because the host
+   * initiated this. With no flow in progress it is a plain teardown, unchanged.
+   */
   close() {
     this.log("close() called");
+    const dismiss = this.dismissActiveFlow;
+    this.dismissActiveFlow = null;
+    dismiss?.();
     this.cleanup();
     this.setStatus("idle");
     this.emit("close");
@@ -1193,10 +1543,80 @@ var Deposit = class {
     if (theme === "dark" || theme === "system") {
       url.searchParams.set("appearance", theme);
     }
+    this.applyBrandParam(url);
+  }
+  /**
+   * Appends the merchant's brand colors as `brand=p-0f62fe.bg-ffffff…`.
+   *
+   * On the URL rather than a message because the hosted flow's loading shell
+   * paints from its entry chunk, hundreds of ms before React mounts: a palette
+   * that arrived by `postMessage` would show Blink's own card color first and
+   * then become the merchant's. Unreserved characters only, so the param costs
+   * ~50 bytes of the URL budget rather than triple that in percent-encoding.
+   *
+   * Validated here purely so the merchant sees the complaint in their OWN
+   * console — the hosted flow re-validates everything it decodes, since the URL
+   * is host-controlled input that ends up in a stylesheet. Silence would be the
+   * worst outcome: a dropped color that nobody is told about looks like the SDK
+   * ignoring the config.
+   */
+  applyBrandParam(url) {
+    const variables = this.config.appearance?.variables;
+    if (!variables) return;
+    const accepted = {};
+    for (const [key, value] of Object.entries(variables)) {
+      if (value === void 0 || value === null) continue;
+      if (!BRAND_COLOR_PARAM_KEYS[key]) {
+        console.error(
+          `[blink] appearance.variables.${key} is not a supported brand color. Supported: ${Object.keys(BRAND_COLOR_PARAM_KEYS).join(", ")}.`
+        );
+        continue;
+      }
+      const hex = normalizeBrandHex(value);
+      if (!hex) {
+        console.error(
+          `[blink] appearance.variables.${key} must be opaque hex (#rgb or #rrggbb); received ${JSON.stringify(value)}. Ignoring it.`
+        );
+        continue;
+      }
+      accepted[key] = hex;
+    }
+    const encoded = Object.keys(BRAND_COLOR_PARAM_KEYS).filter((key) => accepted[key] !== void 0).map((key) => `${BRAND_COLOR_PARAM_KEYS[key]}-${accepted[key].slice(1)}`).join(".");
+    if (encoded) url.searchParams.set("brand", encoded);
+  }
+  /**
+   * Normalizes the display-only {@link DepositRequest.balance} for the wire,
+   * or returns `undefined` to omit it everywhere — the `blink:signed-payload`
+   * sibling field and the legacy fallback URL param alike. Additive wire
+   * discipline: an unset or rejected balance leaves both channels
+   * byte-for-byte what they always were, and old webviews ignore the field
+   * by construction.
+   *
+   * Validated here purely so the merchant sees the complaint in their OWN
+   * console (same rationale as {@link applyBrandParam}); the hosted flow
+   * re-validates whatever arrives, since both channels are host-controlled
+   * input. A rejected balance never blocks the deposit — the flow proceeds
+   * without the subtitle.
+   */
+  normalizeRequestBalance(balance) {
+    if (balance === void 0 || balance === null) return void 0;
+    const normalized = normalizeDisplayBalance(balance);
+    if (normalized === null) {
+      const received = typeof balance === "number" ? String(balance) : JSON.stringify(balance) ?? String(balance);
+      console.error(
+        `[blink] balance must be a finite number >= 0 and < 1e12 (USD, display only); received ${received}. Ignoring it.`
+      );
+      return void 0;
+    }
+    return normalized;
   }
-  /** Fluid is the default; `layout: 'fixed'` opts back into the legacy container. */
+  /**
+   * Fluid is the default; `layout: 'fixed'` opts back into the legacy
+   * container. Embedded is a separate presentation and never fluid — the
+   * constructor rejects the combination outright.
+   */
   isFluidLayout() {
-    return this.config.layout !== "fixed";
+    return !this.isEmbedded() && this.config.layout !== "fixed";
   }
   /**
    * Marks the hosted-flow URL as fluid-layout: the iframe spans the full
@@ -1206,6 +1626,10 @@ var Deposit = class {
    * assumed to understand fluid layout and gets the fixed container.
    */
   applyLayoutParam(url) {
+    if (this.isEmbedded()) {
+      url.searchParams.set("layout", "embed");
+      return;
+    }
     if (this.isFluidLayout()) {
       url.searchParams.set("layout", "fluid");
     }
@@ -1217,7 +1641,14 @@ var Deposit = class {
    * afterwards (rotation, window resize) — see iframe.ts.
    */
   applyViewportParams(url) {
-    if (!this.isFluidLayout()) return;
+    const embedded = this.isEmbedded();
+    if (!this.isFluidLayout() && !embedded) return;
+    if (embedded) {
+      const embedMaxHeightPx = this.resolveEmbedMaxHeightPx();
+      if (embedMaxHeightPx !== void 0) {
+        url.searchParams.set("embedMaxHeight", String(embedMaxHeightPx));
+      }
+    }
     const metrics = measureViewportMetrics();
     if (metrics.viewportLvh <= 0) return;
     url.searchParams.set("viewportLvh", String(metrics.viewportLvh));
@@ -1237,6 +1668,7 @@ var Deposit = class {
         signer: typeof this.config.signer === "string" ? this.config.signer : "<function>"
       });
       const signerRequest = buildSignerRequest(request, webviewBaseUrl);
+      const displayBalance = this.normalizeRequestBalance(request.balance);
       let preloadIframe;
       let iframeReadyPromise;
       const warm = this.takeWarmIframe();
@@ -1254,21 +1686,12 @@ var Deposit = class {
         });
         this.log("Reusing warm preload iframe");
       } else {
-        preloadIframe = createIframe(
-          this.buildPreloadUrl(webviewBaseUrl),
-          this.config.containerElement,
-          { fluid: this.isFluidLayout() }
-        );
+        preloadIframe = this.createPresentedIframe(this.buildPreloadUrl(webviewBaseUrl), {});
         iframeReadyPromise = this.waitForIframeReady(preloadIframe).promise;
       }
       this.iframe = preloadIframe;
       preloadIframe.onClose(() => {
-        onError(
-          new DepositError(
-            "DEPOSIT_DISMISSED",
-            "The deposit was dismissed before the transfer completed."
-          )
-        );
+        onError(dismissedError());
         this.cleanup();
         this.emit("close");
       });
@@ -1298,7 +1721,8 @@ var Deposit = class {
             buildSignedPayloadMessage(
               signerResponse.merchantId,
               signerResponse.payload,
-              signerResponse.signature
+              signerResponse.signature,
+              displayBalance
             ),
             this.hostedOrigin
           );
@@ -1312,17 +1736,19 @@ var Deposit = class {
         hostedUrl.searchParams.set("merchantId", signerResponse.merchantId);
         hostedUrl.searchParams.set("payload", signerResponse.payload);
         hostedUrl.searchParams.set("signature", signerResponse.signature);
+        if (displayBalance !== void 0) {
+          hostedUrl.searchParams.set("balance", displayBalance);
+        }
         this.applyFullWidgetParam(hostedUrl);
+        if (this.isEmbedded()) {
+          this.applyLayoutParam(hostedUrl);
+          this.applyViewportParams(hostedUrl);
+        }
         const targetUrl = hostedUrl.toString();
-        const iframeHandle = createIframe(targetUrl, this.config.containerElement);
+        const iframeHandle = this.createPresentedIframe(targetUrl, {});
         this.iframe = iframeHandle;
         iframeHandle.onClose(() => {
-          onError(
-            new DepositError(
-              "DEPOSIT_DISMISSED",
-              "The deposit was dismissed before the transfer completed."
-            )
-          );
+          onError(dismissedError());
           this.cleanup();
           this.emit("close");
         });
@@ -1398,6 +1824,16 @@ var Deposit = class {
         iframeHandle.close();
         return;
       }
+      const contentHeight = parseContentHeight(event.data);
+      if (contentHeight) {
+        iframeHandle.applyContentHeight(contentHeight.heightPx);
+        this.emit("resize", {
+          heightPx: contentHeight.heightPx,
+          ...contentHeight.preferredWidthPx === void 0 ? {} : { preferredWidthPx: contentHeight.preferredWidthPx },
+          ...contentHeight.minWidthPx === void 0 ? {} : { minWidthPx: contentHeight.minWidthPx }
+        });
+        return;
+      }
       const message = parseTransferComplete(event.data);
       if (!message) {
         return;
@@ -1475,7 +1911,7 @@ function detectMerchantColorScheme() {
 var Checkout = Deposit;
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.3.32";
 
 exports.ALLOWED_RPC_METHODS = ALLOWED_RPC_METHODS;
 exports.BRIDGE_PROTOCOL_VERSION = BRIDGE_PROTOCOL_VERSION;