@12-apps/payments-frontend 3.22.0 → 3.23.1

package/src/components/checkout/resolution-actions.ts

@@ -0,0 +1,43 @@
+import { useCallback, type Dispatch, type SetStateAction } from "react";
+
+import type { Step } from "./checkout-actions";
+import type { CheckoutDecline } from "./decline";
+import type { BuyerInfo, OrderStatus, PaymentMethod } from "./types";
+
+/**
+ * The two actions the payment step raises on its own: paying once an e-mail
+ * has been typed, and reporting the result the provider's screen reached.
+ *
+ * Extracted from `useCheckoutController` for the same reason `useRetryAction`
+ * and `useGoToPayment` were: the controller is the one function that has to
+ * hold every piece of checkout state at once, and each action it also spells
+ * out inline is a line it cannot spend on the state. FUT-1170 and FUT-1240
+ * together pushed it past the size gate; these two callbacks are the part that
+ * reads the same wherever it lives.
+ */
+export function useResolutionActions(input: {
+  buyer: BuyerInfo;
+  method: PaymentMethod | null;
+  startPayment: (method: PaymentMethod, buyer: BuyerInfo) => Promise<void>;
+  setBuyerState: Dispatch<SetStateAction<BuyerInfo>>;
+  setDecline: Dispatch<SetStateAction<CheckoutDecline | null>>;
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
+  setStep: Dispatch<SetStateAction<Step>>;
+}): {
+  payWithEmail: (email: string) => void;
+  handleResolved: (status: OrderStatus, refusal?: CheckoutDecline | null) => void;
+} {
+  const { buyer, method, startPayment, setBuyerState, setDecline, setFinalStatus, setStep } = input;
+  const payWithEmail = useCallback((email: string) => {
+    if (!method) return;
+    const next = { ...buyer, email };
+    setBuyerState(next);
+    void startPayment(method, next);
+  }, [buyer, method, setBuyerState, startPayment]);
+  const handleResolved = useCallback((status: OrderStatus, refusal?: CheckoutDecline | null) => {
+    setDecline(refusal ?? null);
+    setFinalStatus(status);
+    setStep("status");
+  }, [setDecline, setFinalStatus, setStep]);
+  return { payWithEmail, handleResolved };
+}

package/src/components/checkout/types.ts

@@ -185,6 +185,17 @@ export interface CreateOrderRequest {
   buyer: BuyerInfo;
   /** Opt-in: save buyer name/phone (not CPF — never persisted here) for next-checkout pre-fill. */
   saveProfile: boolean;
+  /**
+   * WHICH settlement the buyer chose, when it is not one of the two above
+   * (FUT-1240).
+   *
+   * `method` is what the CHAIN can be asked to charge, so a pipeline host's own
+   * registered settlement — "pay the courier", "pay the waiter" — cannot be
+   * said there, and without this every one of them arrives as the same request.
+   * ABSENT for `PIX` and `CARD`, which is what keeps it additive; otherwise the
+   * registered `SettlementMethodDescriptor.id` verbatim (`flows/pipeline`).
+   */
+  settlementMethod?: string;
 }
 
 /** What the flow hands the host's `saveBuyerContact` port on "Continuar". */

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";
@@ -27,6 +28,7 @@ import type {
   OrderStatus,
   PaymentMethod,
 } from "./types";
+import { useResolutionActions } from "./resolution-actions";
 import { useHostedResume } from "./use-hosted-resume";
 
 const STEP_ORDER: Step[] = ["dados", "payment", "status"];
@@ -124,10 +126,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,
   });
@@ -135,28 +141,29 @@ export function useCheckoutController(
     buyer, saveProfile, createOrder, navigate, tenantSlug, basket, failure,
     setCreating, setDecline, setOrder, setFinalStatus,
   });
-  const payWithEmail = useCallback((email: string) => {
-    if (!method) return;
-    const next = { ...buyer, email };
-    setBuyerState(next);
-    void startPayment(method, next);
-  }, [buyer, method, startPayment]);
-  const handleResolved = useCallback((s: OrderStatus, refusal?: CheckoutDecline | null) => {
-    setDecline(refusal ?? null);
-    setFinalStatus(s);
-    setStep("status");
-  }, []);
+  const { payWithEmail, handleResolved } = useResolutionActions({
+    buyer, method, startPayment, setBuyerState, setDecline, setFinalStatus, setStep,
+  });
   const retry = useRetryAction({
     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);
+}