@12-apps/payments-frontend 3.4.0 → 3.6.0

package/src/activation/use-redirect-activation.ts

@@ -0,0 +1,341 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type React from 'react';
+
+import type { RedirectActivationCopy } from './copy';
+import { mintCharge } from './mint-charge';
+import {
+  postActivation,
+  settleActivationPoll,
+  type ActivationClock,
+  type ActivationPendingBody,
+  type ActivationPollBody,
+  type RedirectActivationState,
+} from './redirect-state';
+import { clearReturnedSettlement, takeReturnedSettlement } from './returned-settlement';
+
+/**
+ * The activation step for a provider whose payer pays on ITS page (FUT-463,
+ * moved here by FUT-763).
+ *
+ * Same proof as a card form, different protocol: a REAL link is minted through
+ * this store's own connection, the owner pays it on the provider's site, and
+ * the provider is then ASKED whether it arrived. Only that answer activates the
+ * store. The alternative — telling an owner to "make a real low-value order and
+ * confirm the money arrives" — is the dead-end instruction the step exists to
+ * abolish.
+ *
+ * ## What is the package's here, and what is not
+ *
+ * `renderVerification` on `PaymentProviderSettings` says the package decides
+ * only WHERE the step appears, never how it works. That still holds for the
+ * SCREEN: the panels, the states an owner reads, the sentences — all of that is
+ * the host's, and none of it is here.
+ *
+ * What is here is the PROTOCOL, which is not a matter of taste and is not
+ * something a second host should get to rediscover: pick the outstanding charge
+ * back up on mount, ask with the return trip's ids on every tick, keep a
+ * refused ATTEMPT distinct from an expired charge, keep an unreachable provider
+ * distinct from a refusing one, stop asking eventually. Every one of those was
+ * learned from a payment that went wrong, and three of them cost a real charge.
+ *
+ * ## Why the attempt is the SERVER's
+ *
+ * It used to live in React state, and that was wrong in a way that costs money.
+ * The flow deliberately sends the owner to another site to pay, so "left this
+ * page and came back" is the NORMAL path, not an edge case — and it erased the
+ * attempt every time. The screen then offered to generate a charge, because as
+ * far as it knew none existed: a second real charge on the owner's own card,
+ * while the first, already paid, was never asked about again.
+ *
+ * So the outstanding charge is loaded from the server on mount, and the only
+ * things that clear it are settlement and an explicit "give up".
+ */
+
+/** How often to ask the provider whether the payment landed. */
+const DEFAULT_POLL_MS = 4000;
+
+/** Give up asking after this long, rather than polling a tab forever. */
+const DEFAULT_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+
+export interface RedirectActivationOptions {
+  /**
+   * The host's verify-charge endpoint for this provider.
+   *
+   * A whole URL, not the parts of one: the route shape belongs to the host and
+   * the package has no business assembling it. `GET` answers the outstanding
+   * charge; `POST` takes `{ action: 'start' | 'poll' | 'discard' }`.
+   */
+  verifyChargeUrl: string;
+  /** A passing charge — the caller refreshes so the provider shows as active. */
+  onVerified: () => void;
+  /**
+   * The provider would not mint a link. Called instead of, not as well as,
+   * settling anything: no charge exists, so there is nothing to confirm — the
+   * caller uses it to reopen the setup step this failure implicates.
+   */
+  onCreateFailed?: () => void;
+  copy: RedirectActivationCopy;
+  /** Where the return trip's ids are parked. Defaults per the package. */
+  storageKey?: string;
+  pollMs?: number;
+  pollTimeoutMs?: number;
+}
+
+export interface RedirectActivation {
+  state: RedirectActivationState;
+  /**
+   * When the provider last answered, as epoch ms (0 before the first ask).
+   *
+   * Shown as "last checked Ns ago". A spinner alone says "something is
+   * happening"; this says the screen is still asking, which is the reassurance
+   * someone who has just paid on another site actually wants — and it is what
+   * stops them pressing a pay button again to be sure.
+   */
+  lastCheckedAt: number;
+  /** Mint the link and begin asking. */
+  start: () => Promise<void>;
+  /** Ask right now, instead of waiting for the next tick. */
+  checkNow: () => Promise<void>;
+  /** Abandon the outstanding charge and offer a fresh one. */
+  reset: () => void;
+}
+
+/**
+ * What the effects call, read through a ref rather than through their deps.
+ *
+ * NOT a style preference — it is what makes the hook safe to hand to a host.
+ * Every callback here changes identity when the caller re-renders without
+ * memoizing, and both effects below would then re-run on it: the resume effect
+ * would re-mount the whole sequence (and, since it sets state, re-render, and
+ * loop), and the poll timer would be cleared and restarted before it ever
+ * ticked — a screen that asks the provider nothing, for ever, while looking
+ * exactly like one that is asking.
+ *
+ * The host that wrote this flow happened to memoize, so neither ever fired
+ * there. A package cannot rely on that: `useRedirectActivation({ onVerified:
+ * () => reload() })` is the obvious way to call it.
+ */
+interface ActivationCallbacks {
+  applyPoll: (body: ActivationPollBody | null) => boolean;
+  returned: () => Record<string, string>;
+  timedOut: string;
+}
+
+/**
+ * Ask the provider every few seconds, and stop asking eventually.
+ *
+ * The give-up is a `failed` state carrying the host's own sentence, because the
+ * wording is load-bearing: the charge is STILL valid, and an owner who has
+ * genuinely paid must not be told they did not pay in time.
+ */
+function usePollTimer(
+  active: boolean,
+  url: string,
+  live: ActivationClock,
+  latest: React.MutableRefObject<ActivationCallbacks>,
+  setState: React.Dispatch<React.SetStateAction<RedirectActivationState>>,
+  pollMs: number,
+  pollTimeoutMs: number,
+): void {
+  useEffect(() => {
+    if (!active) return;
+    const timer = setInterval(() => {
+      if (!live.current.polling) return;
+      if (Date.now() - live.current.startedAt > pollTimeoutMs) {
+        live.current.polling = false;
+        setState({ kind: 'failed', reason: latest.current.timedOut });
+        return;
+      }
+      // WITH the ids, every tick. A hint-less poll is measured to answer "not
+      // paid" for payments that happened — one hinted ask on resume made a
+      // single dropped request fatal.
+      void postActivation(url, 'poll', latest.current.returned()).then((body) =>
+        latest.current.applyPoll(body),
+      );
+    }, pollMs);
+    return () => clearInterval(timer);
+  }, [active, url, live, latest, setState, pollMs, pollTimeoutMs]);
+}
+
+/**
+ * Pick the outstanding charge back up on mount.
+ *
+ * This is what makes the return trip work at all. The owner is sent to the
+ * provider's site to pay and comes back here holding the ids that let the
+ * payment be confirmed — so the very first thing this does on load is ask
+ * whether a charge is outstanding and, if so, check it immediately with
+ * whatever the redirect brought back.
+ */
+function useResumeOutstanding(
+  url: string,
+  live: ActivationClock,
+  latest: React.MutableRefObject<ActivationCallbacks>,
+  setState: React.Dispatch<React.SetStateAction<RedirectActivationState>>,
+): void {
+  useEffect(() => {
+    const alive = { current: true };
+    const carried = latest.current.returned();
+
+    // An owner who came back holding a settlement has DEMONSTRABLY paid, so the
+    // screen must be confirming from the first frame — never showing the pay
+    // button, whatever the pending row says and whatever any single request
+    // does. `checkoutUrl: null` renders the confirming panel without an
+    // open-link button. This also arms the timer, so one dropped request costs
+    // four seconds rather than the payment.
+    if (Object.keys(carried).length > 0) {
+      live.current.polling = true;
+      live.current.startedAt = Date.now();
+      setState({ kind: 'awaiting', checkoutUrl: null });
+    }
+
+    void resumeSequence({ url, live, latest, setState }, carried, alive);
+
+    return () => {
+      alive.current = false;
+    };
+  }, [url, live, latest, setState]);
+}
+
+/** Everything the resume sequence reaches for, gathered once. */
+interface ResumeIo {
+  url: string;
+  live: ActivationClock;
+  latest: React.MutableRefObject<ActivationCallbacks>;
+  setState: React.Dispatch<React.SetStateAction<RedirectActivationState>>;
+}
+
+/** The resume sequence, in the order that keeps a paid return confirmable. */
+async function resumeSequence(
+  io: ResumeIo,
+  carried: Record<string, string>,
+  alive: { current: boolean },
+): Promise<void> {
+  const cameBack = Object.keys(carried).length > 0;
+  // Fired FIRST, and not gated on the pending GET below: this ask depends on
+  // nothing but the returned ids, and chaining it behind another request's
+  // success is how a mid-refresh session cookie once turned a confirmed payment
+  // into a pay button.
+  if (cameBack) {
+    const polled = await postActivation(io.url, 'poll', carried);
+    if (alive.current) io.latest.current.applyPoll(polled);
+  }
+  await restoreOutstanding(io, carried, alive, cameBack);
+}
+
+/**
+ * The GET's answer: the outstanding charge, and whether the server settled it
+ * during this very read (its own heal path).
+ */
+interface OutstandingBody {
+  pending?: ActivationPendingBody;
+  proven?: boolean;
+}
+
+async function readOutstanding(url: string): Promise<OutstandingBody | null> {
+  const response = await fetch(url).catch(() => null);
+  if (!response?.ok) return null;
+  return (await response.json().catch(() => null)) as OutstandingBody | null;
+}
+
+/** Restore the server's pending row into the screen, and ask once if idle. */
+async function restoreOutstanding(
+  io: ResumeIo,
+  carried: Record<string, string>,
+  alive: { current: boolean },
+  cameBack: boolean,
+): Promise<void> {
+  const body = await readOutstanding(io.url);
+  if (!body || !alive.current) return;
+  // Settled server-side while we were reading — the charge is done, and the one
+  // thing this must not do now is resume a pay flow for it.
+  if (body.proven) {
+    io.latest.current.applyPoll({ ok: true });
+    return;
+  }
+  const pending = body.pending;
+  if (!pending) return;
+
+  io.live.current.polling = true;
+  io.live.current.startedAt = Date.parse(pending.startedAt) || Date.now();
+  io.setState((current) =>
+    current.kind === 'passed' || current.kind === 'failed'
+      ? current
+      : { kind: 'awaiting', checkoutUrl: pending.checkoutUrl },
+  );
+  if (!cameBack) {
+    const polled = await postActivation(io.url, 'poll', carried);
+    if (alive.current) io.latest.current.applyPoll(polled);
+  }
+}
+
+export function useRedirectActivation(options: RedirectActivationOptions): RedirectActivation {
+  const {
+    verifyChargeUrl: url,
+    onVerified,
+    onCreateFailed,
+    copy,
+    storageKey,
+    pollMs = DEFAULT_POLL_MS,
+    pollTimeoutMs = DEFAULT_POLL_TIMEOUT_MS,
+  } = options;
+
+  const [state, setState] = useState<RedirectActivationState>({ kind: 'idle' });
+  const [lastCheckedAt, setLastCheckedAt] = useState(0);
+  // Read inside the interval callback so the timer never closes over a stale
+  // state — mutating a ref's property rather than reassigning a captured
+  // binding, which the flakiness lint rightly rejects.
+  const live = useRef({ polling: false, startedAt: 0 });
+
+  const returned = useCallback(() => takeReturnedSettlement(storageKey), [storageKey]);
+
+  const applyPoll = useCallback(
+    (body: ActivationPollBody | null): boolean => {
+      // Stamped even on a dropped request: the counter reports when we last
+      // ASKED, and freezing it on a network blip would read as a stalled screen.
+      setLastCheckedAt(Date.now());
+      return settleActivationPoll(body, {
+        live,
+        setState,
+        onVerified,
+        clearSettlement: () => clearReturnedSettlement(storageKey),
+        copy,
+      });
+    },
+    [onVerified, storageKey, copy],
+  );
+
+  const latest = useRef<ActivationCallbacks>({
+    applyPoll,
+    returned,
+    timedOut: copy.confirmTimedOut,
+  });
+  latest.current = { applyPoll, returned, timedOut: copy.confirmTimedOut };
+
+  useResumeOutstanding(url, live, latest, setState);
+  usePollTimer(state.kind === 'awaiting', url, live, latest, setState, pollMs, pollTimeoutMs);
+
+  const start = useCallback(
+    () => mintCharge({ url, live, setState, copy, onCreateFailed }),
+    [url, copy, onCreateFailed],
+  );
+
+  const checkNow = useCallback(async () => {
+    applyPoll(await postActivation(url, 'poll', returned()));
+  }, [applyPoll, url, returned]);
+
+  /**
+   * Give up on the outstanding charge — and tell the SERVER so.
+   *
+   * Clearing only the local state would leave the charge on record, so the very
+   * next load would resume the attempt the owner just abandoned.
+   */
+  const reset = useCallback(() => {
+    live.current.polling = false;
+    setState({ kind: 'idle' });
+    void postActivation(url, 'discard');
+  }, [url]);
+
+  return { state, lastCheckedAt, start, checkNow, reset };
+}

package/src/components/checkout/checkout-steps.tsx

@@ -3,12 +3,7 @@ import { useEffect, useRef, type JSX, type ReactNode } from "react";
 
 import { BuyerInfoForm } from "./buyer-info-form";
 import { LockOutlinedIcon } from "./icons";
-import {
-  cardPathAvailable,
-  offeredMethods,
-  selectableMethods,
-  usePreselectSoleMethod,
-} from "./method-capability";
+import { useMethodChoice } from "./method-choice";
 import { MethodPicker } from "./method-picker";
 import { PaymentErrorPanel } from "./payment-error-panel";
 import { PayerSummary } from "./payer-summary";
@@ -42,8 +37,8 @@ function useAutoRaiseOrder(
       requestedFor.current = null;
       return;
     }
-    // No method chosen yet ⇒ show only the picker; raise the order once the
-    // buyer selects PIX or card.
+    // No method chosen yet ⇒ show only the picker (or, for a hand-off store,
+    // its "Seguir para o pagamento"); raise the order once the buyer commits.
     if (!method || creating || createError || requestedFor.current === method) return;
     requestedFor.current = method;
     onGenerate(method);
@@ -70,6 +65,8 @@ function PaymentBody({
   method,
   tenantSlug,
   onResolved,
+  onStart,
+  creating,
   pollIntervalMs,
   validateApplePayMerchant,
 }: {
@@ -79,6 +76,9 @@ function PaymentBody({
   method: PaymentMethod | null;
   tenantSlug?: string;
   onResolved: (status: OrderStatus) => void;
+  /** Set only when the shell hid its picker — see {@link PaymentStep}. */
+  onStart?: () => void;
+  creating: boolean;
   pollIntervalMs?: number;
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
 }): JSX.Element | null {
@@ -91,6 +91,8 @@ function PaymentBody({
       method={method}
       tenantSlug={tenantSlug}
       onResolved={onResolved}
+      onStart={onStart}
+      creating={creating}
       pollIntervalMs={pollIntervalMs}
       validateApplePayMerchant={validateApplePayMerchant}
     />
@@ -303,6 +305,17 @@ interface PaymentStepProps {
  * Step 2 "Pagamento" — pick PIX or card and pay on the SAME page. Selecting a
  * method auto-raises its order and reveals its UI (PIX QR / card form) with no
  * intermediate tap; switching method clears the previous order (controller).
+ *
+ * ## Unless the choice is not ours to ask
+ *
+ * A store that finishes checkout on the provider's own page gets NO picker
+ * here (`methodChosenAtProvider`). Its screen renders a single "Seguir para o
+ * pagamento" instead, and pressing it selects the store's hand-off method —
+ * which is the same event a tile press is, so the auto-raise, the error panel
+ * and the retry below all keep working unchanged. Preselection is suppressed
+ * for the same flow, and deliberately: it exists to spare a buyer a tap that
+ * buys them nothing, but here the tap is the buyer's consent to LEAVE, and
+ * taking it for them would redirect a checkout the moment it rendered.
  */
 export function PaymentStep({
   method,
@@ -323,35 +336,42 @@ export function PaymentStep({
   onResolved,
 }: PaymentStepProps): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
-  const cardUnavailable = !cardPathAvailable(providerConfig ?? null);
-  const offered = offeredMethods(providerConfig ?? null);
+  const config = providerConfig ?? null;
+  const choice = useMethodChoice(config, method, onMethodChange);
   useAutoRaiseOrder(order, method, creating, createError, onGenerate);
-  usePreselectSoleMethod(selectableMethods(offered, cardUnavailable), method, onMethodChange);
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
       {/* Self-hiding: renders only for a flow whose Dados step was skipped. */}
       <PayerSummary name={buyer.name} taxId={buyer.taxId} onEdit={onEditBuyer} />
 
-      <MethodPicker
-        value={method}
-        onChange={onMethodChange}
-        cardUnavailable={cardUnavailable}
-        offered={offered}
-      />
+      {choice.atProvider ? null : (
+        <MethodPicker
+          value={method}
+          onChange={onMethodChange}
+          cardUnavailable={choice.cardUnavailable}
+          offered={choice.offered}
+        />
+      )}
 
       <PaymentBody
         order={order}
         buyer={buyer}
-        providerConfig={providerConfig ?? null}
+        providerConfig={config}
         method={method}
         tenantSlug={tenantSlug}
         onResolved={onResolved}
+        onStart={choice.onStart}
+        creating={creating}
         pollIntervalMs={pollIntervalMs}
         validateApplePayMerchant={validateApplePayMerchant}
       />
 
-      {!order && creating ? (
+      {/* The shell's own busy spinner, SUPPRESSED for a hand-off screen: that
+          screen renders its own "Preparando o pagamento" while the charge is
+          raised, and two stacked spinners saying the same thing is what the
+          buyer actually saw. */}
+      {!order && creating && !choice.atProvider ? (
         <LoadingState variant="spinner" size="md" message="Gerando pagamento…" dataTestId="payment-generating" />
       ) : null}
 

package/src/components/checkout/method-capability.ts

@@ -216,6 +216,33 @@ export function selectableMethods(
   );
 }
 
+/**
+ * The method a HAND-OFF checkout raises on the buyer's behalf, when the buyer
+ * was never asked (see `providers/registry.ts`'s `methodChosenAtProvider`).
+ *
+ * A charge still has to be raised with SOME method — that is the wire's shape,
+ * and the link is minted by raising it — but for a hand-off store the value is
+ * provisional by construction: the buyer picks for real on the provider's page,
+ * and the settlement reports back which one they actually used. So the choice
+ * here is about which request the SERVER will honour, not about what the buyer
+ * gets.
+ *
+ * PIX when the chain offers it, because PIX is the one method whose first
+ * charge is always raised immediately: a CARD request at a store that can
+ * tokenize somewhere in its chain is answered with the bare order instead, and
+ * there is no hand-off link on that answer to send anyone anywhere. Otherwise
+ * the chain's first declared method, since a store that cannot PIX would have
+ * the walk refuse a PIX charge outright.
+ *
+ * `null` offered — still loading, or a fetch blip — cannot reach here: the
+ * picker is only hidden for a store whose config already said it hands over.
+ * PIX is the safe reading of it anyway, for the reason above.
+ */
+export function handOffMethod(offered: PaymentMethod[] | null): PaymentMethod {
+  if (!offered || offered.includes("PIX")) return "PIX";
+  return offered[0] ?? "PIX";
+}
+
 /**
  * A SOLE remaining method is not a choice — take it (FUT-697 review, widened by
  * FUT-741).

package/src/components/checkout/method-choice.ts

@@ -0,0 +1,64 @@
+/**
+ * WHO asks the buyer PIX-or-card, and what the Pagamento step does about it.
+ *
+ * Its own module because the answer is a set of derived facts that must move
+ * together: a picker rendered for a store that hands the buyer over, or a
+ * hand-off CTA rendered beside a picker, are both a checkout asking one
+ * question twice — which is the defect this seam exists to make impossible.
+ */
+import {
+  cardPathAvailable,
+  handOffMethod,
+  offeredMethods,
+  selectableMethods,
+  usePreselectSoleMethod,
+} from "./method-capability";
+import { methodChosenAtProvider } from "./providers/registry";
+import type { CheckoutProviderConfig, PaymentMethod } from "./types";
+
+/** What the Pagamento step needs to know about WHO asks the buyer for a method. */
+interface MethodChoice {
+  /** The store's active provider has no card path in this browser. */
+  cardUnavailable: boolean;
+  /** The methods the chain declares it can charge, or `null` while unknown. */
+  offered: PaymentMethod[] | null;
+  /** The choice is made on the provider's page ⇒ render no picker here. */
+  atProvider: boolean;
+  /**
+   * The hand-off screen's "start paying" port, or `undefined` when the picker
+   * is on the page and owns that job instead. It SELECTS the store's hand-off
+   * method, which is the same event a tile press is — so the auto-raise, the
+   * error panel and its retry all keep working with no second code path.
+   */
+  onStart?: () => void;
+}
+
+/**
+ * Resolve who asks the buyer PIX-or-card, and preselect a sole method when the
+ * question is ours to ask.
+ */
+export function useMethodChoice(
+  config: CheckoutProviderConfig | null,
+  method: PaymentMethod | null,
+  onMethodChange: (method: PaymentMethod) => void,
+): MethodChoice {
+  const cardUnavailable = !cardPathAvailable(config);
+  const offered = offeredMethods(config);
+  const atProvider = methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config);
+  // Nothing to preselect when the screen owns the choice: the whole point of
+  // its button is that the buyer presses it. Preselection exists to spare them
+  // a tap that buys them nothing, and here the tap is their consent to LEAVE —
+  // taking it for them would redirect a checkout the moment it rendered.
+  usePreselectSoleMethod(
+    atProvider ? [] : selectableMethods(offered, cardUnavailable),
+    method,
+    onMethodChange,
+  );
+  if (!atProvider) return { cardUnavailable, offered, atProvider };
+  return {
+    cardUnavailable,
+    offered,
+    atProvider,
+    onStart: () => onMethodChange(handOffMethod(offered)),
+  };
+}

package/src/components/checkout/providers/capability-default.tsx

@@ -19,45 +19,11 @@
  */
 import type { JSX } from "react";
 
-import type { CheckoutProviderConfig } from "../types";
-
+import { handsBuyerOver } from "./hands-over";
 import { HostedLinkScreen } from "./hosted-link";
 import { PixAndCardScreen } from "./pix-and-card";
 import type { ProviderCheckoutScreenProps } from "./types";
 
-/** Schemes that give the BROWSER a card form of its own. */
-const IN_BROWSER_TOKENIZATION: ReadonlySet<string> = new Set(["PUBLIC_KEY", "SDK"]);
-
-/**
- * Whether this store hands the buyer over instead of collecting here — the
- * frontend twin of the server's `usesHostedCheckout`, deliberately written to
- * the same three rules so the pane and the walk cannot disagree.
- *
- * Note this is NOT `!cardPathAvailable(config)`. That helper answers a
- * different question — "is a card offerable at all" — and it answers TRUE for
- * a hand-off store, because typing the card on the provider's page is still a
- * card path. Inverting it therefore sends the hosted store to the on-page
- * screen and the on-page store to the hand-off, which is exactly backwards.
- *
- * The rules, in order:
- *   - Only CARD can be answered in advance. TOKENIZATION IS A CARD FACT: it
- *     says how the browser turns a PAN into an instrument, and a PIX charge
- *     has no instrument to mint. A store with no card-capable entry is not
- *     hosted — this is the FUT-747 correction, and getting it wrong routed the
- *     simplest store there is (one PIX-only provider honestly declaring
- *     `NONE`) into a hand-off it had no link for.
- *   - Hosted only when NOBODY who takes a card takes it here.
- *   - No chain served (an older host, a still-loading config) ⇒ not hosted,
- *     which is what this checkout did before there was a chain to read.
- */
-function handsBuyerOver(config: CheckoutProviderConfig | null): boolean {
-  const chain = config?.chain;
-  if (!chain || chain.length === 0) return false;
-  const cardCapable = chain.filter((link) => link.methods.includes("CARD"));
-  if (cardCapable.length === 0) return false;
-  return !cardCapable.some((link) => IN_BROWSER_TOKENIZATION.has(link.tokenization));
-}
-
 export function CapabilityDefaultScreen(props: ProviderCheckoutScreenProps): JSX.Element | null {
   return handsBuyerOver(props.config) ? (
     <HostedLinkScreen {...props} />

package/src/components/checkout/providers/hands-over.ts

@@ -0,0 +1,43 @@
+/**
+ * Whether a store finishes checkout on the PROVIDER's own page.
+ *
+ * Its own module because two callers need the same answer and must never be
+ * able to disagree about it: {@link CapabilityDefaultScreen}, which picks the
+ * pane for a provider that declared no screen, and the shell's picker gate,
+ * which decides whether the buyer is asked PIX-or-card here at all. It lived
+ * inside `capability-default.tsx` while there was one caller.
+ */
+import type { CheckoutProviderConfig } from "../types";
+
+/** Schemes that give the BROWSER a card form of its own. */
+const IN_BROWSER_TOKENIZATION: ReadonlySet<string> = new Set(["PUBLIC_KEY", "SDK"]);
+
+/**
+ * Whether this store hands the buyer over instead of collecting here — the
+ * frontend twin of the server's `usesHostedCheckout`, deliberately written to
+ * the same three rules so the pane and the walk cannot disagree.
+ *
+ * Note this is NOT `!cardPathAvailable(config)`. That helper answers a
+ * different question — "is a card offerable at all" — and it answers TRUE for
+ * a hand-off store, because typing the card on the provider's page is still a
+ * card path. Inverting it therefore sends the hosted store to the on-page
+ * screen and the on-page store to the hand-off, which is exactly backwards.
+ *
+ * The rules, in order:
+ *   - Only CARD can be answered in advance. TOKENIZATION IS A CARD FACT: it
+ *     says how the browser turns a PAN into an instrument, and a PIX charge
+ *     has no instrument to mint. A store with no card-capable entry is not
+ *     hosted — this is the FUT-747 correction, and getting it wrong routed the
+ *     simplest store there is (one PIX-only provider honestly declaring
+ *     `NONE`) into a hand-off it had no link for.
+ *   - Hosted only when NOBODY who takes a card takes it here.
+ *   - No chain served (an older host, a still-loading config) ⇒ not hosted,
+ *     which is what this checkout did before there was a chain to read.
+ */
+export function handsBuyerOver(config: CheckoutProviderConfig | null): boolean {
+  const chain = config?.chain;
+  if (!chain || chain.length === 0) return false;
+  const cardCapable = chain.filter((link) => link.methods.includes("CARD"));
+  if (cardCapable.length === 0) return false;
+  return !cardCapable.some((link) => IN_BROWSER_TOKENIZATION.has(link.tokenization));
+}