@12-apps/payments-frontend 1.7.0 → 1.8.0

package/src/components/checkout/types.ts

@@ -198,6 +198,17 @@ export interface ChargeCardInput {
   taxId?: string;
 }
 
+/** A buyer field a provider asks for, as `/config` publishes it (FUT-595). */
+export interface CheckoutCustomerField {
+  key: "name" | "email" | "taxId" | "phone";
+  /** Which validation rule applies. `MOBILE` is the strictly narrower `PHONE`. */
+  type: "NAME" | "EMAIL" | "PHONE" | "MOBILE" | "CPF";
+  /** The provider refuses (or its own page stalls) without this field. */
+  required: boolean;
+  /** Methods this spec applies to; omitted means every method the adapter takes. */
+  methods?: ("PIX" | "CARD" | "BOLETO")[];
+}
+
 /**
  * ONE enabled provider of the store's chain (FUT-563), as the buyer's config
  * answers it. The same protocol facts as the head, stated per provider —
@@ -209,6 +220,22 @@ export interface CheckoutChainLink {
   publicKey: string | null;
   mockTokenization: boolean;
   methods: ("PIX" | "CARD" | "BOLETO")[];
+  /**
+   * What this provider needs to know about the buyer (FUT-595).
+   *
+   * `GET /api/checkout/config` has published this since FUT-740; this mirror
+   * type simply dropped it, so the buyer form could not be honest about what
+   * the chain requires and a missing field was only discoverable as a 400 AFTER
+   * the buyer had finished filling it in — the third FUT-740 critical, one
+   * layer up.
+   *
+   * Optional, and the DEGRADE DIRECTION IS LOAD-BEARING: absent (an older host,
+   * a hand-written config) must mean today's behaviour — CPF required — never
+   * "this chain asks for nothing". Asking for nothing produces a form the buyer
+   * completes and a charge the server then refuses for a document they were
+   * never shown a field for.
+   */
+  customerSchema?: CheckoutCustomerField[];
 }
 
 /**

package/src/components/checkout/ui.tsx

@@ -145,7 +145,18 @@ const CheckoutComponentsContext = createContext<CheckoutComponents>(defaultCheck
 /**
  * Fills the checkout's component slots for everything rendered beneath it.
  * Partial on purpose: a host overrides only the slots its design system
- * covers and inherits the raw-MUI default for the rest.
+ * covers and inherits the rest.
+ *
+ * Inherits from the NEAREST provider above, not from the raw-MUI defaults.
+ * That distinction is the whole contract once these nest — and they do nest:
+ * `createPaymentFlows` fills the slots once at the factory, and the
+ * `CheckoutFlow` inside its mount opens a provider of its own. Merging over
+ * the defaults there re-imposed raw MUI on a host that had already stated its
+ * design system, silently, one level in. Merging over the inherited set makes
+ * a nested provider ADD to what is above it, which is what "partial" has to
+ * mean for the surface to agree with itself. The context's own default is
+ * still `defaultCheckoutComponents`, so the outermost provider is unchanged:
+ * an unfilled slot is raw MUI exactly as before.
  */
 export function CheckoutComponentsProvider({
   components,
@@ -154,9 +165,10 @@ export function CheckoutComponentsProvider({
   components?: Partial<CheckoutComponents>;
   children: ReactNode;
 }): JSX.Element {
+  const inherited = useCheckoutComponents();
   const value = useMemo<CheckoutComponents>(
-    () => ({ ...defaultCheckoutComponents, ...components }),
-    [components],
+    () => ({ ...inherited, ...components }),
+    [inherited, components],
   );
   return (
     <CheckoutComponentsContext.Provider value={value}>

package/src/components/checkout/use-card-checkout.ts

@@ -17,13 +17,14 @@ import {
 } from "../../card";
 import { ok, type Result } from "../../result";
 
-import { resolveNewCardToken, type CardInstruments } from "./card-instruments";
 import {
-  chargeCard,
-  listSavedCards,
-  refreshCardPublicKey,
-} from "./client";
+  resolveNewCardToken,
+  type CardInstruments,
+  type RefreshBrowserKey,
+} from "./card-instruments";
+import { useCheckoutClientApi } from "./client-context";
 import { rememberHostedOrder } from "./hosted-return";
+import { useCheckoutNavigate, type CheckoutNavigate } from "./navigate-context";
 import type { CardChainLink } from "./method-capability";
 import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
 import { usePaymentPolling } from "./use-payment-polling";
@@ -43,10 +44,11 @@ function useSavedCards(tenantSlug: string | undefined): {
 } {
   const [savedCards, setSavedCards] = useState<SavedCard[]>([]);
   const [selection, setSelection] = useState<string>(NEW_CARD);
+  const client = useCheckoutClientApi();
 
   useEffect(() => {
     let active = true;
-    void listSavedCards(tenantSlug).then((cards) => {
+    void client.listInstruments(tenantSlug).then((cards) => {
       if (!active) return;
       setSavedCards(cards);
       const first = cards[0];
@@ -55,7 +57,7 @@ function useSavedCards(tenantSlug: string | undefined): {
     return () => {
       active = false;
     };
-  }, [tenantSlug]);
+  }, [tenantSlug, client]);
 
   return { savedCards, selection, setSelection };
 }
@@ -76,19 +78,20 @@ function useCardPublicKey(
   setPublicKey: (key: string) => void;
 } {
   const [publicKey, setPublicKey] = useState<string | null>(config.publicKey);
+  const client = useCheckoutClientApi();
   const refreshable =
     config.provider !== null && tokenizerFor(config.provider) === "pagbank-sdk";
 
   useEffect(() => {
     if (config.publicKey !== null || !refreshable) return undefined;
     let active = true;
-    void refreshCardPublicKey({ orderId }).then((result) => {
+    void client.refreshBrowserKey({ orderId }).then((result) => {
       if (active && result.ok && result.data.publicKey) setPublicKey(result.data.publicKey);
     });
     return () => {
       active = false;
     };
-  }, [orderId, config.publicKey, refreshable]);
+  }, [orderId, config.publicKey, refreshable, client]);
 
   return { publicKey, setPublicKey };
 }
@@ -151,9 +154,16 @@ const CARD_AWAITING_POLL_CAP = 36;
  * redirect provider's link takes (FUT-556): the return lands back on this
  * checkout route, where the hosted-resume machinery polls the parked order.
  */
-function handOverToChallenge(order: CheckoutOrder, url: string): void {
+function handOverToChallenge(
+  order: CheckoutOrder,
+  url: string,
+  navigate: CheckoutNavigate,
+): void {
+  // PARK FIRST. The navigation may not come back to a live SPA at all, and a
+  // return trip that finds nothing parked lands the buyer on a blank
+  // confirmation after they have paid.
   rememberHostedOrder(order);
-  window.location.assign(url);
+  navigate(url);
 }
 
 /** The buyer's card is invalid — block the submit and show which field. */
@@ -178,6 +188,8 @@ async function resolveInstruments(input: {
   config: CardTokenizationConfig;
   onKeyRefreshed: (key: string) => void;
   providerChain: readonly CardChainLink[];
+  /** The bound key-refresh call (FUT-741) — the self-heal must hit OUR mount. */
+  refreshKey: RefreshBrowserKey;
 }): Promise<Result<CardInstruments>> {
   const { form } = input;
   if (!form.usingNewCard) return ok({ token: form.selection });
@@ -188,6 +200,8 @@ async function resolveInstruments(input: {
     input.onKeyRefreshed,
     form.saveCard,
     input.providerChain,
+    undefined,
+    input.refreshKey,
   );
 }
 
@@ -212,6 +226,8 @@ function useCardSubmit(
   // The active key: resolved by the checkout config, overridden by the
   // rotated-key self-heal for the rest of the session.
   const { publicKey, setPublicKey } = useCardPublicKey(order.orderId, providerConfig);
+  const client = useCheckoutClientApi();
+  const navigate = useCheckoutNavigate();
 
   const { status, error: pollError, timedOut: pollTimedOut } = usePaymentPolling(order.orderId, {
     enabled: submitted,
@@ -235,6 +251,7 @@ function useCardSubmit(
       config: { ...providerConfig, publicKey },
       onKeyRefreshed: setPublicKey,
       providerChain,
+      refreshKey: client.refreshBrowserKey,
     });
     if (!resolved.ok) {
       setError(resolved.error);
@@ -242,7 +259,7 @@ function useCardSubmit(
       return;
     }
 
-    const charged = await chargeCard({
+    const charged = await client.charge({
       orderId: order.orderId,
       token: resolved.data.token,
       tokensByProvider: resolved.data.tokensByProvider,
@@ -261,7 +278,7 @@ function useCardSubmit(
     // 3-D Secure (FUT-698): the buyer must finish on the provider's page.
     // `submitting` stays true on purpose — the tab is navigating away.
     if (charged.data.hostedCheckoutUrl) {
-      return handOverToChallenge(order, charged.data.hostedCheckoutUrl);
+      return handOverToChallenge(order, charged.data.hostedCheckoutUrl, navigate);
     }
     // A business outcome (e.g. declined → FAILED) shows the status screen;
     // an accepted charge begins polling for the async confirmation.

package/src/components/checkout/use-checkout-controller.ts

@@ -1,14 +1,16 @@
 import { useCallback, useEffect, useMemo, useState, type Dispatch, type SetStateAction } from "react";
 
-import { validateCpf } from "../../card";
+import { buyerFormComplete } from "./buyer-info-form";
 
 import { rememberHostedOrder, takeHostedOrder } from "./hosted-return";
+import { useCheckoutNavigate, type CheckoutNavigate } from "./navigate-context";
 import type {
   BuyerContact,
   BuyerField,
   BuyerInfo,
   CheckoutOrder,
   CreateOrderRequest,
+  CheckoutCustomerField,
   CreateOrderResult,
   OrderStatus,
   PaymentMethod,
@@ -19,6 +21,11 @@ type Step = "dados" | "payment" | "status";
 
 const STEP_ORDER: Step[] = ["dados", "payment", "status"];
 
+/** The pre-FUT-595 demand, and the safe reading of a chain that declared none. */
+const CPF_ONLY: readonly CheckoutCustomerField[] = [
+  { key: "taxId", type: "CPF", required: true },
+];
+
 /**
  * Everything the flow needs FROM its host, as explicit ports (FUT-564). The
  * package owns the payment surface; the host owns the cart, the catalog,
@@ -81,19 +88,49 @@ function useCheckoutNav(
   return { back, editBuyer: taxIdOnFile ? openDados : undefined };
 }
 
+/** The message shown when a declared field is missing or malformed. */
+const FIELD_COMPLAINT: Record<string, string> = {
+  taxId: "CPF inválido.",
+  name: "Informe seu nome.",
+  email: "E-mail inválido.",
+  phone: "Telefone inválido.",
+};
+
+/** Which input to highlight for a declared key. */
+const FIELD_INPUT: Record<string, BuyerField> = {
+  taxId: "cpf",
+  name: "name",
+  email: "email",
+  phone: "phone",
+};
+
 /**
- * What the "Continuar" gate objects to about the CPF, or undefined to advance.
+ * What the "Continuar" gate objects to, or undefined to advance.
  *
- * A blank field is only an error when the store has NO CPF for this buyer. With
+ * The fields come from the chain's own declaration (FUT-595) — absent, they
+ * degrade to CPF-required, which is exactly what this gate has always demanded.
+ *
+ * A blank CPF is only an error when the store has NO CPF for this buyer. With
  * one on file the field starts empty by design (the client is never sent the
  * saved CPF), so demanding one here trapped a returning buyer who opened Dados
  * through "Alterar" and changed their mind: they could not reach Pagamento
  * again, and back only led out to the menu. Leaving it blank means "charge me
  * as before", which is exactly what the server's `resolveBuyerTaxId` does.
  */
-function cpfGateError(typed: string, taxIdOnFile: boolean): string | undefined {
-  if (!typed && taxIdOnFile) return undefined;
-  return validateCpf(typed);
+function buyerGateError(
+  buyer: BuyerInfo,
+  fields: readonly CheckoutCustomerField[],
+  taxIdOnFile: boolean,
+): { message: string; field: BuyerField } | undefined {
+  const effective = taxIdOnFile
+    ? fields.filter((field) => !(field.key === "taxId" && !buyer.taxId?.trim()))
+    : fields;
+  const offending = buyerFormComplete(buyer, effective);
+  if (!offending) return undefined;
+  return {
+    message: FIELD_COMPLAINT[offending.key] ?? "Campo obrigatório.",
+    field: FIELD_INPUT[offending.key] ?? "cpf",
+  };
 }
 
 /**
@@ -119,10 +156,13 @@ function initialStep(resuming: boolean, taxIdOnFile: boolean): Step {
  *
  * @returns true when the buyer is on their way and the caller must stop.
  */
-function handOverToProvider(order: CheckoutOrder): boolean {
+function handOverToProvider(order: CheckoutOrder, navigate: CheckoutNavigate): boolean {
   if (!order.hostedCheckoutUrl) return false;
+  // PARK FIRST, navigate second. The order is the only thing the return trip
+  // has to rehydrate from, and the navigation may tear this SPA down before
+  // any later write lands.
   rememberHostedOrder(order);
-  window.location.assign(order.hostedCheckoutUrl);
+  navigate(order.hostedCheckoutUrl);
   return true;
 }
 
@@ -197,20 +237,24 @@ function useCreateFailure() {
  *   being saved.
  * - `startPayment` raises the order (PIX → QR, CARD → chargeable); `payWithEmail`
  *   re-raises with a corrected e-mail for the merchant-email rejection.
+ *
+ * @param taxIdOnFile The buyer already has a CPF saved (FUT-465) ⇒ the Dados
+ *   step has nothing left to ask, so checkout opens on Pagamento and `back`
+ *   goes to the menu rather than to a form the buyer never saw. The CPF itself
+ *   is never in the client's hands — the server reads it from the encrypted
+ *   profile when the charge is raised.
+ * @param buyerFields What the store's chain declares it needs from the buyer
+ *   (FUT-595). Absent ⇒ CPF-required, which is what this gate demanded before
+ *   there was a declaration to read — never "ask nothing".
  */
 export function useCheckoutController(
   ports: CheckoutHostPorts,
   defaultBuyer?: BuyerInfo,
-  /**
-   * The buyer already has a CPF saved (FUT-465) ⇒ the Dados step has nothing
-   * left to ask, so checkout opens on Pagamento and `back` goes to the menu
-   * rather than to a form the buyer never saw. The CPF itself is never in the
-   * client's hands — the server reads it from the encrypted profile when the
-   * charge is raised.
-   */
   taxIdOnFile = false,
+  buyerFields: readonly CheckoutCustomerField[] = CPF_ONLY,
 ) {
   const { createOrder, saveBuyerContact, onExitToMenu, onPaid } = ports;
+  const navigate = useCheckoutNavigate();
   const resume = useHostedResume();
   const [step, setStep] = useState<Step>(initialStep(Boolean(resume.order), taxIdOnFile));
   // No method pre-selected: the Pagamento step shows just the picker until the
@@ -232,8 +276,8 @@ export function useCheckoutController(
   }, [clearError]);
   const goToPayment = useCallback(() => {
     clearError();
-    const cpfError = cpfGateError(buyer.taxId?.trim() ?? "", taxIdOnFile);
-    if (cpfError) { failure.fail({ message: cpfError, field: "cpf" }); return; }
+    const complaint = buyerGateError(buyer, buyerFields, taxIdOnFile);
+    if (complaint) { failure.fail(complaint); return; }
     // Persist the buyer's details HERE, on "Continuar" — not when a payment is
     // raised. Everything after this step can fail (no provider configured, a
     // declined card, an abandoned PIX, a closed tab) and the details must
@@ -245,17 +289,17 @@ export function useCheckoutController(
       saveBuyerContact?.({ name: buyer.name, phone: buyer.phone, taxId: buyer.taxId });
     }
     setStep("payment");
-  }, [buyer.name, buyer.phone, buyer.taxId, saveProfile, taxIdOnFile, clearError, saveBuyerContact]);
+  }, [buyer, buyerFields, saveProfile, taxIdOnFile, clearError, saveBuyerContact]);
   const startPayment = useCallback(async (chosen: PaymentMethod, override?: BuyerInfo) => {
     clearError();
     setCreating(true);
     const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
     setCreating(false);
     if (!result.ok) { failure.fail(result.error); return; }
-    if (handOverToProvider(result.data)) return;
+    if (handOverToProvider(result.data, navigate)) return;
     setOrder(result.data);
     setFinalStatus(null);
-  }, [buyer, saveProfile, createOrder, clearError]);
+  }, [buyer, saveProfile, createOrder, clearError, navigate]);
   const payWithEmail = useCallback((email: string) => {
     if (!method) return;
     const next = { ...buyer, email };

package/src/components/checkout/use-payment-polling.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 
-import { pollOrderStatus } from "./client";
+import { useCheckoutClientApi } from "./client-context";
 import { TERMINAL_STATUSES, type OrderStatus } from "./types";
 
 interface PollingOptions {
@@ -34,6 +34,10 @@ export function usePaymentPolling(
   const [status, setStatus] = useState<OrderStatus | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [timedOut, setTimedOut] = useState(false);
+  // Whichever mount this tree is bound to (FUT-741). Stable per provider, so it
+  // belongs in the deps below rather than being read out of a ref: a checkout
+  // re-pointed at another mount must re-poll against THAT one.
+  const client = useCheckoutClientApi();
 
   useEffect(() => {
     if (!orderId || !enabled) {
@@ -48,7 +52,7 @@ export function usePaymentPolling(
     setError(null);
 
     const tick = async (): Promise<void> => {
-      const result = await pollOrderStatus(orderId);
+      const result = await client.getStatus(orderId);
       if (cancelled) {
         return;
       }
@@ -87,7 +91,7 @@ export function usePaymentPolling(
         clearTimeout(timer);
       }
     };
-  }, [orderId, intervalMs, enabled, maxHealthyPolls]);
+  }, [orderId, intervalMs, enabled, maxHealthyPolls, client]);
 
   return { status, error, timedOut };
 }

package/src/flows/copy.ts

@@ -0,0 +1,57 @@
+/**
+ * The sentences `createPaymentFlows` renders on its OWN screens (FUT-741).
+ *
+ * Scope is deliberately narrow and stated rather than implied: this covers the
+ * copy the FACTORY owns — the unavailable screen's two remedies, the hosted
+ * handover and its fallback link, the empty cart, and the buyer form's continue
+ * action. The screens that already carried their own product copy before this
+ * ticket (PIX, card, status) keep it; moving all of it here in the same change
+ * that introduces the factory would be a copy rewrite disguised as an API.
+ *
+ * Every default below is today's pt-BR, verbatim — a host that passes no `copy`
+ * reads exactly what a buyer reads now.
+ */
+
+/** Every buyer-facing string the factory's own screens render. */
+export interface CheckoutCopyFE {
+  /** No provider connected AND no host remedy: the store simply does not charge. */
+  unavailableTitle: string;
+  unavailableBody: string;
+  /** No provider connected but the host offers a remedy (this repo: the waiter). */
+  unavailableWithRemedyTitle: string;
+  unavailableWithRemedyBody: string;
+  /** The hosted handover interstitial, and the link that is its fallback. */
+  handoffTitle: string;
+  handoffBody: string;
+  handoffLink: string;
+  handoffCancel: string;
+  /** The return leg, while the parked order is polled to a terminal state. */
+  returnPending: string;
+  /** The return leg when nothing was parked — the buyer came back to nothing. */
+  returnUnknown: string;
+  /** Nothing to check out (cart mode only). */
+  emptyCartTitle: string;
+  emptyCartAction: string;
+  /** The Dados step's primary action. */
+  continueAction: string;
+}
+
+export const DEFAULT_CHECKOUT_COPY_FE: CheckoutCopyFE = {
+  unavailableTitle: "Pagamento online indisponível",
+  unavailableBody:
+    "Esta loja não recebe pagamentos pelo site. Combine o pagamento diretamente com a loja para concluir seu pedido.",
+  unavailableWithRemedyTitle: "Pagamento com o garçom",
+  unavailableWithRemedyBody:
+    "Esta loja não recebe pagamentos pelo site. Chame o garçom para fechar a conta na mesa.",
+  handoffTitle: "Você será levado ao pagamento",
+  handoffBody:
+    "Estamos abrindo a página segura do meio de pagamento. Se ela não abrir sozinha, use o link abaixo.",
+  handoffLink: "Abrir a página de pagamento",
+  handoffCancel: "Voltar",
+  returnPending: "Confirmando seu pagamento…",
+  returnUnknown:
+    "Não encontramos um pagamento em andamento nesta sessão. Verifique seus pedidos em instantes.",
+  emptyCartTitle: "Seu carrinho está vazio.",
+  emptyCartAction: "Ver cardápio",
+  continueAction: "Continuar",
+};

package/src/flows/create-payment-flows.tsx

@@ -0,0 +1,196 @@
+/**
+ * `createPaymentFlows` — the buyer checkout, mounted rather than composed
+ * (FUT-741).
+ *
+ * Called ONCE at module scope; the host mounts what comes back. See
+ * `./types.ts` for the config vocabulary and why none of it names a vendor.
+ *
+ * ## Why the scope arrives as HOOKS
+ *
+ * `useScope`, `useCart`, `useBuyerDefaults`, `useComanda` and
+ * `ports.useAvailability` are hooks, not values, and they are invoked in a
+ * component BODY — never read at factory time. The factory runs once, at module
+ * evaluation, so a value-shaped config would freeze the first store's slug and
+ * one moment's cart total onto every checkout the page ever renders. Naming
+ * them `use*` also keeps rules-of-hooks lint able to see them.
+ */
+import { useCallback, type JSX, type ReactNode } from "react";
+
+import { buyerFieldsFor } from "../components/checkout/buyer-fields";
+import { CheckoutFlow } from "../components/checkout/checkout-flow";
+import { createCheckoutClient } from "../components/checkout/transport";
+import type { CheckoutProviderConfig, ComandaCheckout } from "../components/checkout/types";
+import { useCheckoutController } from "../components/checkout/use-checkout-controller";
+
+import { DEFAULT_CHECKOUT_COPY_FE } from "./copy";
+import { FlowsProvider, useResolvedConfig, type FlowsRuntime } from "./runtime";
+import { buyerScreens } from "./screens-buyer";
+import { hostedScreens } from "./screens-hosted";
+import { payScreens, storeCannotCharge } from "./screens-pay";
+import type {
+  CheckoutAvailability,
+  CheckoutController,
+  CheckoutScreens,
+  PaymentFlows,
+  PaymentFlowsConfig,
+} from "./types";
+
+/** A store that is always payable — what a host with no veto to cast means. */
+const ALWAYS_PAYABLE: CheckoutAvailability = { payable: true };
+
+/** Build the runtime every screen closes over. */
+function buildRuntime(config: PaymentFlowsConfig): FlowsRuntime {
+  const client = createCheckoutClient(config.transport);
+  const navigate =
+    config.ports.navigate ??
+    ((url: string) => {
+      window.location.assign(url);
+    });
+  return {
+    config,
+    client,
+    copy: { ...DEFAULT_CHECKOUT_COPY_FE, ...config.copy },
+    navigate,
+    // Both of these are HOOKS. They are called from a component body on every
+    // render, so the slug follows the host's router and the availability vote
+    // follows whatever the host currently knows.
+    useTenantSlug: () => config.useScope?.().tenantSlug,
+    useAvailability: () => config.ports.useAvailability?.() ?? ALWAYS_PAYABLE,
+  };
+}
+
+/** The whole three-step flow, with the config fetched and availability decided. */
+function buildCheckout(
+  runtime: FlowsRuntime,
+  screens: CheckoutScreens,
+): PaymentFlows["Checkout"] {
+  const { ports } = runtime.config;
+  const Unavailable = screens.PaymentsUnavailable;
+
+  function CheckoutBody({ comanda }: { comanda?: ComandaCheckout | null }): JSX.Element {
+    const cart = runtime.config.useCart();
+    const defaults = runtime.config.useBuyerDefaults?.() ?? {};
+    const hostComanda = runtime.config.useComanda?.() ?? null;
+    const { config, pending } = useResolvedConfig(runtime);
+    const availability = runtime.useAvailability();
+    const tenantSlug = runtime.useTenantSlug();
+    // Adapts the port to the package's older, prop-shaped contract. Memoised so
+    // the controller does not see a fresh `createOrder` identity each render.
+    const createOrder = useCallback(
+      (input: Parameters<typeof ports.createPayable>[0]) => ports.createPayable(input),
+      [],
+    );
+
+    if (storeCannotCharge(config, pending, availability.payable)) return <Unavailable />;
+
+    return (
+      <CheckoutFlow
+        cart={cart}
+        createOrder={createOrder}
+        saveBuyerContact={ports.saveBuyerContact}
+        onExitToMenu={ports.exitToCatalog}
+        onPaid={ports.onPaid}
+        defaultBuyer={defaults.buyer}
+        taxIdOnFile={defaults.taxIdOnFile ?? false}
+        comanda={comanda ?? hostComanda}
+        providerConfig={config}
+        tenantSlug={tenantSlug}
+        confirmationExtra={runtime.config.confirmation?.extra}
+      />
+    );
+  }
+
+  return function Checkout(props) {
+    // Its OWN provider, so the one-line mount really is one line: `/config` is
+    // fetched here and every nested screen reads that answer.
+    //
+    // The design-system slots come from the `FlowsShell` inside it, and the
+    // `CheckoutComponentsProvider` that `CheckoutFlow` opens one level down
+    // INHERITS them (see `ui.tsx`) rather than resetting to raw MUI — which is
+    // why nothing here re-threads `components`.
+    return (
+      <FlowsProvider runtime={runtime}>
+        <CheckoutBody {...props} />
+      </FlowsProvider>
+    );
+  };
+}
+
+/** Assemble the eleven screens from their builders. */
+function buildScreens(runtime: FlowsRuntime): CheckoutScreens {
+  return {
+    MethodChoice: buyerScreens.buildMethodChoice(runtime),
+    BuyerDetails: buyerScreens.buildBuyerDetails(runtime),
+    CardEntry: payScreens.buildCardEntry(runtime),
+    PixPayment: payScreens.buildPixPayment(runtime),
+    HostedHandoff: hostedScreens.buildHostedHandoff(runtime),
+    HostedReturn: hostedScreens.buildHostedReturn(runtime),
+    PaymentStatus: payScreens.buildPaymentStatus(runtime),
+    PaymentsUnavailable: payScreens.buildPaymentsUnavailable(runtime),
+    PayerSummary: buyerScreens.buildPayerSummary(runtime),
+    SavedCards: buyerScreens.buildSavedCards(runtime),
+    EmptyCart: buyerScreens.buildEmptyCart(runtime),
+  };
+}
+
+/** The flow controller, pre-bound to the ports and the chain's declaration. */
+function buildUseCheckout(runtime: FlowsRuntime): () => CheckoutController {
+  const { ports } = runtime.config;
+  return function useCheckout(): CheckoutController {
+    const { config } = useResolvedConfig(runtime);
+    const defaults = runtime.config.useBuyerDefaults?.() ?? {};
+    return useCheckoutController(
+      {
+        createOrder: ports.createPayable,
+        saveBuyerContact: ports.saveBuyerContact,
+        onExitToMenu: ports.exitToCatalog,
+        onPaid: ports.onPaid,
+      },
+      defaults.buyer,
+      defaults.taxIdOnFile ?? false,
+      // Resolved for NO method: the gate runs on the Dados step, before the
+      // picker, and FUT-595's rule is to collect the union up front.
+      buyerFieldsFor(config?.chain, null),
+    );
+  };
+}
+
+/**
+ * The buyer checkout, pre-bound.
+ *
+ * ```ts
+ * export const components = createPaymentFlows({ useCart, ports: { … } });
+ * // …and in the page:  <components.Checkout />
+ * ```
+ *
+ * The flat exports (`CheckoutFlow`, the hooks, the fetch clients) are
+ * unchanged and remain the escape hatch for a host that wants its own
+ * composition — nothing here replaces them.
+ */
+export function createPaymentFlows(config: PaymentFlowsConfig): PaymentFlows {
+  const runtime = buildRuntime(config);
+  const screens = buildScreens(runtime);
+
+  function Provider({
+    children,
+    config: provided,
+  }: {
+    children: ReactNode;
+    config?: CheckoutProviderConfig | null;
+  }): JSX.Element {
+    return (
+      <FlowsProvider runtime={runtime} config={provided}>
+        {children}
+      </FlowsProvider>
+    );
+  }
+
+  return {
+    Checkout: buildCheckout(runtime, screens),
+    Provider,
+    screens,
+    useCheckout: buildUseCheckout(runtime),
+    useCheckoutConfig: () => useResolvedConfig(runtime),
+    client: runtime.client,
+  };
+}