@djangocfg/payments 2.1.457

package/src/components/PaymentHistory.tsx

@@ -0,0 +1,79 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — PaymentHistory
+// ============================================================================
+// A DataTable of PaymentRecord rows. Uses the ui-tools DataTable (subpath
+// import, per the in-repo rule) and the PaymentStatusBadge. Pure
+// presentational — the host feeds `records` (e.g. from usePaymentHistory()).
+
+import React, { useMemo } from 'react';
+import { DataTable, type DataTableColumn } from '@djangocfg/ui-tools/data-table';
+import { PaymentStatusBadge } from './PaymentStatusBadge';
+import { formatAmount } from '../domain/money';
+import type { PaymentRecord } from '../domain/types';
+
+export interface PaymentHistoryProps {
+  records: PaymentRecord[];
+  loading?: boolean;
+  emptyMessage?: string;
+  onRowClick?: (record: PaymentRecord) => void;
+  locale?: string;
+  className?: string;
+}
+
+export function PaymentHistory({
+  records,
+  loading,
+  emptyMessage = 'No payments yet.',
+  onRowClick,
+  locale,
+  className,
+}: PaymentHistoryProps) {
+  const columns = useMemo<DataTableColumn<PaymentRecord>[]>(
+    () => [
+      {
+        key: 'createdAt',
+        header: 'Date',
+        sortable: true,
+        cell: (p) => new Date(p.createdAt).toLocaleDateString(locale),
+      },
+      {
+        key: 'reference',
+        header: 'For',
+        cell: (p) => `${p.reference.kind} · ${p.reference.id}`,
+      },
+      {
+        key: 'amount',
+        header: 'Amount',
+        sortable: true,
+        cell: (p) => formatAmount(p.amount, p.currency, locale),
+      },
+      {
+        key: 'provider',
+        header: 'Provider',
+        cell: (p) => p.provider,
+      },
+      {
+        key: 'status',
+        header: 'Status',
+        cell: (p) => <PaymentStatusBadge status={p.status} />,
+      },
+    ],
+    [locale],
+  );
+
+  return (
+    <div className={className}>
+      <DataTable
+        data={records}
+        columns={columns}
+        getRowId={(p) => p.id}
+        loading={loading}
+        emptyMessage={emptyMessage}
+        onRowClick={onRowClick}
+        getRowClassName={onRowClick ? () => 'cursor-pointer' : undefined}
+      />
+    </div>
+  );
+}

package/src/components/PaymentStatusBadge.tsx

@@ -0,0 +1,94 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — PaymentStatusBadge
+// ============================================================================
+// Stripe-like status pill: a colored dot + label on a subtle tinted chip.
+// Self-contained (no ui-core Badge) so the dot tone and chip tint stay in sync.
+
+import React from 'react';
+
+import type { PaymentStatus } from '../domain/types';
+
+export interface PaymentStatusBadgeProps {
+  status: PaymentStatus;
+  /** Optional label override (host supplies translated text). */
+  label?: string;
+  className?: string;
+}
+
+interface StatusStyle {
+  /** Tailwind classes for the chip (bg tint + text). */
+  chip: string;
+  /** Tailwind class for the dot. */
+  dot: string;
+  defaultLabel: string;
+}
+
+// ui-core semantic status tokens (success/warning/info/destructive
+// background+foreground pairs) — contrast-tuned per theme, unlike raw
+// palette tints which wash out on light backgrounds. Borderless by design:
+// tint + toned text carry the state (Stripe-dashboard style).
+const STATUS_STYLES: Record<PaymentStatus, StatusStyle> = {
+  idle: {
+    chip: 'bg-muted text-muted-foreground',
+    dot: 'bg-muted-foreground/50',
+    defaultLabel: 'Not started',
+  },
+  creating: {
+    chip: 'bg-muted text-muted-foreground',
+    dot: 'bg-muted-foreground/60',
+    defaultLabel: 'Preparing',
+  },
+  requires_payment: {
+    chip: 'bg-warning-background text-warning-foreground',
+    dot: 'bg-warning',
+    defaultLabel: 'Awaiting payment',
+  },
+  processing: {
+    chip: 'bg-info-background text-info-foreground',
+    dot: 'bg-info animate-pulse',
+    defaultLabel: 'Processing',
+  },
+  requires_action: {
+    chip: 'bg-warning-background text-warning-foreground',
+    dot: 'bg-warning',
+    defaultLabel: 'Action required',
+  },
+  succeeded: {
+    chip: 'bg-success-background text-success-foreground',
+    dot: 'bg-success',
+    defaultLabel: 'Paid',
+  },
+  failed: {
+    // NB: --destructive-foreground is near-white (text on SOLID destructive),
+    // not a chip foreground like the success/warning/info triples — use the
+    // base --destructive tone for text on the pale background.
+    chip: 'bg-destructive-background text-destructive',
+    dot: 'bg-destructive',
+    defaultLabel: 'Failed',
+  },
+  canceled: {
+    chip: 'bg-muted text-muted-foreground',
+    dot: 'bg-muted-foreground/50',
+    defaultLabel: 'Canceled',
+  },
+};
+
+export function PaymentStatusBadge({ status, label, className }: PaymentStatusBadgeProps) {
+  const style = STATUS_STYLES[status];
+  return (
+    <span
+      className={[
+        'inline-flex items-center gap-1.5 rounded-full px-2.5 py-0.5 text-xs font-medium',
+        style.chip,
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      <span className={`h-1.5 w-1.5 rounded-full ${style.dot}`} />
+      {label ?? style.defaultLabel}
+    </span>
+  );
+}

package/src/components/StripePaymentElement.tsx

@@ -0,0 +1,274 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — StripePaymentElement
+// ============================================================================
+// One of TWO files allowed to import @stripe/* (the other is stripe-adapter).
+// Wraps the Stripe <Elements> provider + <PaymentElement>, and exposes the
+// live Elements instance to the host via a render prop so it can be handed to
+// the adapter's confirm() (CheckoutForm's `elementsContext`).
+//
+// Theming: Stripe renders in a cross-origin iframe that app CSS can't touch, so
+// we pass an `appearance` derived from the live ui-core design tokens (via
+// useThemePalette) with `theme: 'night' | 'stripe'`. Without this the form is a
+// WHITE box on our dark dialog. Appearance is MUTABLE — we update it in place on
+// a theme toggle (see the <Elements> note below), we do NOT remount, so a
+// half-typed card isn't wiped.
+//
+// Placement: the host decides where the card field goes. Instead of rendering
+// <PaymentElement/> next to the children, we pass a ready-to-place node INTO
+// the render prop, so the host can drop it under CheckoutForm's "CARD" label as
+// the single `paymentField` (no duplicate mock stub).
+//
+// Load handling: loadStripe() REJECTS (does not resolve null) when Stripe.js
+// can't load from the CDN (network/blocked). We await it explicitly so we can
+// render an honest error + Retry instead of a stuck spinner or a misleading
+// fallback. Only mount <Elements> once Stripe actually resolved.
+
+import React, { useEffect, useMemo, useState } from 'react';
+import { Elements, PaymentElement, useElements } from '@stripe/react-stripe-js';
+import type {
+  Stripe,
+  StripeElementsOptionsClientSecret,
+  StripePaymentElementOptions,
+} from '@stripe/stripe-js';
+import {
+  Alert,
+  AlertDescription,
+  Button,
+  Spinner,
+  useResolvedTheme,
+} from '@djangocfg/ui-core';
+import { useThemePalette } from '@djangocfg/ui-core/styles/palette';
+import { AlertTriangle } from 'lucide-react';
+import { buildStripeAppearance } from './appearance';
+
+/** Live elements context handed to the host for confirm(). */
+export type StripeElementsContext = ReturnType<typeof useElements>;
+
+/**
+ * Card-focused defaults — the calm, single-column checkout (plan7).
+ *
+ * ACCORDION, not tabs. The old 4-tile tab grid (Card · Klarna · Cash App ·
+ * Amazon Pay) was the main source of clutter — four equal-weight tiles for a
+ * choice that is almost always "card". Accordion (Stripe's default since
+ * 2025-03-31) shows the card form open and fillable, with any surviving
+ * alternative methods as quiet collapsed rows below it:
+ *   - `defaultCollapsed: false` → card form open immediately (no extra click).
+ *   - `radios: 'never'` + `spacedAccordionItems: false` → the two cheapest
+ *     height wins; tight rows, no radio column, no inter-item gaps.
+ *
+ * Which methods appear is driven by the intent (server-side / Dashboard), NOT
+ * hand-pinned here: for a subscription Stripe auto-hides non-recurring methods,
+ * so we don't need `paymentMethodOrder` to filter — dropping it also keeps
+ * Link's inline prompt visible. Klarna is disabled in the Dashboard (heaviest
+ * row, least subscription value); Cash App / Amazon Pay survive collapsed.
+ *
+ * Link is LEFT ON: it renders inline *inside* the card form (not a tall express
+ * block), so it lifts conversion without bloating the dialog. Pass `email`
+ * (and `phone` where available) below so returning Link users go straight to a
+ * short OTP. We still suppress the tall Apple/Google Pay express blocks.
+ * Prereq: Link enabled in Dashboard + domain registered — until then Link
+ * simply doesn't render, so this is safe to ship ahead of it.
+ */
+export const DEFAULT_PAYMENT_ELEMENT_OPTIONS: StripePaymentElementOptions = {
+  layout: {
+    type: 'accordion',
+    defaultCollapsed: false,
+    radios: 'never',
+    spacedAccordionItems: false,
+  },
+  wallets: { applePay: 'never', googlePay: 'never' },
+  fields: { billingDetails: { address: 'never' } },
+};
+
+export interface StripePaymentElementProps {
+  /** loadStripe(publishableKey), memoized once at host module scope. */
+  stripe: Promise<Stripe | null>;
+  /** Client secret created on the backend for this PaymentIntent. */
+  clientSecret: string;
+  /**
+   * Render prop receiving the live Stripe Elements context AND a ready-to-place
+   * <PaymentElement/> node. Pass `field` where you want the card input to
+   * appear (e.g. CheckoutForm's `paymentField`) and `elements` to
+   * <CheckoutForm elementsContext={elements}>.
+   */
+  children: (args: {
+    elements: StripeElementsContext;
+    field: React.ReactNode;
+  }) => React.ReactNode;
+  /** Optional Elements appearance/options overrides (merged after appearance). */
+  options?: Omit<StripeElementsOptionsClientSecret, 'clientSecret' | 'appearance'>;
+  /** Override the compact PaymentElement options (layout, wallets, fields…). */
+  paymentElementOptions?: StripePaymentElementOptions;
+  /**
+   * Logged-in user's email. Passed to the PaymentElement as
+   * `defaultValues.billingDetails.email` so Stripe Link can autofill / one-click
+   * for returning users. Stripe recommends supplying it when available.
+   */
+  email?: string;
+  /**
+   * Logged-in user's phone (E.164). Prefilling it alongside email pre-targets
+   * Link's SMS OTP so a returning user lands on the code with fewer fields —
+   * shrinks Link's inline block. Optional; omit if unknown.
+   */
+  phone?: string;
+  /**
+   * Called when Stripe.js fails to load. The host can disable its own Pay
+   * affordance, log, etc. Receives the error message.
+   */
+  onLoadError?: (message: string) => void;
+}
+
+type LoadState =
+  | { phase: 'loading' }
+  | { phase: 'ready'; stripe: Stripe }
+  | { phase: 'error'; message: string };
+
+/** Inner component: must live under <Elements> to call useElements(). */
+function ElementsBridge({
+  children,
+  paymentElementOptions,
+  email,
+  phone,
+}: {
+  children: StripePaymentElementProps['children'];
+  paymentElementOptions: StripePaymentElementOptions;
+  email?: string;
+  phone?: string;
+}) {
+  const elements = useElements();
+  // Prefill email + phone so Stripe Link recognizes the returning user and
+  // targets the SMS OTP immediately (shorter Link block). Merge (don't clobber)
+  // any caller-provided defaultValues.
+  const options = useMemo<StripePaymentElementOptions>(() => {
+    if (!email && !phone) return paymentElementOptions;
+    return {
+      ...paymentElementOptions,
+      defaultValues: {
+        ...paymentElementOptions.defaultValues,
+        billingDetails: {
+          ...paymentElementOptions.defaultValues?.billingDetails,
+          ...(email ? { email } : {}),
+          ...(phone ? { phone } : {}),
+        },
+      },
+    };
+  }, [paymentElementOptions, email, phone]);
+  const field = <PaymentElement options={options} />;
+  return <>{children({ elements, field })}</>;
+}
+
+export function StripePaymentElement({
+  stripe,
+  clientSecret,
+  children,
+  options,
+  paymentElementOptions = DEFAULT_PAYMENT_ELEMENT_OPTIONS,
+  email,
+  phone,
+  onLoadError,
+}: StripePaymentElementProps) {
+  const [state, setState] = useState<LoadState>({ phase: 'loading' });
+  // Bump to retry loading.
+  const [attempt, setAttempt] = useState(0);
+
+  // Drive the Stripe appearance from the live design tokens. useThemePalette
+  // returns hex (safe for Stripe's core color vars); useResolvedTheme picks the
+  // base 'night'/'stripe' theme and is the remount key.
+  const theme = useResolvedTheme();
+  const palette = useThemePalette();
+  const appearance = useMemo(
+    () =>
+      buildStripeAppearance(theme, {
+        primary: palette.primary,
+        input: palette.input,
+        foreground: palette.foreground,
+        mutedForeground: palette.mutedForeground,
+        border: palette.border,
+        ring: palette.ring,
+        destructive: palette.destructive,
+      }),
+    [theme, palette],
+  );
+
+  useEffect(() => {
+    let active = true;
+    setState({ phase: 'loading' });
+    stripe
+      .then((s) => {
+        if (!active) return;
+        if (s) {
+          setState({ phase: 'ready', stripe: s });
+        } else {
+          const msg = 'Stripe is not configured.';
+          setState({ phase: 'error', message: msg });
+          onLoadError?.(msg);
+        }
+      })
+      .catch((e: unknown) => {
+        if (!active) return;
+        const msg =
+          e instanceof Error ? e.message : 'Failed to load the payment form.';
+        setState({ phase: 'error', message: msg });
+        onLoadError?.(msg);
+      });
+    return () => {
+      active = false;
+    };
+    // `attempt` re-runs the load; `stripe` is a stable host-memoized promise.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [stripe, attempt]);
+
+  if (state.phase === 'loading') {
+    return (
+      <div className="flex flex-col items-center gap-2 py-8">
+        <Spinner className="h-5 w-5" />
+        <p className="text-muted-foreground text-sm">Loading secure payment form…</p>
+      </div>
+    );
+  }
+
+  if (state.phase === 'error') {
+    return (
+      <div className="space-y-3 py-2">
+        <Alert variant="destructive">
+          <AlertTriangle className="h-4 w-4" />
+          <AlertDescription>
+            {state.message} Check your connection and try again.
+          </AlertDescription>
+        </Alert>
+        <Button
+          type="button"
+          variant="outline"
+          className="w-full"
+          onClick={() => setAttempt((n) => n + 1)}
+        >
+          Retry
+        </Button>
+      </div>
+    );
+  }
+
+  const elementsOptions: StripeElementsOptionsClientSecret = {
+    ...options,
+    clientSecret,
+    appearance,
+  };
+  return (
+    // NO `key={theme}` remount: @stripe/react-stripe-js diffs the `options` prop
+    // and calls `elements.update({ appearance })` live for mutable keys
+    // (appearance is mutable; only clientSecret/fonts are immutable). Remounting
+    // on a theme flip would tear down the iframe and WIPE any half-typed card
+    // details — updating in place re-themes without losing input.
+    <Elements stripe={state.stripe} options={elementsOptions}>
+      <ElementsBridge
+        paymentElementOptions={paymentElementOptions}
+        email={email}
+        phone={phone}
+      >
+        {children}
+      </ElementsBridge>
+    </Elements>
+  );
+}

package/src/components/appearance.ts

@@ -0,0 +1,131 @@
+// ============================================================================
+// @djangocfg/payments — Stripe Appearance builder (design-token driven)
+// ============================================================================
+// Maps the live ui-core design tokens (macos preset) onto Stripe's Appearance
+// API so the Payment Element (rendered in a cross-origin iframe, un-styleable
+// from the app) matches the surrounding dialog in BOTH light and dark themes.
+//
+// Why this file exists: without an `appearance`, Stripe uses its default light
+// `theme: 'stripe'` and renders a WHITE form on our dark dialog. Only the
+// Appearance API can touch the iframe, so we translate our tokens into it.
+//
+// Stripe constraint: the core color variables (colorPrimary/colorBackground/
+// colorText/colorDanger/colorSuccess/colorWarning) must be CONCRETE colors —
+// `var(...)` and `rgba(...)` are rejected there. ui-core's palette hooks return
+// hex, so we read from that (passed in as `tokens`) rather than forwarding raw
+// `hsl(var(--x))` token strings.
+
+import type { Appearance } from '@stripe/stripe-js';
+
+/** Concrete hex/color values read from the live theme (ui-core palette). */
+export interface AppearanceTokens {
+  /** Brand CTA / accent — `--primary`. */
+  primary: string;
+  /** Input fill — `--input` (falls back to `--background`). */
+  input: string;
+  /** Body text — `--foreground`. */
+  foreground: string;
+  /** Secondary text / placeholders — `--muted-foreground`. */
+  mutedForeground: string;
+  /** Control outline — `--border`. */
+  border: string;
+  /** Focus ring (blue, ui-core pattern) — `--ring`. */
+  ring: string;
+  /** Error color — `--destructive`. */
+  destructive: string;
+  /** Resolved font stack — `--font-sans`. */
+  fontFamily?: string;
+  /** Control radius, e.g. `0.625rem` — `--radius-control`. */
+  borderRadius?: string;
+}
+
+/** Sensible dark defaults if the theme can't be read (SSR / probe failure). */
+const DARK_FALLBACK: AppearanceTokens = {
+  primary: '#0a84ff',
+  input: '#1c1c1e',
+  foreground: '#f5f5f7',
+  mutedForeground: '#98989d',
+  border: '#38383a',
+  ring: '#0a84ff',
+  destructive: '#ff453a',
+};
+
+/** Sensible light defaults if the theme can't be read. */
+const LIGHT_FALLBACK: AppearanceTokens = {
+  primary: '#0071e3',
+  input: '#ffffff',
+  foreground: '#1d1d1f',
+  mutedForeground: '#6e6e73',
+  border: '#d2d2d7',
+  ring: '#0071e3',
+  destructive: '#ff3b30',
+};
+
+/**
+ * Build a Stripe {@link Appearance} from resolved design tokens.
+ *
+ * @param theme  'light' | 'dark' — picks the base Stripe theme + fallback set.
+ * @param tokens Concrete color/typography values from the live theme. When
+ *               omitted (SSR), a matching light/dark fallback is used so the
+ *               form is never white-on-dark.
+ */
+export function buildStripeAppearance(
+  theme: 'light' | 'dark',
+  tokens?: Partial<AppearanceTokens>,
+): Appearance {
+  const base = theme === 'dark' ? DARK_FALLBACK : LIGHT_FALLBACK;
+  const t: AppearanceTokens = { ...base, ...tokens };
+
+  const fontFamily =
+    t.fontFamily ||
+    '-apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif';
+  const borderRadius = t.borderRadius || '0.625rem';
+
+  return {
+    theme: theme === 'dark' ? 'night' : 'stripe',
+    labels: 'above',
+    variables: {
+      colorPrimary: t.primary,
+      colorBackground: t.input,
+      colorText: t.foreground,
+      colorTextSecondary: t.mutedForeground,
+      colorTextPlaceholder: t.mutedForeground,
+      colorDanger: t.destructive,
+      colorIcon: t.mutedForeground,
+      fontFamily,
+      fontSizeBase: '16px', // ≥16px avoids mobile input auto-zoom
+      spacingUnit: '4px',
+      borderRadius,
+    },
+    rules: {
+      '.Input': {
+        border: `1px solid ${t.border}`,
+        boxShadow: 'none',
+      },
+      // Apple-minimal focus: a clean 1px ring, no fat blue glow.
+      '.Input:focus': {
+        border: `1px solid ${t.ring}`,
+        boxShadow: `0 0 0 1px ${t.ring}`,
+        outline: 'none',
+      },
+      '.Input--invalid': {
+        border: `1px solid ${t.destructive}`,
+        boxShadow: `0 0 0 1px ${t.destructive}`,
+      },
+      '.Tab': {
+        border: `1px solid ${t.border}`,
+        boxShadow: 'none',
+      },
+      '.Tab:hover': {
+        border: `1px solid ${t.border}`,
+      },
+      '.Tab--selected': {
+        border: `1px solid ${t.primary}`,
+        boxShadow: `0 0 0 1px ${t.primary}`,
+      },
+      '.Label': {
+        color: t.mutedForeground,
+      },
+    },
+  };
+}

package/src/components/index.ts

@@ -0,0 +1,21 @@
+// ============================================================================
+// @djangocfg/payments — components barrel
+// ============================================================================
+
+export { CheckoutDialog } from './CheckoutDialog';
+export type { CheckoutDialogProps } from './CheckoutDialog';
+
+export { CheckoutForm } from './CheckoutForm';
+export type { CheckoutFormProps } from './CheckoutForm';
+
+export { StripePaymentElement, DEFAULT_PAYMENT_ELEMENT_OPTIONS } from './StripePaymentElement';
+export type { StripePaymentElementProps, StripeElementsContext } from './StripePaymentElement';
+
+export { buildStripeAppearance } from './appearance';
+export type { AppearanceTokens } from './appearance';
+
+export { PaymentHistory } from './PaymentHistory';
+export type { PaymentHistoryProps } from './PaymentHistory';
+
+export { PaymentStatusBadge } from './PaymentStatusBadge';
+export type { PaymentStatusBadgeProps } from './PaymentStatusBadge';

package/src/context/CheckoutGuard.tsx

@@ -0,0 +1,94 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — CheckoutGuard (the dialog's own checkout context)
+// ============================================================================
+// A tiny context shared by a checkout dialog and its inner form so BOTH read
+// ONE source of truth for "is a payment in flight". The inner form (which owns
+// the useCheckout machine) publishes its status up; the outer <Dialog> reads
+// `canClose` to gate Esc / overlay-click / the × button, and any component in
+// the tree can read the same status.
+//
+// Why a context and not props: the dialog shell and the form are on opposite
+// sides of the Stripe <Elements> boundary — threading a setter through
+// StripePaymentElement's render prop would be brittle. The provider wraps the
+// whole dialog; the form pushes status via `usePublishCheckoutStatus`, the shell
+// consumes via `useCheckoutGuard`. Matches @rules_2.0 03-DIALOGS (registry owns
+// open/close; this owns the in-flight lock, orthogonally).
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import type { PaymentStatus } from '../domain/types';
+
+/**
+ * Statuses during which the dialog MUST NOT close — a charge is mid-flight or
+ * awaiting 3DS, and tearing down <Elements> now would orphan the intent.
+ */
+export function isCheckoutLocked(status: PaymentStatus): boolean {
+  return status === 'processing' || status === 'requires_action';
+}
+
+interface CheckoutGuardValue {
+  readonly status: PaymentStatus;
+  /** False while a payment is in flight / awaiting action. */
+  readonly canClose: boolean;
+  readonly setStatus: (status: PaymentStatus) => void;
+}
+
+const CheckoutGuardContext = createContext<CheckoutGuardValue | null>(null);
+
+export function CheckoutGuardProvider({ children }: { children: ReactNode }) {
+  const [status, setStatus] = useState<PaymentStatus>('idle');
+  const value = useMemo<CheckoutGuardValue>(
+    () => ({ status, canClose: !isCheckoutLocked(status), setStatus }),
+    [status],
+  );
+  return (
+    <CheckoutGuardContext.Provider value={value}>
+      {children}
+    </CheckoutGuardContext.Provider>
+  );
+}
+
+/**
+ * Read the guard from the dialog shell. Returns `canClose` (false while locked)
+ * plus the live status. Safe outside a provider — defaults to "can close".
+ */
+export function useCheckoutGuard(): Pick<CheckoutGuardValue, 'status' | 'canClose'> {
+  const ctx = useContext(CheckoutGuardContext);
+  if (!ctx) return { status: 'idle', canClose: true };
+  return { status: ctx.status, canClose: ctx.canClose };
+}
+
+/**
+ * Inner-form hook: pushes the live checkout status into the guard so the shell
+ * can gate close. No-op when rendered outside a provider (e.g. a standalone
+ * form). Also installs a `beforeunload` guard while locked so a full-page
+ * refresh mid-confirm prompts the user.
+ */
+export function usePublishCheckoutStatus(status: PaymentStatus): void {
+  const ctx = useContext(CheckoutGuardContext);
+  const setStatus = ctx?.setStatus;
+
+  useEffect(() => {
+    setStatus?.(status);
+  }, [setStatus, status]);
+
+  const locked = isCheckoutLocked(status);
+  useEffect(() => {
+    if (!locked) return;
+    const onBeforeUnload = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+      // Legacy Chrome requires a returnValue to trigger the prompt.
+      e.returnValue = '';
+    };
+    window.addEventListener('beforeunload', onBeforeUnload);
+    return () => window.removeEventListener('beforeunload', onBeforeUnload);
+  }, [locked]);
+}