@12-apps/payments-frontend 3.22.0 → 3.23.0

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

@@ -169,8 +169,9 @@ type CardSubmit = Pick<
  * It was 36 healthy polls, which is the same 90 s at the default 2500 ms
  * interval and an unbounded wait at any other — including the one that
  * mattered, where every poll is FAILING and the healthy count never moves.
- * PIX passes no bound at all and keeps today's behavior: its charge expires
- * server-side and comes back as a terminal EXPIRED.
+ * PIX is bounded too since FUT-1170, but by the CHARGE's own expiry rather
+ * than by a constant: a code the buyer can still scan is still worth watching,
+ * and one that has died is not.
  */
 const CARD_AWAITING_WAIT_MS = 90_000;
 

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

@@ -12,6 +12,7 @@ import {
   useStartPayment,
   type Step,
 } from "./checkout-actions";
+import { useConfirmationWait } from "./confirmation-wait";
 import { useCheckoutCopy } from "./copy-context";
 
 import { forgetHostedOrder } from "./hosted-return";
@@ -124,10 +125,14 @@ export function useCheckoutController(
   const { back, editBuyer } = useCheckoutNav(taxIdOnFile, onExitToMenu, setStep);
   const setMethod = useCallback((next: PaymentMethod) => {
     setMethodState((prev) => {
-      if (prev !== next) { setOrder(null); forgetHostedOrder(); clearError(); }
+      // SCOPED (FUT-1240): the order dropped here is THIS store's, and so is
+      // the parked entry that goes with it. Unscoped, changing method at store
+      // B threw away store A's parked hand-off — the same cross-store slot the
+      // slug closed on the read side, still open on the write side.
+      if (prev !== next) { setOrder(null); forgetHostedOrder(tenantSlug); clearError(); }
       return next;
     });
-  }, [clearError]);
+  }, [clearError, tenantSlug]);
   const goToPayment = useGoToPayment({
     buyer, buyerFields, taxIdOnFile, saveProfile, saveBuyerContact, validation, failure, setStep,
   });
@@ -150,13 +155,22 @@ export function useCheckoutController(
     decline, order, clearError, setOrder, setDecline, setFinalStatus, setStep, setFreshInstrument,
   });
   const completed = useMemo(() => new Set(STEP_ORDER.slice(0, STEP_ORDER.indexOf(step))), [step]);
-  useSettledPort(finalStatus ?? resume.status, onPaid);
+  const settled = finalStatus ?? resume.status;
+  useSettledPort(settled, onPaid);
+  // The confirmation screen's own wait (FUT-1170). Live only where nothing else
+  // is polling and nothing has answered: a resumed leg brings its own wait, and
+  // every method's screen polls for itself on the payment step.
+  const confirming = useConfirmationWait({
+    orderId: order?.orderId ?? null,
+    active: step === "status" && settled === null && resume.order === null,
+    onSettled: setFinalStatus,
+  });
 
   return {
     step, setStep, method, setMethod, buyer, setBuyer, saveProfile, setSaveProfile,
-    order, finalStatus: finalStatus ?? resume.status, creating,
+    order, finalStatus: settled, creating,
     decline, freshInstrument,
-    ...resumeSurface(resume),
+    ...resumeSurface(resume, confirming),
     createError: failure.message, errorField: failure.field, errorCode: failure.code,
     goToMenu: onExitToMenu, back, editBuyer,
     goToPayment, startPayment, payWithEmail, handleResolved, retry, completed,

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

@@ -1,8 +1,8 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState, type Dispatch, type SetStateAction } from "react";
 
 import { useCheckoutClientApi } from "./client-context";
 import { useCheckoutCopy } from "./copy-context";
-import { createPollLoop, type PollLoop, type PollingOptions } from "./poll-loop";
+import { createPollLoop, type PollLoop, type PollingOptions, type PollSink } from "./poll-loop";
 import type { OrderStatus } from "./types";
 
 /** What a consumer reads off the wait, and the one action it can take. */
@@ -24,6 +24,50 @@ interface PaymentPollingState {
   checkAgain: () => void;
 }
 
+/**
+ * What one wait has learned, and WHICH order it learned it about (FUT-1170).
+ *
+ * The three facts used to be three `useState`s with no order id attached, so a
+ * consumer re-pointed at a new charge read the PREVIOUS charge's answer until
+ * the new loop's first poll returned. That is not a cosmetic flash: a terminal
+ * status is acted on, and `PixView` acts on it by handing the flow to the
+ * confirmation screen — so a fresh, unpaid PIX code was reported settled by the
+ * code it had just replaced. Regenerating an expired charge is the path that
+ * does exactly this, and it is the one FUT-1170 was reported from.
+ *
+ * Stamping the answer and comparing at READ time (rather than clearing the
+ * state in an effect) is what makes the guard hold in the render that changes
+ * the id, with no intermediate frame in which the stale answer is still live.
+ */
+interface PollAnswer {
+  orderId: string | null;
+  status: OrderStatus | null;
+  error: string | null;
+  timedOut: boolean;
+}
+
+const NO_ANSWER: PollAnswer = { orderId: null, status: null, error: null, timedOut: false };
+
+/**
+ * Where a wait for ONE order writes what it learns.
+ *
+ * Every write is stamped with the order the loop was started for, and a write
+ * arriving against a DIFFERENT stamp starts from `NO_ANSWER` rather than
+ * merging into the previous order's facts.
+ */
+function sinkFor(
+  orderId: string,
+  setAnswer: Dispatch<SetStateAction<PollAnswer>>,
+): PollSink {
+  const write = (patch: Partial<PollAnswer>): void =>
+    setAnswer((prev) => ({ ...(prev.orderId === orderId ? prev : NO_ANSWER), ...patch, orderId }));
+  return {
+    setStatus: (status) => write({ status }),
+    setError: (error) => write({ error }),
+    setTimedOut: (timedOut) => write({ timedOut }),
+  };
+}
+
 
 /**
  * Ask again the moment the shopper could plausibly have an answer for us.
@@ -77,9 +121,7 @@ export function usePaymentPolling(
     askTimeoutMs,
   }: PollingOptions = {},
 ): PaymentPollingState {
-  const [status, setStatus] = useState<OrderStatus | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [timedOut, setTimedOut] = useState(false);
+  const [answer, setAnswer] = useState<PollAnswer>(NO_ANSWER);
   // 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.
@@ -106,7 +148,7 @@ export function usePaymentPolling(
         askTimeoutMs,
         askTimeoutError: transportCopy.offline,
       },
-      { setStatus, setError, setTimedOut },
+      sinkFor(orderId, setAnswer),
     );
     loop.current = running;
     running.restart();
@@ -133,6 +175,15 @@ export function usePaymentPolling(
     loop.current?.restart();
   }, []);
 
-  return { status, error, timedOut, checkAgain };
+  // The answer is this order's, or there is no answer yet. Read here rather
+  // than reset in an effect: an effect runs after paint, so the render that
+  // re-points the hook would still hand a consumer the old charge's status.
+  const current = answer.orderId === orderId ? answer : NO_ANSWER;
+  return {
+    status: current.status,
+    error: current.error,
+    timedOut: current.timedOut,
+    checkAgain,
+  };
 }
 

package/src/components/checkout/use-wallet-charge.ts

@@ -1,5 +1,7 @@
 import { useEffect, useState } from "react";
 
+import { parkedBasket } from "./basket";
+import type { ChallengeScope } from "./card-outcome";
 import { useCheckoutClientApi } from "./client-context";
 import { UNRESOLVED_CODE } from "./failure-codes";
 import { rememberHostedOrder } from "./hosted-return";
@@ -62,12 +64,33 @@ export interface WalletCharge {
  */
 const WALLET_AWAITING_WAIT_MS = 90_000;
 
+/**
+ * Park the order before the tab leaves, WITH the store and the basket
+ * (FUT-1240).
+ *
+ * Both absences are read as "no opinion" by the resume — `belongsHere` passes
+ * a slug-less entry at any store and the basket rule passes a basket-less one
+ * against any basket — so a wallet's 3-D Secure hand-off that named neither
+ * resumed over whatever checkout mounted next. The card path has carried these
+ * since FUT-1213; this call site is the one that did not.
+ */
+function parkForHandover(order: CheckoutOrder, scope: ChallengeScope): void {
+  const basket = parkedBasket(scope.basket);
+  rememberHostedOrder(order, {
+    ...(scope.tenantSlug === undefined ? {} : { tenantSlug: scope.tenantSlug }),
+    ...(basket === undefined ? {} : { basket }),
+    handoff: true,
+  });
+}
+
 /** The wallet charge state machine. See the module comment. */
 export function useWalletCharge(
   order: CheckoutOrder,
   buyer: BuyerInfo,
   onResolved: (status: OrderStatus) => void,
   pollIntervalMs = 2500,
+  /** WHOSE store and WHICH basket — see {@link parkForHandover} (FUT-1240). */
+  scope: ChallengeScope = {},
 ): WalletCharge {
   const [phase, setPhase] = useState<WalletPhase>("idle");
   const [error, setError] = useState<string | null>(null);
@@ -116,7 +139,7 @@ export function useWalletCharge(
     // FUT-698): park the order and hand the buyer over, exactly as the card
     // path does. `phase` stays as-is — the tab is navigating away.
     if (charged.data.hostedCheckoutUrl) {
-      rememberHostedOrder(order);
+      parkForHandover(order, scope);
       navigate(charged.data.hostedCheckoutUrl);
       return true;
     }

package/src/components/checkout/view-copy.ts

@@ -130,12 +130,50 @@ export interface PaymentStatusCopy {
   receiptEmailLabel: string;
 }
 
+/**
+ * The pipeline engine's own two sentences (FUT-1240).
+ *
+ * REQUIRED, both of them, and stated here rather than defaulted for the reason
+ * every other string in this file is: a default in the origin host's language
+ * reads as finished right up until a shopper sees it. These two are the whole
+ * of what the ENGINE renders on its own account — everything else on screen
+ * belongs to a step, a gate or a settlement method.
+ */
+export interface CheckoutPipelineCopy {
+  /**
+   * What is on screen while the checkout has nothing to show yet: a gate still
+   * deciding, the store's protocol still in flight, or no step applying.
+   *
+   * It replaces a blank frame. A shopper who taps "pagar" and gets an empty
+   * page taps again.
+   */
+  loading: string;
+  /**
+   * PER SETTLEMENT METHOD, what the shopper reads between choosing it and the
+   * surface that takes the money arriving — the hand-off interstitial's own
+   * line. Keyed by `SettlementMethodDescriptor.id`.
+   *
+   * Per method because the sentences are not interchangeable: a Pix hand-off
+   * and a card challenge send the shopper to different places for different
+   * reasons, and one shared "aguarde" describes neither. A method with no
+   * entry falls back to {@link CheckoutPipelineCopy.loading}, which is what a
+   * host registering a new charged method gets until it writes the sentence.
+   */
+  awaitingHandover: Readonly<Record<string, string>>;
+}
+
 /** What the legacy `CheckoutFlow` itself renders and must be handed. */
 export interface CheckoutViewCopy {
   steps: CheckoutStepperCopy;
   dados: DadosStepCopy;
   emptyCart: EmptyCartCopy;
   status: PaymentStatusCopy;
+  /**
+   * The engine's own two sentences (FUT-1240). Carried here, beside the
+   * stepper labels, so a host still answers copy exactly once — the pipeline
+   * is another way of rendering this same checkout, not a second surface.
+   */
+  pipeline: CheckoutPipelineCopy;
   /**
    * The words the screens BELOW these read — the card fields, the wallet
    * panes, the buyer-details inputs (FUT-760).

package/src/components/checkout/wallet-pane.tsx

@@ -150,7 +150,12 @@ export function WalletCardPane(props: WalletPaneProps): JSX.Element {
   const copy = useCheckoutCopy().screens.settling;
   const { order, buyer, config, tenantSlug, onResolved, pollIntervalMs } = props;
   const { freshInstrument, basket } = props;
-  const wallet = useWalletCharge(order, buyer, onResolved, pollIntervalMs);
+  // The same store and basket the card path already parks with (FUT-1213,
+  // FUT-1240): a wallet's 3-D Secure hand-off is a hand-off like any other.
+  const wallet = useWalletCharge(order, buyer, onResolved, pollIntervalMs, {
+    ...(tenantSlug === undefined ? {} : { tenantSlug }),
+    ...(basket === undefined ? {} : { basket }),
+  });
   // A sheet failure the wallet reported before any charge existed (pay.js
   // refused, merchant validation unavailable, the sheet errored) — shown
   // beside the form, which stays usable.

package/src/flows/catalog-exit.ts

@@ -0,0 +1,33 @@
+/**
+ * ONE WAY OUT OF A CHECKOUT (FUT-1240).
+ *
+ * A checkout has two controls that leave it — the chrome's back link on the
+ * first step, and "voltar ao cardápio" on the confirmation — and until this
+ * existed they answered differently: back honoured a registered
+ * {@link CheckoutExit} while the confirmation went straight to
+ * `ports.exitToCatalog`. So a host that registered its router's own catalog
+ * route got it from one control and a full page navigation from the other,
+ * with the difference visible only to the shopper who pressed the second one.
+ *
+ * `exit` is a FACTORY-scope constant, so calling its `useCatalog()` here is a
+ * hook call whose presence never changes between renders.
+ */
+import { useCallback } from "react";
+
+import type { FlowsRuntime } from "./runtime";
+
+/**
+ * Leave for the host's catalog, through whichever door it registered.
+ *
+ * `exit` wins when there is one — it is the host's own router, and a router
+ * navigation keeps the SPA alive. `ports.exitToCatalog` is the fallback every
+ * host already wires, and stays the answer for a host that registered nothing.
+ */
+export function useCatalogExit(runtime: FlowsRuntime): () => void {
+  const exit = runtime.config.exit;
+  const catalog = exit?.useCatalog();
+  return useCallback(() => {
+    if (exit && catalog) exit.navigate(catalog.to);
+    else runtime.config.ports.exitToCatalog();
+  }, [exit, catalog, runtime]);
+}

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

@@ -22,6 +22,8 @@ import { createCheckoutClient } from "../components/checkout/transport";
 import type { CheckoutProviderConfig, SettlementCheckout } from "../components/checkout/types";
 import { useCheckoutController } from "../components/checkout/use-checkout-controller";
 
+import { buildPipeline } from "./pipeline/engine";
+import { pipelineRequested } from "./pipeline/types";
 import { FlowsProvider, useResolvedConfig, type FlowsRuntime } from "./runtime";
 import { buyerScreens } from "./screens-buyer";
 import { hostedScreens } from "./screens-hosted";
@@ -203,12 +205,21 @@ export function createPaymentFlows(config: PaymentFlowsConfig): PaymentFlows {
     );
   }
 
+  // THE ADDITIVE SWITCH (FUT-1240). A host that registered a step, a gate, a
+  // settlement method, an intent, an open payable, an exit or a settle
+  // callback gets the pipeline; a host that registered none gets the flat
+  // three-step flow, unchanged, down to its test ids. `useAdmission` is built
+  // either way — with no gates registered it passes, which is the honest
+  // answer for a host that has declared no admission rules.
+  const pipeline = buildPipeline(runtime, screens);
+
   return {
-    Checkout: buildCheckout(runtime, screens),
+    Checkout: pipelineRequested(config) ? pipeline.Checkout : buildCheckout(runtime, screens),
     Provider,
     screens,
     useCheckout: buildUseCheckout(runtime),
     useCheckoutConfig: () => useResolvedConfig(runtime),
+    useAdmission: pipeline.useAdmission,
     client: runtime.client,
   };
 }

package/src/flows/pipeline/actions.tsx

@@ -0,0 +1,104 @@
+/**
+ * WHAT A STEP CAN DO, as a context (FUT-1240).
+ *
+ * A step's `render` is handed only what §4.2 declares — its context, its
+ * facts, its slice, and the two navigations. Everything a step needs to CHANGE
+ * (choose a method, place the order, report a terminal status, edit the buyer)
+ * belongs to the engine, and the engine is the only writer of each.
+ *
+ * It arrives as a React context rather than as a closure, for one mechanical
+ * reason: the registered arrays must be identity-stable across renders (see
+ * `stable-plugins.ts`), so a step object cannot be rebuilt each render to
+ * capture this render's callbacks. A context is read where it is used, in a
+ * component, and leaves the step objects frozen.
+ */
+import { createContext, useContext, type JSX, type ReactNode } from "react";
+
+import type { CheckoutDecline } from "../../components/checkout/decline";
+import type {
+  BuyerInfo,
+  CheckoutError,
+  CheckoutOrder,
+  OrderStatus,
+} from "../../components/checkout/types";
+import type { CheckoutViewCopy } from "../../components/checkout/view-copy";
+import type { CheckoutScreens } from "../types";
+
+import type { AnySettlementMethod, CheckoutContext } from "./types";
+
+/** The engine's writers, plus the two tables a step renders from. */
+export interface PipelineActions {
+  /** Every screen the factory built, already bound to transport and slots. */
+  screens: CheckoutScreens;
+  /** The words. The engine's own two live under `copy.pipeline`. */
+  copy: CheckoutViewCopy;
+  /** Every registered settlement method, in picker order. */
+  methods: readonly AnySettlementMethod[];
+  /** The subset this shopper is actually offered, in the same order. */
+  offered: readonly AnySettlementMethod[];
+  /** The shopper picked a way to settle. Raises the payable unless a Review owns that. */
+  choose(methodId: string): void;
+  /** Raise the payable for the chosen method — a `Review`'s own action. */
+  place(): void;
+  /** A payable is being raised right now. */
+  placing: boolean;
+  /** "Continuar" on the buyer-details step: gate, persist, advance. */
+  continueFromDados(): void;
+  setBuyer(buyer: BuyerInfo): void;
+  saveProfile: boolean;
+  setSaveProfile(save: boolean): void;
+  /** A terminal status, carrying the refusal when the charge produced one. */
+  resolve(status: OrderStatus, decline?: CheckoutDecline | null): void;
+  /**
+   * Take up an order this visit did not raise — a resumed on-page charge.
+   * Separate from {@link PipelineActions.place} because nothing is being
+   * created: the charge exists, and what changes is only which order the walk
+   * is about.
+   */
+  adoptOrder(order: CheckoutOrder): void;
+  /** Leave for the host's catalog. */
+  exitToCatalog(): void;
+  /** The refusal the engine currently holds, whoever claimed it. */
+  error: CheckoutError | null;
+  /** Reopen the buyer-details step — the payer block's "alterar". */
+  editBuyer: (() => void) | undefined;
+}
+
+const PipelineActionsContext = createContext<PipelineActions | null>(null);
+
+/** The engine's actions. Throws outside the engine, on purpose. */
+export function usePipelineActions(): PipelineActions {
+  const actions = useContext(PipelineActionsContext);
+  if (!actions) {
+    throw new Error(
+      "usePipelineActions() was called outside the checkout pipeline. A step's " +
+        "render only runs inside <Checkout />; mounting one on its own is what " +
+        "`flows.screens.*` is for.",
+    );
+  }
+  return actions;
+}
+
+/** Supplied once by the engine, above every step. */
+export function PipelineActionsProvider({
+  actions,
+  children,
+}: {
+  actions: PipelineActions;
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <PipelineActionsContext.Provider value={actions}>
+      {children}
+    </PipelineActionsContext.Provider>
+  );
+}
+
+/** The descriptor for a chosen method, or `undefined` when nobody registered it. */
+export function descriptorFor(
+  methods: readonly AnySettlementMethod[],
+  ctx: CheckoutContext,
+): AnySettlementMethod | undefined {
+  if (ctx.method === null) return undefined;
+  return methods.find((entry) => entry.id === ctx.method);
+}

package/src/flows/pipeline/admission.ts

@@ -0,0 +1,55 @@
+/**
+ * MAY THIS SHOPPER CHECK OUT — one answer, offered headless (FUT-1240).
+ *
+ * The gates run in ARRAY ORDER and the first non-`pass` verdict wins. Order
+ * matters and is the host's to choose: a gate that would curtain the screen
+ * must not speak before the gate that is still waiting for the cart, or a
+ * shopper meets "loja fechada" because a fact had not arrived yet.
+ *
+ * Exported as `flows.useAdmission()` so the cart drawer's CTA and a
+ * buy-now button consume the SAME list the checkout does. Two surfaces
+ * deciding this separately is how a storefront ends up with a drawer that
+ * offers a checkout the checkout itself refuses.
+ */
+import { hostedCheckoutReturnPending } from "../../components/checkout/hosted-return";
+
+import type { AnyCheckoutGate, CheckoutContext, GateVerdict } from "./types";
+
+/** Nothing said otherwise. */
+const PASS: GateVerdict = { kind: "pass" };
+
+/**
+ * The gates' verdict, given the facts each of them returned.
+ *
+ * Pure: the hooks run in the caller's body, in array order, and their answers
+ * arrive here as a list. That is what makes this testable without a renderer
+ * and what keeps hook order a property of the ARRAY rather than of the
+ * verdicts.
+ */
+export function decideAdmission(input: {
+  gates: readonly AnyCheckoutGate[];
+  facts: readonly unknown[];
+  ctx: CheckoutContext;
+  /** A hand-off from this tab is still waiting — see `standsAsideForResume`. */
+  resuming: boolean;
+}): GateVerdict {
+  for (const [at, gate] of input.gates.entries()) {
+    // A gate that stands aside for a resume is standing aside from the one
+    // route where money gets confirmed. Skipped for that visit only.
+    if (input.resuming && gate.standsAsideForResume) continue;
+    const verdict = gate.decide(input.ctx, input.facts[at]);
+    if (verdict.kind !== "pass") return verdict;
+  }
+  return PASS;
+}
+
+/**
+ * Whether a hand-off from this tab is still waiting to be resolved.
+ *
+ * Asked with the SAME slug and basket the resume asks with, so a gate and the
+ * flow behind it cannot disagree about whose return this is — the property
+ * `hostedCheckoutReturnPending`'s own doc argues for at length.
+ */
+export function resumePending(ctx: CheckoutContext): boolean {
+  return hostedCheckoutReturnPending(ctx.tenantSlug, ctx.cart.identity);
+}

package/src/flows/pipeline/context.ts

@@ -0,0 +1,140 @@
+/**
+ * THE CONTEXT EVERY PLUGIN READS, built once from the host's own hooks
+ * (FUT-1240).
+ *
+ * One builder, used by BOTH the engine and `flows.useAdmission()`, so the
+ * headless admission the cart drawer asks and the checkout the shopper reaches
+ * cannot disagree about the same shopper. That was the whole harm behind
+ * "three exemption sets": every surface answered "may this store take money"
+ * from its own reading of its own facts.
+ *
+ * Every field is server-owned or parked. Nothing here is React state the
+ * engine happens to hold — the engine layers its own on top with
+ * {@link withCheckoutState}, and only there.
+ */
+import type { CheckoutOrder } from "../../components/checkout/types";
+
+import { useResolvedConfig, type FlowsRuntime } from "../runtime";
+
+import type { CheckoutContext, CheckoutPipelineConfig } from "./types";
+
+/** No host `useIntent` ⇒ no one-click, no resume request, no preset method. */
+const NO_INTENT: CheckoutContext["intent"] = Object.freeze({
+  oneClick: false,
+  resuming: false,
+  presetMethod: null,
+});
+
+/** No host `useOpenPayable` ⇒ the server is never asked; the park still answers. */
+const NO_OPEN_PAYABLE: { order: CheckoutOrder | null; pending: boolean } = Object.freeze({
+  order: null,
+  pending: false,
+});
+
+/**
+ * The two reads only a HOST can answer: what the address bar asked for, and
+ * what the server says is already in flight.
+ *
+ * Its own function so the defaulting stays in one place — and so the base
+ * builder below reads as a list of facts rather than as a chain of `??`.
+ */
+function usePipelineReads(pipeline: CheckoutPipelineConfig): {
+  intent: CheckoutContext["intent"];
+  openPayable: { order: CheckoutOrder | null; pending: boolean };
+} {
+  const intent = pipeline.useIntent?.() ?? NO_INTENT;
+  const openPayable = pipeline.useOpenPayable?.() ?? NO_OPEN_PAYABLE;
+  return { intent, openPayable };
+}
+
+/** The base context plus the two reads a caller may need on their own. */
+interface CheckoutBase {
+  ctx: CheckoutContext;
+  openPayable: { order: CheckoutOrder | null; pending: boolean };
+  /** The buyer's saved details are still being fetched. */
+  buyerPending: boolean;
+}
+
+/**
+ * The host's facts, as a context.
+ *
+ * `method`, `order`, `outcome` and `slices` are at their resting values here:
+ * an admission decision is about the SHOPPER and the STORE, never about how
+ * far into a payment somebody is. The engine supplies the rest.
+ */
+export function useCheckoutBase(
+  runtime: FlowsRuntime,
+  pipeline: CheckoutPipelineConfig,
+): CheckoutBase {
+  const cart = runtime.config.useCart();
+  const defaults = runtime.config.useBuyerDefaults?.() ?? {};
+  const settlement = runtime.config.useSettlement?.() ?? null;
+  const { config, pending } = useResolvedConfig(runtime);
+  const tenantSlug = runtime.useTenantSlug();
+  const { intent, openPayable } = usePipelineReads(pipeline);
+  return {
+    ctx: {
+      ...(tenantSlug === undefined ? {} : { tenantSlug }),
+      config,
+      configPending: pending,
+      cart,
+      settlement,
+      ...buyerFacts(defaults),
+      ...AT_REST,
+      order: openPayable.order,
+      intent,
+    },
+    openPayable,
+    buyerPending: defaults.pending ?? false,
+  };
+}
+
+/** Nothing has been chosen, raised or answered yet. */
+const AT_REST = Object.freeze({
+  method: null,
+  outcome: null,
+  slices: Object.freeze({}),
+} as const);
+
+/** The buyer half, with the two absences that mean "the host wired none". */
+function buyerFacts(defaults: {
+  buyer?: CheckoutContext["buyer"];
+  taxIdOnFile?: boolean;
+}): Pick<CheckoutContext, "buyer" | "taxIdOnFile"> {
+  return {
+    buyer: defaults.buyer ?? {},
+    taxIdOnFile: defaults.taxIdOnFile ?? false,
+  };
+}
+
+/** What the ENGINE knows and the base does not. */
+interface CheckoutEngineState {
+  buyer: CheckoutContext["buyer"];
+  method: string | null;
+  order: CheckoutOrder | null;
+  outcome: CheckoutContext["outcome"];
+  slices: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The base context with the engine's own state laid over it.
+ *
+ * The BUYER is overlaid rather than merged: the shopper may have typed a CPF
+ * for this purchase over the one on file, and the whole of `checkout-skip-dados`
+ * turns on that replacement being visible to every later step.
+ */
+export function withCheckoutState(
+  base: CheckoutContext,
+  state: CheckoutEngineState,
+): CheckoutContext {
+  return {
+    ...base,
+    buyer: state.buyer,
+    method: state.method,
+    // The just-raised order wins over whatever the server or the park offered:
+    // it is the one this visit is actually paying.
+    order: state.order ?? base.order,
+    outcome: state.outcome,
+    slices: state.slices,
+  };
+}