@12-apps/payments-frontend 3.48.1 → 3.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.48.1",
+  "version": "3.49.0",
   "type": "module",
   "sideEffects": false,
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",

package/src/components/checkout/list/choice-list.tsx

@@ -155,6 +155,9 @@ export function ChoiceList({
   const base = useId();
   const props: RowProps = { ...rest, name: `${base}-choice` };
   const { copy, state } = props;
+  // Nothing to tap before the saved cards answer: a row tapped now would move
+  // when the saved card is preselected and opens its chips (FUT-3849).
+  if (!state.settled) return <Box data-testid="payment-list-loading" aria-busy="true" sx={{ minHeight: (theme) => theme.spacing(30) }} />;
   return (
     <Box
       data-testid="payment-list"

package/src/components/checkout/list/cpf-top.tsx

@@ -4,7 +4,6 @@ import { useEffect, useRef, type JSX } from "react";
 import { formatCpf, validateCpf } from "../../../card";
 import { fieldSatisfied } from "../buyer-fields";
 import { useCheckoutCopy } from "../copy-context";
-import { useCheckoutLayout } from "../payment-step-layout";
 import type { BuyerInfo, CheckoutCustomerField } from "../types";
 import { useCheckoutComponents } from "../ui";
 
@@ -15,6 +14,14 @@ import type { PaymentListCopy } from "./types";
 /** The prototype's 280px CPF field on a computer (L7), on the theme's spacing scale. */
 const FIELD_WIDE_MAX = 35;
 
+/**
+ * The list's own width from which the field stops at ~280px (FUT-3711): twice
+ * the field. Read off the list's container, not the window or the flow's
+ * frame — a host laying out its own two columns puts the list in a ~680px
+ * column, under the frame's 900px "wide", and the field still has to stop.
+ */
+const FIELD_CAP_FROM_PX = 560;
+
 /**
  * The CPF at the TOP of Pagamento, above the wallets (FUT-3685, C3, C4, E1,
  * L7): "CPF", the provider's reason under it ("o PagBank pede para pagar pelo
@@ -40,7 +47,6 @@ export function CpfTop({ field, buyer, onBuyerChange, copy, provider, onComplete
   const { Button, Checkbox, Input, Text } = useCheckoutComponents();
   const consent = usePaymentListMode()?.consent;
   const fieldCopy = useCheckoutCopy().card.fields;
-  const wide = useCheckoutLayout()?.wide ?? false;
   // The CPF the store already holds, when the host passed it, shown masked and editable.
   const value = formatCpf(buyer.taxId ?? "");
   useOnComplete(value.trim() !== "" && fieldSatisfied(field, value), onComplete);
@@ -50,7 +56,7 @@ export function CpfTop({ field, buyer, onBuyerChange, copy, provider, onComplete
   }, [focusOnMount]);
   const complaint = complaintOf(field, value, copy, (typed) => validateCpf(typed, fieldCopy));
   return (
-    <Box ref={scope} data-testid="list-cpf" sx={{ display: "flex", flexDirection: "column", gap: 1.25 }}>
+    <Box ref={scope} data-testid="list-cpf" sx={{ display: "flex", flexDirection: "column", gap: 1.5, containerType: "inline-size" }}>
       {/* A native <label> around the words and the field names the input with both. */}
       <Box component="label" sx={{ display: "flex", flexDirection: "column", gap: 0.75 }}>
         <Box component="span" sx={{ display: "flex", flexDirection: "column" }}>
@@ -61,7 +67,7 @@ export function CpfTop({ field, buyer, onBuyerChange, copy, provider, onComplete
             {copy.cpfHint(provider)}
           </Text>
         </Box>
-        <Box sx={{ width: "100%", maxWidth: (t) => (wide ? t.spacing(FIELD_WIDE_MAX) : "none") }}>
+        <Box data-testid="list-cpf-field" sx={(t) => ({ width: "100%", [`@container (min-width: ${FIELD_CAP_FROM_PX}px)`]: { maxWidth: t.spacing(FIELD_WIDE_MAX) } })}>
           <Input
             type="text"
             inputMode="numeric"
@@ -79,19 +85,25 @@ export function CpfTop({ field, buyer, onBuyerChange, copy, provider, onComplete
         </Box>
       </Box>
       {onKeepSaved && copy.keepSavedCpf ? (
-        <Box sx={{ alignSelf: "flex-start", ml: -1 }}>
-          <Button variant="text" color="primary" size="sm" onClick={onKeepSaved} dataTestId="list-cpf-keep">
+        // Flush with the field's left edge, in the neutral ink of a link that keeps
+        // what is on file — the brand's primary read as an error on a red-brown theme.
+        <Box sx={{ alignSelf: "flex-start", "& button": { textDecoration: "underline", px: 0, py: 0, minWidth: 0, minHeight: (t) => t.spacing(3) } }}>
+          <Button variant="text" color="neutral" size="sm" onClick={onKeepSaved} dataTestId="list-cpf-keep">
             {copy.keepSavedCpf}
           </Button>
         </Box>
       ) : null}
       {consent ? (
-        <Checkbox
-          label={consent.label}
-          checked={consent.checked}
-          onChange={(_event, checked) => consent.onChange(checked)}
-          data-testid="list-save-profile"
-        />
+        // Flush with the field: the box's own 9px ring and the label's negative inset
+        // (MUI's, under every kit built on it) pushed the words right until they wrapped on a phone.
+        <Box data-testid="list-save-profile-row" sx={{ "& .MuiFormControlLabel-root": { ml: 0, mr: 0 }, "& .MuiFormControlLabel-root .MuiCheckbox-root": { p: 0, mr: 1 } }}>
+          <Checkbox
+            label={consent.label}
+            checked={consent.checked}
+            onChange={(_event, checked) => consent.onChange(checked)}
+            data-testid="list-save-profile"
+          />
+        </Box>
       ) : null}
     </Box>
   );

package/src/components/checkout/list/credit-types.ts

@@ -0,0 +1,27 @@
+/**
+ * A balance the host holds paying part of the cart, as the "Resumo do pedido"
+ * column draws it (FUT-3711). Kept apart from `./types` only for that file's
+ * length; both are part of `CheckoutPaymentList` / `PaymentListCopy`.
+ */
+export interface PaymentListCredit {
+  /**
+   * The balance that pays part of the cart, as the host words and formats it
+   * — `{ label: "Crédito da loja", amountLabel: "− R$ 5,00" }`. With
+   * `amountDueLabel`, the computer's "Resumo do pedido" column draws it under
+   * "Total", then "A pagar" (`copy.amountDue`) and the amount due, so Total −
+   * credit reads as what the button charges — while an ONLINE option is
+   * chosen. A door option or no choice charges the cart's total, so "Total"
+   * stands alone. Absent ⇒ "Total" alone.
+   */
+  credit?: { label: string; amountLabel: string };
+}
+
+/** The words of the column's credit rows (FUT-3711). */
+export interface PaymentListCreditCopy {
+  /**
+   * "A pagar" — the row under "Total" in the computer's "Resumo do pedido"
+   * column, after the host's `credit` row, naming `amountDueLabel`. Absent ⇒
+   * neither row is drawn.
+   */
+  amountDue?: string;
+}

package/src/components/checkout/list/en-US.ts

@@ -64,6 +64,7 @@ export const EN_US_PAYMENT_LIST_COPY: PaymentListCopy = {
   payerChange: "Change",
   charging: (total, card) => `Paying ${total} with ${card ?? "the card entered"}…`,
   chargingCovered: "Confirming the order, paid with your balance…",
+  amountDue: "Amount due",
   cancel: "Cancel",
   pixFace: {
     title: (total) => `Pay ${total} with Pix`,

package/src/components/checkout/list/lazy-body.tsx

@@ -0,0 +1,118 @@
+import { Component, Suspense, lazy, type ComponentType, type JSX, type LazyExoticComponent, type ReactNode } from "react";
+
+import { useCheckoutComponents, type CheckoutLazy } from "../ui";
+
+/** What a part is rendered with to load it and draw nothing (`Preload`). */
+interface Probe {
+  readonly probe: true;
+}
+
+/** How long a part that failed to load waits before its one retry. */
+export const PART_RETRY_MS = 1000;
+
+/**
+ * Catches a part whose chunk failed to load (FUT-3711): draws `fallback` in
+ * its place — the rest of the list stays — and, with `retry` (the part's
+ * `useForget()`), forgets the failed load and tries ONCE more after
+ * {@link PART_RETRY_MS}, importing again rather than replaying the error. The
+ * retry suspends to a boundary of its own, never to one holding drawn rows.
+ */
+export class PartBoundary extends Component<{ fallback: ReactNode; retry?: () => void; children: ReactNode }, { failed: boolean; tries: number }> {
+  state = { failed: false, tries: 0 };
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true };
+  }
+
+  componentDidCatch(): void {
+    const { retry } = this.props;
+    if (!retry || this.state.tries > 0) return;
+    this.timer = setTimeout(() => {
+      retry();
+      this.setState({ failed: false, tries: 1 });
+    }, PART_RETRY_MS);
+  }
+
+  componentWillUnmount(): void {
+    if (this.timer) clearTimeout(this.timer);
+  }
+
+  render(): ReactNode {
+    const { fallback, children } = this.props;
+    if (this.state.failed) return fallback;
+    // A retry suspends here, on its own: the boundary above may hold what the
+    // first failure left on screen (the rows under the top), and hiding it
+    // while the part imports again would blink it out under a finger.
+    return this.state.tries > 0 ? <Suspense fallback={fallback}>{children}</Suspense> : children;
+  }
+}
+
+/** The part as loaded, answering a probe with nothing. */
+function probed<P extends object>(Part: ComponentType<P>): ComponentType<P | Probe> {
+  return function ProbedPart(props: P | Probe): JSX.Element | null {
+    return "probe" in props ? null : <Part {...(props as P)} />;
+  };
+}
+
+/** A part of the list loaded as a chunk of its own — see {@link deferredPart}. */
+interface DeferredPart<P extends object> {
+  /** The part, built through the host's loader; it suspends until its chunk has landed. */
+  usePart: () => LazyExoticComponent<ComponentType<P | Probe>>;
+  /** Drops this host loader's build, so the next render imports again — a `PartBoundary`'s `retry`. */
+  useForget: () => () => void;
+  /**
+   * Starts the part's load through the same loader, drawing nothing: render it
+   * as soon as the list knows it MAY draw the part, so the part is in hand
+   * when it does — and never suspends where it would push the rows down.
+   */
+  Preload: () => JSX.Element;
+}
+
+/**
+ * A part of the list loaded as a chunk of its own (FUT-3711), through the
+ * host's `lazy` slot — its stale-chunk-safe loader — or React's `lazy` when the
+ * host fills none.
+ *
+ * Each loader builds the deferred component ONCE and keeps it, keyed by the
+ * loader itself: a component made on every render would be a new type every
+ * render, remounting the part and suspending it again each time. A load that
+ * fails is dropped from that cache — by the import's own rejection, and by the
+ * part's `PartBoundary` retry for a failure in the host's loader around it —
+ * so the retry imports again instead of rethrowing a rejection kept forever.
+ */
+export function deferredPart<P extends object>(load: () => Promise<ComponentType<P>>): DeferredPart<P> {
+  const made = new WeakMap<CheckoutLazy, LazyExoticComponent<ComponentType<P | Probe>>>();
+  function build(loader: CheckoutLazy): LazyExoticComponent<ComponentType<P | Probe>> {
+    const part = loader(() =>
+      load().then(
+        (Part) => ({ default: probed(Part) }),
+        (error: unknown) => {
+          made.delete(loader);
+          throw error;
+        },
+      ),
+    );
+    made.set(loader, part);
+    return part;
+  }
+  function usePart(): LazyExoticComponent<ComponentType<P | Probe>> {
+    const loader = useCheckoutComponents().lazy ?? lazy;
+    return made.get(loader) ?? build(loader);
+  }
+  function useForget(): () => void {
+    const loader = useCheckoutComponents().lazy ?? lazy;
+    return () => made.delete(loader);
+  }
+  function Preload(): JSX.Element {
+    const Part = usePart();
+    return (
+      <PartBoundary fallback={null}>
+        <Suspense fallback={null}>
+          <Part probe />
+        </Suspense>
+      </PartBoundary>
+    );
+  }
+  return { usePart, useForget, Preload };
+}

package/src/components/checkout/list/list-bar.tsx

@@ -12,6 +12,12 @@ import { CHARGE_WINDOW_MS } from "./use-list-charge";
 const ACTION_HEIGHT = 6.5;
 const SECONDARY_HEIGHT = 5.5;
 
+/** A block the host handed that draws nothing takes no row, and so no gap (FUT-3711). */
+const NO_EMPTY_ROW = { "&:empty": { display: "none" } } as const;
+
+/** Read by a screen reader, drawn nowhere. */
+const VISUALLY_HIDDEN = { position: "absolute", width: "1px", height: "1px", overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" } as const;
+
 /** Focus the first button under `scope` — the slot owns the element, so it is found, not referenced. */
 function focusButtonIn(scope: HTMLElement | null): void {
   scope?.querySelector<HTMLButtonElement>("button")?.focus();
@@ -46,19 +52,19 @@ export function ListBar({ summary, extras, payer, reason, live, children }: {
   const column = useSummaryColumnTarget();
   const content = (
     <Box data-testid={column ? "list-pay-bar" : undefined} sx={{ display: "flex", flexDirection: "column", gap: 1, width: "100%", minWidth: 0 }}>
-      {summary ? <Box data-testid="list-bar-summary">{summary}</Box> : null}
-      {extras ? <Box data-testid="list-bar-extras">{extras}</Box> : null}
+      {/* The context line in the secondary ink in the column, as in the bar — the column inherits whatever the host's element is inked in. */}
+      {summary ? <Box data-testid="list-bar-summary" sx={{ ...NO_EMPTY_ROW, ...(column ? { color: "text.secondary" } : {}) }}>{summary}</Box> : null}
+      {extras ? <Box data-testid="list-bar-extras" sx={NO_EMPTY_ROW}>{extras}</Box> : null}
       {payer}
       {children}
-      <Box role="status" aria-live="polite" data-testid="list-bar-live">
+      {/* Out of the flow while it has nothing to show: an empty row still took a gap under the button. */}
+      <Box role="status" aria-live="polite" data-testid="list-bar-live" sx={reason ? undefined : VISUALLY_HIDDEN}>
         {reason ? (
           <Text variant="body" size="sm" color="danger" as="p" style={{ margin: 0 }} data-testid="list-blocked-reason">
             {reason}
           </Text>
         ) : (
-          <Box component="span" sx={{ position: "absolute", width: "1px", height: "1px", overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" }}>
-            {live ?? ""}
-          </Box>
+          <Box component="span">{live ?? ""}</Box>
         )}
       </Box>
     </Box>

package/src/components/checkout/list/list-face.tsx

@@ -16,7 +16,7 @@ import { OtherBankLink } from "./list-pix";
 import { ChoiceList } from "./choice-list";
 import { CardRun, WalletRun, type ListChargeFailure, type WalletSheet } from "./charge-runners";
 import { ActionButton, ChargeBar, ListBar } from "./list-bar";
-import { ListTop, gateFields, walletsHeld } from "./list-top";
+import { ListTop, TopAndRows, gateFields, walletsHeld } from "./list-top";
 import { PayerLine } from "./payer-line";
 import type { ListCapability } from "./use-capability";
 import type { ListCharge } from "./use-list-charge";
@@ -375,11 +375,14 @@ export function ListFace(props: ListFaceProps): JSX.Element {
   const { returnFocus, onCancel } = useCancelWithFocus(charge);
   const shown = charge.phase !== "waiting";
   const facts = barFacts(props, door, reason);
-  const top = <ListTop props={props} held={wallets.held} failure={wallets.failure} onGoogle={wallets.onGoogle} onApple={wallets.onApple} />;
+  const rowsShown = useRef(false);
+  const top = <ListTop props={props} held={wallets.held} failure={wallets.failure} onGoogle={wallets.onGoogle} onApple={wallets.onApple} rowsShown={rowsShown} />;
   return (
     <Box data-testid="payment-list-step" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
       {shown ? (
-        <ChoiceList copy={list.copy} state={state} door={list.door ?? []} buyer={c.buyer} onBuyerChange={c.setBuyer} provider={props.provider} failure={failure} locked={facts.locked} covered={coveredByHost(list)} top={top} />
+        <TopAndRows rowsShown={rowsShown}>
+          <ChoiceList copy={list.copy} state={state} door={list.door ?? []} buyer={c.buyer} onBuyerChange={c.setBuyer} provider={props.provider} failure={failure} locked={facts.locked} covered={coveredByHost(list)} top={top} />
+        </TopAndRows>
       ) : null}
       <Runners props={props} sheet={wallets.sheet.current} onFailed={onFailed} onWalletFailed={wallets.onFailed} />
       <RaiseError c={c} onRetry={() => act()} />

package/src/components/checkout/list/list-top-body.tsx

@@ -0,0 +1,40 @@
+import { Box } from "@mui/material";
+import { useRef, type JSX } from "react";
+
+import { CpfTop } from "./cpf-top";
+import type { ListTopInput } from "./list-top";
+import { cpfProvider } from "./top-cpf";
+import { WalletBlock } from "./wallet-block";
+
+/** Move the focus to "Número do cartão" — the next thing to type once the CPF is complete. */
+function focusCardNumber(scope: HTMLElement | null): void {
+  scope?.closest('[data-testid="payment-list"]')?.querySelector<HTMLInputElement>('input[data-testid="card-number"]')?.focus();
+}
+
+/**
+ * What the top of Pagamento draws (FUT-3685): the CPF field, then the
+ * "PAGAMENTO RÁPIDO" block — loaded only when `ListTop` decides there is one
+ * to draw (FUT-3711).
+ */
+export function ListTopBody({ props, held, failure, onGoogle, onApple }: ListTopInput): JSX.Element {
+  const scope = useRef<HTMLDivElement | null>(null);
+  const { list, state, cap, config, c } = props;
+  const typingCard = state.choice?.kind === "online" && state.choice.method === "CARD";
+  return (
+    <Box ref={scope} data-testid="list-top" sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
+      {state.top ? (
+        <CpfTop
+          field={state.top}
+          buyer={c.buyer}
+          onBuyerChange={c.setBuyer}
+          copy={list.copy.buyer}
+          provider={cpfProvider(config?.chain, state.methods)}
+          onComplete={typingCard ? () => focusCardNumber(scope.current) : undefined}
+          focusOnMount={props.revealed}
+          onKeepSaved={props.revealed ? props.onKeepSavedCpf : undefined}
+        />
+      ) : null}
+      <WalletBlock cap={cap} copy={list.copy} held={held} failure={failure} onGoogle={onGoogle} onApple={onApple} />
+    </Box>
+  );
+}

package/src/components/checkout/list/list-top.tsx

@@ -1,15 +1,14 @@
 import { Box } from "@mui/material";
-import { useRef, type JSX } from "react";
+import { Suspense, useEffect, useState, type JSX, type ReactNode } from "react";
 
 import type { BuyerInfo, CheckoutCustomerField, CheckoutProviderConfig, PaymentMethod } from "../types";
 
 import type { ListChargeFailure } from "./charge-runners";
-import { CpfTop } from "./cpf-top";
-import { cpfHolds, cpfProvider } from "./top-cpf";
+import { PartBoundary, deferredPart } from "./lazy-body";
+import { cpfHolds } from "./top-cpf";
 import type { CheckoutPaymentList } from "./types";
 import type { ListCapability } from "./use-capability";
 import type { ListState } from "./use-list-state";
-import { WalletBlock } from "./wallet-block";
 
 /**
  * The fields that hold the bar's button for the chosen online option, in the
@@ -46,13 +45,8 @@ export function walletsHeld(input: {
   return priced ? null : (list.copy.reasons.repricing ?? list.copy.reasons.choose);
 }
 
-/** Move the focus to "Número do cartão" — the next thing to type once the CPF is complete. */
-function focusCardNumber(scope: HTMLElement | null): void {
-  scope?.closest('[data-testid="payment-list"]')?.querySelector<HTMLInputElement>('input[data-testid="card-number"]')?.focus();
-}
-
 /** What the top of the list reads, gathered by the face. */
-interface ListTopFacts {
+export interface ListTopFacts {
   list: CheckoutPaymentList;
   state: ListState;
   cap: ListCapability;
@@ -63,37 +57,97 @@ interface ListTopFacts {
   onKeepSavedCpf: () => void;
 }
 
-/**
- * The top of Pagamento (FUT-3685): the CPF, asked once (E1, L7), then the
- * "PAGAMENTO RÁPIDO" block (C5, C6) — both above the rows.
- */
-export function ListTop({ props, held, failure, onGoogle, onApple }: {
+/** What the top of the list is handed by the face. */
+export interface ListTopInput {
   props: ListTopFacts;
   held: string | null;
   /** The last wallet charge's refusal, said under the buttons. */
   failure: ListChargeFailure | null;
   onGoogle: () => void;
   onApple: () => void;
-}): JSX.Element | null {
-  const scope = useRef<HTMLDivElement | null>(null);
-  const { list, state, cap, config, c } = props;
+  /** Whether the rows under the top have been drawn yet — set by the face once they are. */
+  rowsShown?: { readonly current: boolean };
+}
+
+/** The top's chunk (FUT-3711): `ListTop` draws it; the step preloads it (`TopPart.Preload`). */
+export const TopPart = deferredPart<ListTopInput>(async () => (await import("./list-top-body")).ListTopBody);
+
+/**
+ * The top of Pagamento (FUT-3685): the CPF, asked once (E1, L7), then the
+ * "PAGAMENTO RÁPIDO" block (C5, C6) — both above the rows.
+ *
+ * Only the decision to draw it is here; what it draws is a chunk of its own
+ * (FUT-3711), so a checkout with neither a CPF to ask nor a wallet ready never
+ * parses it. The step starts that chunk as soon as it mounts
+ * (`TopPart.Preload`). A top drawn with the list's first rows SUSPENDS to the
+ * boundary the face puts around the top AND the rows (`ChoiceList`): the two
+ * land together, so no row is pushed down under a finger. A top that appears
+ * once the rows are drawn suspends on its own and never hides them. A chunk that
+ * fails is caught here — the rows stay, nothing is drawn in the top's place,
+ * and it is tried once more. What the CPF holds — the pay button, the wallets
+ * — is decided in this file (`gateFields`, `walletsHeld`), so the hold is in
+ * force whether or not the field is on screen.
+ */
+export function ListTop(input: ListTopInput): JSX.Element | null {
+  const { state, cap } = input.props;
   if (!state.top && cap.wallets.length === 0) return null;
-  const typingCard = state.choice?.kind === "online" && state.choice.method === "CARD";
+  return <TopWithRetry {...input} />;
+}
+
+/**
+ * The top behind its own boundary: a failed chunk draws nothing there, then is
+ * tried once more. A top that first appears AFTER the rows are on screen — a
+ * wallet that turned ready, a CPF opened by "Alterar" — also suspends on its
+ * own (nothing drawn while it loads), so it can never hide rows already drawn.
+ * Decided once, when the top mounts: a boundary that came and went would
+ * remount what is under it.
+ */
+function TopWithRetry(input: ListTopInput): JSX.Element {
+  const forget = TopPart.useForget();
+  const [late] = useState(() => input.rowsShown?.current === true);
+  const top = <DeferredTop {...input} />;
+  return (
+    <PartBoundary fallback={null} retry={forget}>
+      {late ? <Suspense fallback={<TopLoading />}>{top}</Suspense> : top}
+    </PartBoundary>
+  );
+}
+
+/** The top's chunk, asked of the host's loader only once there is a top to draw. */
+function DeferredTop(input: ListTopInput): JSX.Element {
+  const Body = TopPart.usePart();
+  return <Body {...input} />;
+}
+
+/**
+ * What the top and the rows show while the top's chunk is on its way: nothing
+ * — an undrawn `list-top-loading` marker a test can wait on (`display: none`
+ * takes no row and no gap). The bar under them is not inside the boundary, so
+ * its button keeps its place and its hold.
+ */
+function TopLoading(): JSX.Element {
+  return <Box data-testid="list-top-loading" sx={{ display: "none" }} />;
+}
+
+/** Marks the rows as drawn once they commit — a top appearing after that suspends on its own. */
+function RowsShown({ into }: { into: { current: boolean } }): null {
+  useEffect(() => {
+    into.current = true;
+  }, [into]);
+  return null;
+}
+
+/**
+ * The top and the rows under ONE boundary (FUT-3711): a top drawn with the
+ * first rows lands with them, so its chunk never pushes a row down. Once the
+ * rows have committed, `rowsShown` says so, and a top that appears later
+ * suspends on its own instead (`TopWithRetry`).
+ */
+export function TopAndRows({ rowsShown, children }: { rowsShown: { current: boolean }; children: ReactNode }): JSX.Element {
   return (
-    <Box ref={scope} data-testid="list-top" sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
-      {state.top ? (
-        <CpfTop
-          field={state.top}
-          buyer={c.buyer}
-          onBuyerChange={c.setBuyer}
-          copy={list.copy.buyer}
-          provider={cpfProvider(config?.chain, state.methods)}
-          onComplete={typingCard ? () => focusCardNumber(scope.current) : undefined}
-          focusOnMount={props.revealed}
-          onKeepSaved={props.revealed ? props.onKeepSavedCpf : undefined}
-        />
-      ) : null}
-      <WalletBlock cap={cap} copy={list.copy} held={held} failure={failure} onGoogle={onGoogle} onApple={onApple} />
-    </Box>
+    <Suspense fallback={<TopLoading />}>
+      {children}
+      <RowsShown into={rowsShown} />
+    </Suspense>
   );
 }

package/src/components/checkout/list/option-row.tsx

@@ -35,6 +35,9 @@ const FIELDS_ON_SURFACE = {
   },
 } as const;
 
+/** The small radio (20px) centred on the title's 24px line. */
+const RADIO_ON_TITLE = 0.25;
+
 /** The row's label and its muted hint, beside the radio. */
 function RowWords({ label, hint }: { label: string; hint?: string }): JSX.Element {
   const { Text } = useCheckoutComponents();
@@ -114,8 +117,9 @@ export function OptionRow({
         // The prototype's `.opt` padding, 12px above and below the label and its
         // hint (FUT-3685 review): a row with a hint is ~62px, and the hint never
         // touches — or is clipped by — the row's border. 48px is the floor, for
-        // a row with no hint.
-        sx={{ display: "flex", alignItems: "center", gap: 1.5, minHeight: (t) => t.spacing(6), py: 1.5, cursor: disabled ? "default" : "pointer" }}
+        // a row with no hint. The radio sits on the TITLE's line, not centred on
+        // title and hint together — a wrapped hint no longer drags it down (FUT-3711).
+        sx={{ display: "flex", alignItems: "flex-start", gap: 1.5, minHeight: (t) => t.spacing(6), py: 1.5, boxSizing: "border-box", cursor: disabled ? "default" : "pointer" }}
       >
         <Radio
           name={name}
@@ -124,7 +128,7 @@ export function OptionRow({
           disabled={disabled}
           onChange={onChoose}
           size="small"
-          sx={{ p: 0, flex: "none" }}
+          sx={{ p: 0, flex: "none", mt: RADIO_ON_TITLE }}
           inputProps={{ "data-testid": `${testId}-radio` } as Record<string, string>}
         />
         <RowWords label={label} hint={hint} />

package/src/components/checkout/list/payer-line.tsx

@@ -26,7 +26,9 @@ export function PayerLine({ copy, name, onChange }: {
       </Text>
       <Box
         sx={{
-          "& button": { textDecoration: "underline", minHeight: (t) => t.spacing(5), minWidth: 0, px: 0.5, py: 0 },
+          // The 40px target reaches into the gaps above and below rather than making the
+          // line 40px tall: a row of text in the bar, not a row of button (FUT-3711).
+          "& button": { textDecoration: "underline", minHeight: (t) => t.spacing(5), height: (t) => t.spacing(5), minWidth: 0, px: 0.5, py: 0, my: -1 },
           "& button:focus-visible": { outline: (t) => `${t.spacing(0.25)} solid ${t.palette.primary.main}`, outlineOffset: (t) => t.spacing(0.25) },
         }}
       >

package/src/components/checkout/list/payment-list-step.tsx

@@ -15,11 +15,12 @@ import type { useCheckoutController } from "../use-checkout-controller";
 import { PaymentListProvider } from "./context";
 import { ListBar, WaitingLine } from "./list-bar";
 import { ListFace } from "./list-face";
+import { TopPart } from "./list-top";
 import { ListLayout } from "./summary-column";
 import type { ListCapability } from "./use-capability";
 import type { ListCharge } from "./use-list-charge";
 import type { ListState } from "./use-list-state";
-import type { CheckoutPaymentList } from "./types";
+import type { CheckoutListChoice, CheckoutPaymentList } from "./types";
 import { useListCapability } from "./use-capability";
 import { useListCharge } from "./use-list-charge";
 import { useListState } from "./use-list-state";
@@ -155,6 +156,32 @@ function useDebitReady(list: CheckoutPaymentList): boolean {
   return Boolean(list.billingAddress) && list.copy.debit !== undefined && client.threeDSecureSession !== undefined;
 }
 
+/**
+ * Starts the top's chunk the moment the list knows it MAY draw a top
+ * (FUT-3711): a CPF to ask, a wallet the chain head DECLARES (readiness —
+ * pay.js, the device, the host's price — arrives only after the first
+ * render), or a CPF on file that "Alterar" can open. So the top is in hand
+ * when it is drawn.
+ */
+function PreloadTop({ state, cap, config, taxIdOnFile }: { state: ListState; cap: ListCapability; config: CheckoutProviderConfig | null; taxIdOnFile: boolean }): JSX.Element | null {
+  const declared = (config?.chain?.[0]?.wallets?.length ?? 0) > 0;
+  if (!state.top && cap.wallets.length === 0 && !declared && !taxIdOnFile) return null;
+  return <TopPart.Preload />;
+}
+
+/**
+ * The column's credit and "A pagar" rows (FUT-3711) — only with all three of
+ * the host's credit, amount due and words, and only while an ONLINE option is
+ * chosen: that is the only time the button charges the amount due. A door
+ * option or no choice charges the cart's total, so "Total" stands alone — a
+ * balance the host holds pays no door tender.
+ */
+function creditRows(list: CheckoutPaymentList, choice: CheckoutListChoice | null): { label: string; amountLabel: string; dueTitle: string; dueLabel: string } | undefined {
+  if (choice?.kind !== "online") return undefined;
+  if (!list.credit || !list.amountDueLabel || !list.copy.amountDue) return undefined;
+  return { ...list.credit, dueTitle: list.copy.amountDue, dueLabel: list.amountDueLabel };
+}
+
 /**
  * The Pagamento step as ONE list (FUT-3591, FUT-3592) — see `./types.ts`.
  *
@@ -201,6 +228,7 @@ export function PaymentListStep(props: PaymentListStepProps): JSX.Element {
       lines={props.totalOverride ? undefined : props.cart.lines}
       moneyLines={props.cart.discountLines}
       totalLabel={displayTotals(props.totalOverride, props.cart).label}
+      credit={creditRows(list, state.choice)}
     >
       <ListFaceFor props={props} state={state} charge={charge} cap={cap} onHandOff={startHandOff} reveal={reveal} />
     </ListLayout>
@@ -208,6 +236,7 @@ export function PaymentListStep(props: PaymentListStepProps): JSX.Element {
   return (
     <PaymentListProvider list={list} onLeavePix={c.dropOrder} consent={consent}>
       <PixStageProvider stage={pixStage}>
+        <PreloadTop state={state} cap={cap} config={config} taxIdOnFile={props.taxIdOnFile} />
         <CartChangedBoundary
           order={c.order}
           creating={c.creating}

package/src/components/checkout/list/pt-BR.ts

@@ -80,6 +80,7 @@ export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
   payerChange: "Alterar",
   charging: (total, card) => `Pagando ${total} no ${card ?? "cartão informado"}…`,
   chargingCovered: "Confirmando o pedido, pago com o seu saldo…",
+  amountDue: "A pagar",
   cancel: "Cancelar",
   pixFace: {
     title: (total) => `Pague ${total} com Pix`,

package/src/components/checkout/list/summary-column-body.tsx

@@ -0,0 +1,61 @@
+import { Box } from "@mui/material";
+import type { JSX, ReactNode } from "react";
+
+import { SummaryLines, SummaryTotal, type CheckoutSummaryLine } from "../payment-summary";
+import { useCheckoutComponents } from "../ui";
+
+/** What the loaded half of "Resumo do pedido" is handed by the layout. */
+export interface ColumnBodyProps {
+  lines?: CheckoutSummaryLine[];
+  /** The host's fee and discount rows (`CheckoutCartView.discountLines`). */
+  moneyLines?: ReactNode;
+  totalLabel: string;
+  /**
+   * A balance paying part of the cart, and what is left to pay (FUT-3711):
+   * drawn under "Total" so Total − credit reads as what the button charges.
+   */
+  credit?: { label: string; amountLabel: string; dueTitle: string; dueLabel: string };
+}
+
+/** One label/amount row under "Total". */
+function AmountRow({ label, amount, strong = false, testId }: { label: string; amount: string; strong?: boolean; testId: string }): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const weight = strong ? "semibold" : undefined;
+  return (
+    <Box data-testid={testId} sx={{ display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: 2 }}>
+      <Text variant="body" size={strong ? "md" : "sm"} weight={weight} color={strong ? undefined : "secondary"} as="span">
+        {label}
+      </Text>
+      <Box component="span" sx={{ flex: "none", whiteSpace: "nowrap" }}>
+        <Text variant="body" size={strong ? "md" : "sm"} weight={weight} color={strong ? undefined : "secondary"} as="span">
+          {amount}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * What "Resumo do pedido" loads (T20, FUT-3711): the cart's lines and the
+ * host's money rows (fees, discounts) as the host words them, a hairline,
+ * "Total" and the amount, and the credit and "A pagar" rows. The frame, the
+ * heading and the pay-button slot under them are the layout's own — eager —
+ * so the bar's content never changes element when this lands.
+ */
+export function SummaryBody({ lines, moneyLines, totalLabel, credit }: ColumnBodyProps): JSX.Element {
+  const shown = lines ?? [];
+  return (
+    <Box data-testid="list-summary-body" sx={{ display: "flex", flexDirection: "column", gap: 1.75 }}>
+      {shown.length > 0 ? <SummaryLines lines={shown} /> : null}
+      {moneyLines ? <Box data-testid="list-summary-money">{moneyLines}</Box> : null}
+      <Box sx={{ height: "1px", bgcolor: "divider" }} />
+      <SummaryTotal totalLabel={totalLabel} />
+      {credit ? (
+        <Box data-testid="list-summary-credit" sx={{ display: "flex", flexDirection: "column", gap: 0.75 }}>
+          <AmountRow label={credit.label} amount={credit.amountLabel} testId="list-summary-credit-row" />
+          <AmountRow label={credit.dueTitle} amount={credit.dueLabel} strong testId="list-summary-due-row" />
+        </Box>
+      ) : null}
+    </Box>
+  );
+}

package/src/components/checkout/list/summary-column.tsx

@@ -1,12 +1,15 @@
 import { Box } from "@mui/material";
-import { createContext, useContext, useMemo, useState, type JSX, type ReactNode } from "react";
+import { Suspense, createContext, useContext, useMemo, useState, type JSX, type ReactNode } from "react";
 import { createPortal } from "react-dom";
 
 import { useCheckoutCopy } from "../copy-context";
-import { SummaryLines, SummaryTotal, type CheckoutSummaryLine } from "../payment-summary";
+import type { CheckoutSummaryLine } from "../payment-summary";
 import { useCheckoutLayout } from "../payment-step-layout";
 import { useCheckoutComponents } from "../ui";
 
+import { PartBoundary, deferredPart } from "./lazy-body";
+import type { ColumnBodyProps } from "./summary-column-body";
+
 /**
  * Where the bar's content goes on a computer (FUT-3685, L4): into the
  * "Resumo do pedido" column — an element the column draws, which the bar's
@@ -30,36 +33,28 @@ export function useSummaryColumnTarget(): { element: HTMLElement | null } | null
 const STEPS_MAX = 85;
 const COLUMN_WIDTH = 45;
 
-/**
- * The computer's two columns (L4): the steps on the left, at most ~680px, and
- * the "Resumo do pedido" column on the right, ~360px, holding the lines, the
- * fees, "Total", the host's context line and the pay button — so no bar sits
- * at the bottom of the screen.
- */
-function TwoColumns({ steps, column }: { steps: ReactNode; column: ReactNode }): JSX.Element {
-  return (
-    <Box data-testid="list-columns" sx={{ display: "flex", gap: 4, alignItems: "flex-start", justifyContent: "center", width: "100%" }}>
-      <Box sx={{ flex: 1, minWidth: 0, maxWidth: (t) => t.spacing(STEPS_MAX) }}>{steps}</Box>
-      <Box sx={{ flex: "none", width: (t) => t.spacing(COLUMN_WIDTH), position: "sticky", top: (t) => t.spacing(3) }}>{column}</Box>
-    </Box>
-  );
+/** The column's loaded half (FUT-3711): lines, money rows, "Total", the credit rows. */
+const ColumnPart = deferredPart<ColumnBodyProps>(async () => (await import("./summary-column-body")).SummaryBody);
+
+/** The loaded half, drawn through the host's loader. */
+function DeferredBody(props: ColumnBodyProps): JSX.Element {
+  const Body = ColumnPart.usePart();
+  return <Body {...props} />;
 }
 
 /**
- * "Resumo do pedido" (T20): the cart's lines and the host's money rows (fees,
- * discounts) as the host words them, a hairline, "Total" and the amount — and
- * under them `slot`, the element the bar's content is portalled into.
+ * "Resumo do pedido" (T20). The frame, the heading and the pay-button slot are
+ * drawn at once and never change element (FUT-3711): the bar's content is
+ * portalled into that ONE slot from the first render, so the body landing —
+ * lines, money rows, "Total" — moves nothing out from under it (the focus on
+ * "Pagar", the host's extras, a 5-second bar counting). Only the body is a
+ * chunk of its own, which a phone never draws and so never parses; a body that
+ * fails to load leaves the frame and the button, and is tried once more.
  */
-function SummaryColumn({ lines, moneyLines, totalLabel, slot }: {
-  lines?: CheckoutSummaryLine[];
-  /** The host's fee and discount rows (`CheckoutCartView.discountLines`). */
-  moneyLines?: ReactNode;
-  totalLabel: string;
-  slot: (element: HTMLElement | null) => void;
-}): JSX.Element {
+function SummaryColumn({ slot, ...body }: ColumnBodyProps & { slot: (element: HTMLElement | null) => void }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.layout;
-  const shown = lines ?? [];
+  const forget = ColumnPart.useForget();
   return (
     <Box
       component="aside"
@@ -70,10 +65,11 @@ function SummaryColumn({ lines, moneyLines, totalLabel, slot }: {
       <Text variant="heading" size="md" weight="bold" as="h2" style={{ margin: 0 }}>
         {copy.summaryTitle}
       </Text>
-      {shown.length > 0 ? <SummaryLines lines={shown} /> : null}
-      {moneyLines ? <Box data-testid="list-summary-money">{moneyLines}</Box> : null}
-      <Box sx={{ height: "1px", bgcolor: "divider" }} />
-      <SummaryTotal totalLabel={totalLabel} />
+      <PartBoundary fallback={null} retry={forget}>
+        <Suspense fallback={<Box data-testid="list-summary-loading" sx={{ display: "none" }} />}>
+          <DeferredBody {...body} />
+        </Suspense>
+      </PartBoundary>
       <Box ref={slot} data-testid="list-summary-action" sx={{ display: "flex", flexDirection: "column" }} />
     </Box>
   );
@@ -86,35 +82,61 @@ function SummaryColumn({ lines, moneyLines, totalLabel, slot }: {
  *    the "Resumo do pedido" column is portalled into the host's element, beside
  *    the host's own step cards, and the bar's action lands in it. While the
  *    element is `null` (not mounted yet) the bar draws nothing rather than flash;
- *  - a computer, the host silent: the step and the column side by side, here;
+ *  - a computer, the host silent: the step and the column side by side, here —
+ *    the steps at most ~680px, the column ~360px and sticky;
  *  - a phone: the step alone, over the host's bar (L2).
  *
+ * The step sits at the SAME place in the tree in all three (FUT-3711): the
+ * same two wrappers, only their styles and the column beside them change. A
+ * host crossing its two-column threshold (an iPad rotated between 1366 and
+ * 1024) or the frame crossing `WIDE_CHECKOUT_MIN` re-lays the step out — it
+ * never remounts it, so a typed card and the chosen row survive.
+ *
  * Only the list face is laid out this way: the Pix screen and the hand-off keep
  * their bar (K9).
  */
-export function ListLayout({ hostTarget, lines, moneyLines, totalLabel, children }: {
+export function ListLayout({ hostTarget, lines, moneyLines, totalLabel, credit, children }: {
   hostTarget: HTMLElement | null | undefined;
   lines?: CheckoutSummaryLine[];
   moneyLines?: ReactNode;
   totalLabel: string;
+  credit?: ColumnBodyProps["credit"];
   children: ReactNode;
 }): JSX.Element {
   const wide = useCheckoutLayout()?.wide ?? false;
   const [slot, setSlot] = useState<HTMLElement | null>(null);
   const target = useMemo(() => ({ element: slot }), [slot]);
-  const column = <SummaryColumn lines={lines} moneyLines={moneyLines} totalLabel={totalLabel} slot={setSlot} />;
-  if (hostTarget !== undefined) {
-    return (
-      <SummaryColumnTarget value={target}>
-        {children}
-        {hostTarget ? createPortal(column, hostTarget) : null}
-      </SummaryColumnTarget>
-    );
-  }
-  if (!wide) return <>{children}</>;
+  const hosted = hostTarget !== undefined;
+  const sideBySide = !hosted && wide;
+  const column = <SummaryColumn lines={lines} moneyLines={moneyLines} totalLabel={totalLabel} credit={credit} slot={setSlot} />;
   return (
-    <SummaryColumnTarget value={target}>
-      <TwoColumns steps={children} column={column} />
+    <SummaryColumnTarget value={hosted || sideBySide ? target : null}>
+      <Columns sideBySide={sideBySide} column={column}>
+        {children}
+      </Columns>
+      {hostTarget ? createPortal(column, hostTarget) : null}
     </SummaryColumnTarget>
   );
 }
+
+/** Not laid out: the wrappers stay in the tree, drawing nothing. */
+const UNLAID = { display: "contents" } as const;
+
+/**
+ * The step, and beside it on a computer the column: the steps at most ~680px,
+ * the column ~360px and sticky. On a phone or beside the host's own columns
+ * the same two wrappers are kept, unlaid, so the step never changes place.
+ */
+function Columns({ sideBySide, column, children }: { sideBySide: boolean; column: ReactNode; children: ReactNode }): JSX.Element {
+  return (
+    <Box
+      data-testid={sideBySide ? "list-columns" : undefined}
+      sx={sideBySide ? { display: "flex", gap: 4, alignItems: "flex-start", justifyContent: "center", width: "100%" } : UNLAID}
+    >
+      <Box sx={sideBySide ? { flex: 1, minWidth: 0, maxWidth: (t) => t.spacing(STEPS_MAX) } : UNLAID}>{children}</Box>
+      {sideBySide ? (
+        <Box sx={{ flex: "none", width: (t) => t.spacing(COLUMN_WIDTH), position: "sticky", top: (t) => t.spacing(3) }}>{column}</Box>
+      ) : null}
+    </Box>
+  );
+}

package/src/components/checkout/list/types.ts

@@ -5,8 +5,7 @@
  * the only thing that creates the order and the charge.
  *
  * Opt-in, through `CheckoutFlowProps.paymentList`. A host that passes nothing
- * keeps the method tabs, the order summary and the raise-on-pick it has today
- * — this is additive, not a replacement.
+ * keeps the method tabs, the order summary and the raise-on-pick it has today — this is additive.
  *
  * ## The door options are the HOST's
  *
@@ -20,6 +19,7 @@
  */
 import type { ReactNode } from "react";
 
+import type { PaymentListCredit, PaymentListCreditCopy } from "./credit-types";
 import type { CheckoutBillingAddress, PaymentListDebitCopy } from "./debit-copy";
 
 export type { CheckoutBillingAddress, PaymentListDebitCopy };
@@ -121,7 +121,7 @@ export interface CheckoutListHold {
 }
 
 /** `CheckoutFlowProps.paymentList` — see the module comment. */
-export interface CheckoutPaymentList {
+export interface CheckoutPaymentList extends PaymentListCredit {
   /** Every sentence the list draws. REQUIRED, with no default (FUT-760). */
   copy: PaymentListCopy;
   /**
@@ -282,7 +282,7 @@ export interface PixBankCopy {
 }
 
 /** The list's words — a pack per locale ships at `@12-apps/payments-frontend/locales`. */
-export interface PaymentListCopy {
+export interface PaymentListCopy extends PaymentListCreditCopy {
   /** "Como você quer pagar?" */
   title: string;
   /** "Pagar agora, pelo app" — drawn in capitals by CSS. */

package/src/components/checkout/list/use-list-state.ts

@@ -30,6 +30,12 @@ export interface ListCard {
 /** Everything the one list holds, and nothing it raises. */
 export interface ListState {
   rows: OnlineRow[];
+  /**
+   * The saved cards answered and the one preselection ran (FUT-3849). Until
+   * then nothing may be offered to tap: the preselected card opens its chips
+   * when it lands and moves every row below it, under the buyer's finger.
+   */
+  settled: boolean;
   choice: CheckoutListChoice | null;
   choose: (next: CheckoutListChoice) => void;
   card: ListCard;
@@ -71,14 +77,19 @@ function usePreselect(
   lastMethod: "PIX" | "CARD" | null,
   apply: (choice: CheckoutListChoice, selection: string | null) => void,
   touched: { current: boolean },
-): void {
+): boolean {
   const done = useRef(false);
+  // Set in the same effect as the preselection, so the render that first
+  // draws the rows already holds the choice they will keep.
+  const [settled, setSettled] = useState(false);
   useEffect(() => {
     if (done.current || touched.current || !loaded) return;
     done.current = true;
     const pick = preselection(rows, saved, fresh, lastMethod);
     if (pick) apply(pick.choice, pick.selection);
+    setSettled(true);
   }, [loaded, rows, saved, fresh, lastMethod, apply, touched]);
+  return settled;
 }
 
 /**
@@ -147,7 +158,7 @@ export function useListState(input: {
     },
     [setSelection],
   );
-  usePreselect(loaded, rows, cards, input.fresh, input.lastMethod ?? null, apply, touched);
+  const settled = usePreselect(loaded, rows, cards, input.fresh, input.lastMethod ?? null, apply, touched);
   const choose = useCallback(
     (next: CheckoutListChoice) => {
       touched.current = true;
@@ -195,7 +206,7 @@ export function useListState(input: {
       }),
     [input.config, methods, input.arrivedWith, input.taxIdOnFile, input.revealed],
   );
-  return { rows, choice, choose, card, asked, top, methods };
+  return { rows, settled, choice, choose, card, asked, top, methods };
 }
 
 /** The chain methods the list's rows and wallets would raise, each once. */

package/src/components/checkout/ui.tsx

@@ -15,7 +15,7 @@
  * mapping. The contract is documented for adopters in
  * `packages/payments/ADOPTING.md` §3.
  */
-import { createContext, useContext, useMemo, type ChangeEvent, type ComponentType, type CSSProperties, type JSX, type ReactNode } from 'react';
+import { createContext, useContext, useMemo, type ChangeEvent, type ComponentType, type CSSProperties, type JSX, type lazy, type ReactNode } from 'react';
 
 import { defaultCheckoutComponents } from './mui-defaults';
 
@@ -127,6 +127,22 @@ export interface CheckoutActionBarProps {
   dataTestId?: string;
 }
 
+/**
+ * How the checkout defers a part of a screen to a chunk of its own
+ * (FUT-3711): React's `lazy` signature, `(factory) => Component`. The list
+ * loads the CPF/wallet block above its rows and the computer's "Resumo do
+ * pedido" column through it, so a checkout that never draws them never parses
+ * them.
+ *
+ * A host whose deploys replace hashed chunks passes its stale-chunk-safe
+ * loader here (one that reloads onto the current build when an old tab asks
+ * for a chunk that is gone). Pass the SAME function every render: each loader
+ * builds its deferred components once and keeps them, so a new function per
+ * render re-suspends those parts every time. Unfilled, the default is
+ * React's own `lazy`, which has no stale-chunk recovery.
+ */
+export type CheckoutLazy = typeof lazy;
+
 /** Every primitive the buyer checkout renders through. */
 export interface CheckoutComponents {
   Text: ComponentType<CheckoutTextProps>;
@@ -138,6 +154,8 @@ export interface CheckoutComponents {
   Stepper: ComponentType<CheckoutStepperProps>;
   RadioGroup: ComponentType<CheckoutRadioGroupProps>;
   ActionBar: ComponentType<CheckoutActionBarProps>;
+  /** Not a primitive but a loader — see `CheckoutLazy`. Absent ⇒ React's `lazy`. */
+  lazy?: CheckoutLazy;
 }
 
 const CheckoutComponentsContext = createContext<CheckoutComponents>(defaultCheckoutComponents);

package/src/index.ts

@@ -190,6 +190,7 @@ export {
   type CheckoutCheckboxProps,
   type CheckoutComponents,
   type CheckoutInputProps,
+  type CheckoutLazy,
   type CheckoutLoadingStateProps,
   type CheckoutRadioGroupProps,
   type CheckoutRadioOption,
@@ -206,11 +207,7 @@ export {
  * host owns the cart and therefore has to build it — see `basket.ts` for why
  * the identity is the lines and never the cart's id.
  */
-export {
-  basketSignature,
-  type CheckoutBasketIdentity,
-  type CheckoutBasketLine,
-} from './components/checkout/basket';
+export { basketSignature, type CheckoutBasketIdentity, type CheckoutBasketLine } from './components/checkout/basket';
 /**
  * WHY a card was refused, and whether another attempt could work (FUT-1145).
  * A host wiring the confirmation screen's per-reason copy names these.