@eifi1/ui-kit 0.32.2 → 0.33.0

package/src/billing/billing-labels.ts

@@ -129,6 +129,13 @@ export interface BillingLabels {
   usage: (used: string, limit: string) => string;
   /** The subject of the `contact` mail; `dimension` is the app's name for it ("Budgets"). */
   contactSubject: (dimension: string) => string;
+  /**
+   * The figure line of the limit's toast (`usePlanLimitToast`, §14.11) and of an
+   * operator's plan change over the new limit (§14.12): "Budgets: 3 of 3". A key of its
+   * own rather than `${dimension}: ${usage}`, because French puts a space before the
+   * colon. Both figures are formatted already.
+   */
+  limitUsageLine: (dimension: string, used: string, limit: string) => string;
 
   /* ── The provider's portal (§7, §12.26) ── */
   /** The portal: payment method and invoices (§2.8, the provider hosts both). */
@@ -139,6 +146,24 @@ export interface BillingLabels {
    * as unambiguously — a translator should use exactly that.
    */
   cancel: string;
+  /**
+   * In place of both while the payer hasn't reached the provider (the overview's
+   * `at_provider` is false, §14.5): there is no customer to open a portal for yet. Also
+   * the words for `409 billing_not_at_provider`, a stale page that asked anyway.
+   */
+  notAtProvider: string;
+
+  /* ── The pay page (§14.4) ── */
+  /* Built into the static page `dist/pay/` at the kit's build: it has no React and no
+     provider, so an app's override never reaches it. */
+  /** While the checkout opens. */
+  payOpening: string;
+  /** A link without a transaction, or billing switched off: nothing to pay. */
+  payNothing: string;
+  /** Paddle's script didn't load, or the page's configuration is wrong. */
+  payFailed: string;
+  /** The buyer closed the checkout without paying. */
+  payBack: string;
 
   /* ── Offline (§12.5) ── */
   /** Changes refused as `billing_read_only` inside a sync reply, kept queued and sent
@@ -159,6 +184,16 @@ export interface BillingLabels {
   /** `billing_disabled`: billing is switched off on this server (§2.9), for a page or a
    *  link that reached it anyway. */
   disabled: string;
+  /* 0.33.0 — server-kit 0.7's refusals (§14.2). `billing_not_at_provider` is
+     {@link notAtProvider}'s: a stale page that asked for the portal anyway. */
+  /** `billing_provider_unavailable` (502): the provider didn't answer. Try again. */
+  providerUnavailable: string;
+  /** `billing_already_subscribed` (409): a second checkout while a subscription runs
+   *  (§14.6) — plan changes go through the portal. */
+  alreadySubscribed: string;
+  /** `billing_plan_not_sold` (422): the catalogue doesn't sell this plan with that
+   *  period or currency. */
+  planNotSold: string;
 }
 
 /** "today", "tomorrow", "in 5 days". */
@@ -221,9 +256,16 @@ export const DEFAULT_BILLING_LABELS: BillingLabels = {
   askForMore: "Ask for more",
   usage: (used, limit) => `${used} of ${limit}`,
   contactSubject: (dimension) => `Plan limit: ${dimension}`,
+  limitUsageLine: (dimension, used, limit) => `${dimension}: ${used} of ${limit}`,
 
   manage: "Payment and invoices",
   cancel: "Cancel subscription",
+  notAtProvider: "Nothing to manage yet. Payments and invoices appear here once you have a paid plan.",
+
+  payOpening: "Opening the secure checkout…",
+  payNothing: "There’s no payment to make here. To choose a plan, go back to the app.",
+  payFailed: "The checkout couldn’t be opened. Please go back and try again in a moment.",
+  payBack: "The checkout was closed. You can go back, or reload this page to open it again.",
 
   waitingChanges: (count) =>
     count === 1 ? "1 change waiting for a plan" : `${count} changes waiting for a plan`,
@@ -231,6 +273,9 @@ export const DEFAULT_BILLING_LABELS: BillingLabels = {
 
   notConfigured: "Payments aren't set up yet. Please try again later.",
   disabled: "Subscriptions aren't available here.",
+  providerUnavailable: "The payment provider can’t be reached right now. Please try again in a moment.",
+  alreadySubscribed: "You already have a subscription. To change your plan, go to “Payment and invoices”.",
+  planNotSold: "This plan isn’t offered for that billing period or currency. Please choose another.",
 };
 
 /** The `billing` namespace, resolved: English, then the provider, then `labels` — which

package/src/billing/billing-lock.ts

@@ -1,14 +1,21 @@
 import type { ReactNode } from "react";
 
 import type { LabelOverride } from "../i18n/kit-labels";
+import type { WriteLockHold, WriteLockKind } from "../components/write-lock";
 import { useBillingLabels } from "./billing-labels";
 import type { BillingLabels } from "./billing-labels";
 
-/** One reason an app may lock writing: whether it locks now, and its one sentence. */
+/** One reason an app may lock writing: whether it locks now, its one sentence, and what
+ *  kind of lock it is. */
 export interface WriteLockSource {
   locked: boolean;
   /** The sentence a locked commit shows ("Not possible in the demo."). */
   reason?: ReactNode;
+  /**
+   * `"demo"`, `"billing"`, or the app's own (§12.36): a control's `commit` may be exempt
+   * from a kind — `COMMIT_EXCEPT_BILLING`. Left out, no control can be exempt from it.
+   */
+  kind?: WriteLockKind;
 }
 
 /** What {@link combineWriteLocks} answers: the props of one `WriteLockProvider`. */
@@ -16,6 +23,9 @@ export interface CombinedWriteLock {
   locked: boolean;
   /** The first locked source's reason; `undefined` while nothing locks. */
   reason: ReactNode | undefined;
+  /** EVERY locked source, kind and reason, in the order given (§12.36) — so a control
+   *  exempt from billing under the demo's lock and billing's still finds the demo's. */
+  holds: WriteLockHold[];
 }
 
 /**
@@ -41,14 +51,21 @@ export interface CombinedWriteLock {
  * not two joined: a tooltip answers "why can't I?" once, and in practice one source locks
  * at a time — demo users have no subscription row and are never gated (§12.7). `null`,
  * `undefined` and `false` entries are skipped, for `cond && { … }`.
+ *
+ * 0.33 (§12.36): name each source's `kind` — `{ locked, reason, kind: "demo" }`,
+ * {@link useBillingWriteLock} for billing — and `holds` carries every locked one, in
+ * order, so the kit's parts that a lapsed plan still allows (removing access, the
+ * account's own settings, an operator's plan change) reopen under billing by themselves
+ * while the demo's lock still holds them.
  */
 export function combineWriteLocks(
   sources: ReadonlyArray<WriteLockSource | null | undefined | false>,
 ): CombinedWriteLock {
+  const holds: WriteLockHold[] = [];
   for (const source of sources) {
-    if (source && source.locked) return { locked: true, reason: source.reason };
+    if (source && source.locked) holds.push({ kind: source.kind, reason: source.reason });
   }
-  return { locked: false, reason: undefined };
+  return { locked: holds.length > 0, reason: holds[0]?.reason, holds };
 }
 
 export interface BillingLockReasonOptions {
@@ -73,3 +90,19 @@ export function useBillingLockReason(options: BillingLockReasonOptions = {}): st
   const labels = useBillingLabels(options.labels);
   return options.guest ? labels.guestReadOnly(options.item) : labels.lockReason;
 }
+
+/**
+ * Billing's lock as one source for {@link combineWriteLocks}: `{ locked, reason, kind:
+ * "billing" }`, the reason the payer's or a guest's as {@link useBillingLockReason} says
+ * it (§12.36). The kind is what lets the kit's parts that §3.3 and §12.13 allow stay live
+ * under it.
+ *
+ *     <WriteLockProvider {...combineWriteLocks([
+ *       { locked: demoReadOnly, reason: demo.writeLocked, kind: "demo" },
+ *       useBillingWriteLock(budget.locked === "billing", { guest: !isOwner, item: budget.name }),
+ *     ])}>
+ */
+export function useBillingWriteLock(locked: boolean, options: BillingLockReasonOptions = {}): WriteLockSource {
+  const reason = useBillingLockReason(options);
+  return { locked, reason, kind: "billing" };
+}

package/src/billing/billing-overview.ts

@@ -0,0 +1,58 @@
+import type { DateInput } from "../lib/format";
+import type { SubscriptionStatus } from "./billing-labels";
+import type { BillingCurrency } from "./plan-price";
+
+/**
+ * The billing API's shapes the kit's parts read (docs/billing-harmonization.md §4,
+ * §14.5) — server-kit 0.7's schemas, field for field under their wire names, for an app
+ * whose client is hand-written (kastlan's `features/billing/types.ts`, Kurvenschmiede's
+ * `shared/types/billing.ts`, which no mirror test covers).
+ */
+
+/** Where a row's current state came from (server-kit's `SubscriptionSource`, §3.2). */
+export type SubscriptionSource = "trial" | "provider" | "manual" | "beta";
+
+/** `GET /billing/overview` (§4): where the payer's subscription stands, what the plan
+ *  allows and what is used. Only ever the payer's own (§12.6). */
+export interface BillingOverview {
+  /** The plan's code, lowercase (§3.1). */
+  plan: string;
+  status: SubscriptionStatus;
+  source: SubscriptionSource;
+  /** False: read-only (§3.3). */
+  in_good_standing: boolean;
+  trial_ends_at: DateInput;
+  /** When the free grant ends; null: no end. */
+  comped_until: DateInput;
+  current_period_end: DateInput;
+  cancel_at_period_end: boolean;
+  /** Dimension → limit; null for unlimited. */
+  limits: Record<string, number | null>;
+  /** What the payer has, per dimension (§12.15). */
+  usage: Record<string, number>;
+  currency: BillingCurrency;
+  /**
+   * 0.7 (§14.5): the provider has a customer for this payer, whatever the status or the
+   * source — `SubscriptionActions`' `atProvider`. False: "nothing to manage yet", and a
+   * portal request would answer `409 billing_not_at_provider`.
+   */
+  at_provider: boolean;
+}
+
+/**
+ * Where in the provider's portal a request lands (server-kit's `PortalTarget`, §14.5):
+ *
+ * - `overview` — "Payment and invoices";
+ * - `cancel` — "Cancel subscription": the subscription's cancel link (§12.26);
+ * - `payment_method` — the payment-failed banner's "Update payment method".
+ *
+ * The server answers the overview where Paddle gives no such link (a paused or cancelled
+ * subscription).
+ */
+export type PortalTarget = "overview" | "cancel" | "payment_method";
+
+/** `POST /billing/portal`'s optional body (server-kit's `PortalRequest`, §14.5); left
+ *  out, the overview. The answer is `{url}`, a fresh link that is never stored. */
+export interface PortalRequest {
+  target?: PortalTarget;
+}

package/src/billing/checkout-processing.ts

@@ -0,0 +1,391 @@
+import { useCallback, useEffect, useEffectEvent, useLayoutEffect, useRef, useSyncExternalStore } from "react";
+
+import { toDate } from "../lib/format";
+import type { DateInput } from "../lib/format";
+import { readStored, writeStored } from "../lib/safe-storage";
+import type { BillingStanding } from "./billing-standing";
+
+/**
+ * "Payment processing" after the way back from a checkout (docs/billing-harmonization.md
+ * §12.21, §14.4; keksdose's `features/billing/checkout-return.ts`, made router-agnostic).
+ *
+ * The provider tells the app about a payment by WEBHOOK, and the webhook may land after
+ * the buyer is back: Cloud Run scales to zero, and a cold start can outlast the
+ * provider's redirect. Without this, someone who has just paid comes back to a page that
+ * still says their trial has ended. So the return is recognised (`?checkout=done`,
+ * `isCheckoutReturn`), the page says "your payment is being processed"
+ * (`BillingBanner kind="processing"`), and the overview is asked again every few seconds
+ * until it has moved.
+ *
+ * **"Landed" is judged against the overview at departure** ({@link checkoutFingerprint},
+ * noted by {@link noteCheckoutStarted}), not by "is it `active` yet": a trial and a beta
+ * grant can both buy, and a running free grant keeps its status whatever the provider
+ * says (§12.11) — only its period end moves — so "active" alone would wait for ever on
+ * one of them. A return with no departure on record (another tab, another device) waits
+ * for `active`. kastlan's 60-second poll for `source === "provider"` is the case this
+ * replaces: a payer who bought under a grant never matched it.
+ *
+ * **Bounded:** after `timeoutMs` (10 minutes) the device stops asking, and the page says
+ * what the overview says, whatever that is — a checkout abandoned at the provider must
+ * not leave "processing" up for good.
+ *
+ * **Remembered across the whole-page return, per payer.** The departure goes into the
+ * browser's storage through the kit's safe storage (a throwing storage — Safari's
+ * private mode — keeps it in memory for this page instead), under `storageKey`; a mark
+ * names its payer, so it never speaks for another account on a shared device. It is a
+ * browser entry on the app's origin: an app whose privacy text lists its entries names
+ * it (Kurvenschmiede passes its own key).
+ */
+
+/** The overview fields a completed checkout changes (wire names, `GET /billing/overview`).
+ *  Pass the overview as it came; the other fields are ignored. */
+export type CheckoutOverview = Pick<BillingStanding, "status" | "in_good_standing"> & {
+  plan: string;
+  source: string;
+  current_period_end?: DateInput;
+};
+
+/** How long a return keeps the page in "processing" before it trusts the overview. */
+const PROCESSING_FOR = 10 * 60_000;
+/** How often the overview is asked meanwhile. */
+const POLL_EVERY = 4_000;
+/** The browser entry, unless the app names its own. */
+const STORAGE_KEY = "eifi1-billing-checkout";
+
+/**
+ * What of the overview a completed checkout changes, as one string: the plan (read
+ * without case, §12.16), the status, the source, the standing and the period's end (read
+ * as an instant, so `…Z` and `…+00:00` agree).
+ */
+export function checkoutFingerprint(o: CheckoutOverview): string {
+  const end = toDate(o.current_period_end ?? null);
+  return [
+    String(o.plan ?? "").toLowerCase(),
+    o.status,
+    o.source,
+    String(o.in_good_standing),
+    end ? end.toISOString() : "",
+  ].join("|");
+}
+
+/**
+ * Whether the overview `now` shows the checkout: it differs from the fingerprint taken
+ * at departure (`before`), or — with no departure on record — it is `active`.
+ */
+export function checkoutLanded(before: string | null, now: CheckoutOverview): boolean {
+  return before === null ? now.status === "active" : checkoutFingerprint(now) !== before;
+}
+
+/* ── The store: one per storage key, shared by every mounted instance ─────── */
+
+interface PendingCheckout {
+  /** Whose checkout: a user's or a company's id, as a string. */
+  payer: string;
+  /** The overview's fingerprint at departure, or null when it was not known. */
+  before: string | null;
+  /** When the buyer came back; null while they are (or were) at the provider. */
+  returnedAt: number | null;
+}
+
+/** One mounted hook: what the shared timers call, kept current on every render. */
+interface Instance {
+  payer: string | null;
+  refetch: () => unknown;
+  onLanded: (() => void) | undefined;
+  timeoutMs: number;
+  pollMs: number;
+}
+
+interface CheckoutStore {
+  key: string;
+  pending: PendingCheckout | null;
+  listeners: Set<() => void>;
+  /** The mounted instances, in mount order: the last is the latest. */
+  instances: Instance[];
+  poll: ReturnType<typeof setInterval> | null;
+  pollEvery: number;
+  expiry: ReturnType<typeof setTimeout> | null;
+  expiryAt: number | null;
+  /** An instance consumed the marker in this commit; the others leave it be. */
+  consuming: boolean;
+}
+
+/** Module-level, so the banner's instance and the subscription page's share one state,
+ *  one poll and one landing (keksdose mounts the hook twice, §14.4). */
+const stores = new Map<string, CheckoutStore>();
+
+function readPending(key: string): PendingCheckout | null {
+  const raw = readStored(key);
+  if (raw === null) return null;
+  try {
+    const value = JSON.parse(raw) as Partial<PendingCheckout> | null;
+    if (
+      value &&
+      typeof value.payer === "string" &&
+      (value.before === null || typeof value.before === "string") &&
+      (value.returnedAt === null || typeof value.returnedAt === "number")
+    ) {
+      return { payer: value.payer, before: value.before, returnedAt: value.returnedAt };
+    }
+  } catch {
+    // Not ours, or damaged: as if nothing was noted.
+  }
+  return null;
+}
+
+/** Drop the browser entry. lib/safe-storage reads and writes; removing needs the same
+ *  guard (a blocked storage throws on access). */
+function forget(key: string): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+    // ignore (private mode, partitioned storage)
+  }
+}
+
+function storeOf(key: string): CheckoutStore {
+  let store = stores.get(key);
+  if (!store) {
+    store = {
+      key,
+      pending: readPending(key),
+      listeners: new Set(),
+      instances: [],
+      poll: null,
+      pollEvery: 0,
+      expiry: null,
+      expiryAt: null,
+      consuming: false,
+    };
+    stores.set(key, store);
+  }
+  return store;
+}
+
+function setPending(store: CheckoutStore, next: PendingCheckout | null): void {
+  store.pending = next;
+  if (next) writeStored(store.key, JSON.stringify(next));
+  else forget(store.key);
+  for (const listener of store.listeners) listener();
+  sync(store);
+}
+
+/** The latest mounted instance's refetch, failures swallowed: a poll that fails is
+ *  simply asked again at the next tick. */
+function refetchLatest(store: CheckoutStore): void {
+  const latest = store.instances.at(-1);
+  if (!latest) return;
+  try {
+    const result = latest.refetch() as PromiseLike<unknown> | undefined;
+    if (result && typeof result.then === "function") result.then(undefined, () => {});
+  } catch {
+    // as above
+  }
+}
+
+/** Arms or stops the store's two timers — the bound and the poll — for its state. */
+function sync(store: CheckoutStore): void {
+  const pending = store.pending;
+  const latest = store.instances.at(-1);
+  const returnedAt = pending?.returnedAt ?? null;
+
+  if (returnedAt === null) {
+    if (store.expiry) clearTimeout(store.expiry);
+    store.expiry = null;
+    store.expiryAt = null;
+  } else {
+    const at = returnedAt + (latest?.timeoutMs ?? PROCESSING_FOR);
+    if (at <= Date.now()) {
+      setPending(store, null);
+      return;
+    }
+    if (store.expiryAt !== at) {
+      if (store.expiry) clearTimeout(store.expiry);
+      store.expiryAt = at;
+      store.expiry = setTimeout(() => {
+        store.expiry = null;
+        store.expiryAt = null;
+        if (store.pending === pending) setPending(store, null);
+      }, at - Date.now());
+    }
+  }
+
+  // One poll for every instance, while a mounted one is the mark's payer.
+  const watching = returnedAt !== null && store.instances.some((i) => i.payer === pending!.payer);
+  const every = latest?.pollMs ?? POLL_EVERY;
+  if (!watching) {
+    if (store.poll) clearInterval(store.poll);
+    store.poll = null;
+  } else if (!store.poll || store.pollEvery !== every) {
+    if (store.poll) clearInterval(store.poll);
+    store.pollEvery = every;
+    store.poll = setInterval(() => refetchLatest(store), every);
+  }
+}
+
+/** A mounted instance joins the store's timers; the latest is the one they call. */
+function register(store: CheckoutStore, instance: Instance): () => void {
+  store.instances.push(instance);
+  return () => {
+    store.instances = store.instances.filter((i) => i !== instance);
+    sync(store);
+  };
+}
+
+/**
+ * Whether this instance is the one to consume a return marker: the first in a commit is.
+ * Another instance in the same commit sees the same marker and leaves it be; the claim
+ * lapses once the commit's effects have run.
+ */
+function claimReturn(store: CheckoutStore): boolean {
+  if (store.consuming) return false;
+  store.consuming = true;
+  void Promise.resolve().then(() => {
+    store.consuming = false;
+  });
+  return true;
+}
+
+/**
+ * Note the departure for a checkout — just before the page leaves for the provider (or
+ * for the pay page, `payPageUrl(url, locale)`):
+ *
+ *     noteCheckoutStarted(user.id, overview.data);
+ *     window.location.assign(payPageUrl(url, i18n.language));
+ *
+ * `payer` is the user's or the company's id: a mark never speaks for another payer.
+ * `overview` is what the page shows now; left out, the return waits for `active`. Pass
+ * the same `storageKey` as the hook's.
+ */
+export function noteCheckoutStarted(
+  payer: string | number,
+  overview?: CheckoutOverview,
+  opts: { storageKey?: string } = {},
+): void {
+  const store = storeOf(opts.storageKey ?? STORAGE_KEY);
+  setPending(store, {
+    payer: String(payer),
+    before: overview ? checkoutFingerprint(overview) : null,
+    returnedAt: null,
+  });
+}
+
+export interface CheckoutProcessingOptions {
+  /** The signed-in payer — the user's or the company's id; null while unknown (the
+   *  marker then waits in the URL). */
+  payer: string | number | null;
+  /** The page was reached as the way back: `isCheckoutReturn(location.search)`. */
+  returned: boolean;
+  /** Drop the marker, with replace — `setSearchParams((p) => withoutCheckoutReturn(p),
+   *  { replace: true })`. Called once per return, by the first instance that sees it. */
+  onConsumed: () => void;
+  /** The overview query's data, judged here against the departure. */
+  overview: CheckoutOverview | undefined;
+  /** The overview query's refetch: the hook polls with it — one timer for every
+   *  instance, with the latest mounted one's — and "Check again" calls it. */
+  refetch: () => unknown;
+  /** Once per landing: refresh what a new standing changes — the plans, the items whose
+   *  `locked` may have lifted. The overview itself is already fresh. */
+  onLanded?: () => void;
+  /** How long a return keeps "processing". Default 600 000 (10 minutes). */
+  timeoutMs?: number;
+  /** How often the overview is asked meanwhile. Default 4 000. */
+  pollMs?: number;
+  /** The browser entry. Default `"eifi1-billing-checkout"`. */
+  storageKey?: string;
+}
+
+/**
+ * Whether this payer is back from a checkout whose payment the overview has not shown
+ * yet — and the "Check again" for the banner that says so:
+ *
+ *     const [params, setParams] = useSearchParams();
+ *     const overview = useQuery(billingOverviewQuery);
+ *     const { processing, checkAgain } = useCheckoutProcessing({
+ *       payer: user?.id ?? null,
+ *       returned: isCheckoutReturn(params),
+ *       onConsumed: () => setParams((p) => withoutCheckoutReturn(p), { replace: true }),
+ *       overview: overview.data,
+ *       refetch: overview.refetch,
+ *       onLanded: () => void qc.invalidateQueries({ queryKey: ["budgets"] }),
+ *     });
+ *     processing && <BillingBanner kind="processing" onAction={checkAgain} />
+ *
+ * The kit has no router: the app says whether the URL returned and how to drop the
+ * marker. Mount it wherever the return lands and the banner shows — every instance with
+ * the same `storageKey` shares one state: the first that sees the marker consumes it,
+ * one timer polls, and `onLanded` runs once. The app's `refetchOnWindowFocus` doesn't
+ * matter.
+ */
+export function useCheckoutProcessing(options: CheckoutProcessingOptions): {
+  processing: boolean;
+  checkAgain: () => void;
+} {
+  const {
+    payer,
+    returned,
+    onConsumed,
+    overview,
+    refetch,
+    onLanded,
+    timeoutMs = PROCESSING_FOR,
+    pollMs = POLL_EVERY,
+    storageKey = STORAGE_KEY,
+  } = options;
+  const payerKey = payer === null || payer === undefined ? null : String(payer);
+  const store = storeOf(storageKey);
+  const subscribe = useCallback(
+    (notify: () => void) => {
+      store.listeners.add(notify);
+      return () => {
+        store.listeners.delete(notify);
+      };
+    },
+    [store],
+  );
+  const snapshot = () => store.pending;
+  const pending = useSyncExternalStore(subscribe, snapshot, snapshot);
+  const processing = payerKey !== null && pending?.payer === payerKey && pending.returnedAt !== null;
+
+  // This instance, as the shared timers see it. Registered before paint, so a mark that
+  // ran out while the page was closed is dropped before "processing" can flash.
+  const instanceRef = useRef<Instance>({ payer: payerKey, refetch, onLanded, timeoutMs, pollMs });
+  useLayoutEffect(() => register(store, instanceRef.current), [store]);
+  useLayoutEffect(() => {
+    Object.assign(instanceRef.current, { payer: payerKey, refetch, onLanded, timeoutMs, pollMs });
+    sync(store);
+  });
+
+  // The return: note it, then drop the marker so a reload does not count it twice.
+  const consumed = useEffectEvent(() => onConsumed());
+  useEffect(() => {
+    if (!returned || payerKey === null || !claimReturn(store)) return;
+    const before = store.pending?.payer === payerKey ? store.pending.before : null;
+    setPending(store, { payer: payerKey, before, returnedAt: Date.now() });
+    consumed();
+  }, [returned, payerKey, store]);
+
+  // Caught up: the overview has moved since the departure. Judged against the store as
+  // it is NOW, so a second instance in the same commit finds the mark gone.
+  useEffect(() => {
+    if (!processing || !overview) return;
+    const live = store.pending;
+    if (!live || live.payer !== payerKey || live.returnedAt === null) return;
+    if (!checkoutLanded(live.before, overview)) return;
+    setPending(store, null);
+    const latest = [...store.instances].reverse().find((i) => i.onLanded);
+    latest?.onLanded?.();
+  }, [processing, overview, payerKey, store]);
+
+  const checkAgain = useCallback(() => {
+    try {
+      const result = instanceRef.current.refetch() as PromiseLike<unknown> | undefined;
+      if (result && typeof result.then === "function") result.then(undefined, () => {});
+    } catch {
+      // The banner stays; the next poll asks again.
+    }
+  }, []);
+
+  return { processing, checkAgain };
+}