@djangocfg/payments 2.1.561 → 2.1.562

package/README.md

@@ -2,19 +2,22 @@
 
 Provider-agnostic React payments module. **Stripe-first**, but the package
 never depends on a concrete SDK — the host injects an adapter. Battle-tested
-in production (one-time PaymentIntent checkout + recurring subscriptions with
-Stripe Link) before extraction into `@djangocfg/*`.
+in production (one-time PaymentIntent checkout, recurring subscriptions with
+Stripe Link, card on file) before extraction into `@djangocfg/*`.
+
+📖 **[Full documentation →](./@docs/README.md)** — architecture, the server
+contract, Stripe traps, testing.
 
 ## The seam
 
 The host picks **one** adapter and injects it via `<PaymentProvider>`. Package
-hooks/components read it through `usePaymentAdapter()` and never import Stripe or
-a generated API client directly.
+hooks/components read it through `usePaymentAdapter()` and never import Stripe
+or a generated API client directly.
 
 ```tsx
 import { PaymentProvider, createMockPaymentAdapter } from '@djangocfg/payments';
 
-// Mock-first: build & verify the whole checkout UX before any backend exists.
+// Mock-first: build & verify the whole UX before any backend exists.
 <PaymentProvider adapter={createMockPaymentAdapter()}>
   {children}
 </PaymentProvider>
@@ -38,18 +41,21 @@ const adapter = createStripeAdapter({
 ## Layering
 
 ```
-domain/      pure types + money helpers   (no React, no Stripe)
-context/     <PaymentProvider> + usePaymentAdapter()  (the injected seam)
-transport/   mock-adapter | stripe-adapter  (only stripe-adapter touches @stripe/*)
-hooks/       useCheckout, usePaymentHistory  (state machine over the adapter)
-components/  CheckoutForm, StripePaymentElement, PaymentHistory, PaymentStatusBadge
+domain/      pure types + money/card helpers   (no React, no Stripe)
+context/     <PaymentProvider> + <CheckoutGuard>   (the seam, the in-flight lock)
+transport/   mock-adapter | stripe-adapter      (the SDK seam; see the note below)
+hooks/       useCheckout, useCardSetup, usePaymentHistory, useSavedCards
+components/  CheckoutForm, CardSetupForm, StripePaymentElement, dialogs, tables, badges
 ```
 
-`@stripe/*` is touched in **exactly two files** (`transport/stripe-adapter.ts`,
-`components/StripePaymentElement.tsx`) and ships as a regular dependency —
+`@stripe/*` is a **runtime** dependency of exactly two files
+(`transport/stripe-adapter.ts`, `components/StripePaymentElement.tsx`) and a
+**type-only** one of a third (`components/appearance.ts`) — enforced by
+`scripts/check-stripe-imports.mjs`, which `pnpm check` runs.
 `@stripe/stripe-js` is only the tiny CDN loader (the real SDK loads from
-js.stripe.com at runtime), and tree-shaking drops the Stripe components from
-mock-only bundles.
+js.stripe.com at runtime), so tree-shaking drops the Stripe components from
+mock-only bundles. See [`@docs/ARCHITECTURE.md`](./@docs/ARCHITECTURE.md) for
+why this is one package and where the boundaries are.
 
 ## Styles (Tailwind v4) — required wiring
 
@@ -73,16 +79,22 @@ Next.js hosts also add the package to `transpilePackages`.
 | Export | Kind | Purpose |
 |---|---|---|
 | `PaymentProvider` / `usePaymentAdapter` | context | inject / read the adapter |
-| `createMockPaymentAdapter` | adapter | full fake state machine (success / declined / 3DS) |
-| `createStripeAdapter` | adapter | real Stripe (host supplies key + create-intent call) |
+| `createMockPaymentAdapter` | adapter | full fake state machine (success / declined / 3DS / cards) |
+| `createStripeAdapter` | adapter | real Stripe (host supplies key + backend calls) |
 | `useCheckout` | hook | `idle → creating → requires_payment → processing → succeeded\|failed\|requires_action` |
+| `useCardSetup` | hook | the same machine for saving a card with no charge |
+| `useSavedCards` | hook | cards on file as a phase (`unavailable\|loading\|ready\|error`) + set-default / remove |
 | `usePaymentHistory` | hook | paginated history via `adapter.listPayments` |
-| `CheckoutDialog` | component | close-locked dialog shell (CheckoutGuard + ui-core Dialog); wrap your checkout body in it |
-| `CheckoutForm` | component | provider-agnostic form shell (ui-core only); inject the provider field via `paymentField` |
-| `StripePaymentElement` | component | `<Elements>` + `<PaymentElement>`; render-props the live Elements to the host |
-| `PaymentHistory` | component | sortable table of `PaymentRecord` (ui-core `Table`) |
-| `PaymentStatusBadge` | component | status pill on ui-core semantic tokens (success/warning/info/destructive) |
-| `toMinorUnits` / `toMajorUnits` / `formatAmount` | util | money at the boundary (amounts cross as integer minor units) |
+| `CheckoutDialog` | component | close-locked dialog shell; wrap your checkout body in it |
+| `CheckoutForm` | component | provider-agnostic form shell; inject the field via `paymentField` |
+| `CardSetupForm` | component | the same, for saving a card (no amount, no "Paid") |
+| `UpdateCardDialog` | component | the whole add-a-card flow: intent on open, confirm, report |
+| `SavedCardList` | component | cards table: default badge, expiry warning, row actions |
+| `StripePaymentElement` | component | `<Elements>` + `<PaymentElement>`; render-props the live Elements |
+| `PaymentHistory` | component | sortable table of `PaymentRecord` |
+| `PaymentStatusBadge` | component | status pill on ui-core semantic tokens |
+| `toMinorUnits` / `toMajorUnits` / `formatAmount` | util | money at the boundary (integer minor units) |
+| `cardExpiresAt` / `isCardExpired` / `isCardExpiringSoon` / `formatCardExpiry` / `sortCards` / `cardsOf` | util | card derivations against a clock |
 
 ## Conventions
 
@@ -91,78 +103,78 @@ Next.js hosts also add the package to `transpilePackages`.
   widget (`widgets/CLAUDE.md`).
 - Does **not** mount its own `<UiProviders>` — the host provides it once.
 - Locale-free: user-facing labels are props/slots (host supplies i18n).
-- Verify with `pnpm -F @djangocfg/payments check` (tsc).
+- Verify with `pnpm -F @djangocfg/payments check` and `… lint`.
+
+## Card on file
+
+A subscription outlives the card that pays for it: when a renewal fails Stripe
+retries for ~2 weeks **against the same stored card**, then gives up. Without
+a way to replace it, a customer who wanted to pay loses the subscription.
+
+```tsx
+const { phase, canAddCard, canManageCards, refresh, setDefault, remove, isBusy } =
+  useSavedCards();
+
+<SavedCardList
+  phase={phase}
+  busy={isBusy}
+  onAddCard={canAddCard ? () => setOpen(true) : undefined}
+  onSetDefault={canManageCards ? setDefault : undefined}
+  onRemove={canManageCards ? remove : undefined}
+/>
+<UpdateCardDialog open={open} onClose={close} onSaved={() => { close(); void refresh(); }} />
+```
+
+Four host endpoints, wired all-or-none, plus four server rules that fail
+silently — see [`@docs/CARD_ON_FILE.md`](./@docs/CARD_ON_FILE.md) and
+[`@docs/SERVER_CONTRACT.md`](./@docs/SERVER_CONTRACT.md).
 
----
+> **Not Link, not the Billing Portal.** Link is a buyer-side wallet —
+> `link.com` does not know your subscription exists, and a renewal charges the
+> stored `pm_…`. The Billing Portal is a server-side redirect that discards
+> this package's theming and the host's locale. Reasoning in
+> [`@docs/STRIPE_NOTES.md`](./@docs/STRIPE_NOTES.md).
 
 ## Configuration & keys
 
-Payments need **three Stripe keys**, split by where they're safe to live. Stripe
-ships them in two flavours — **test** (`sk_test_…`, `pk_test_…`) and **live**
-(`sk_live_…`, `pk_live_…`) — with the **same variable names**; only the values
-differ. Bring up **test first**, verify end-to-end, then switch to live.
+Three Stripe keys, split by where they're safe to live. Stripe ships **test**
+(`sk_test_…`, `pk_test_…`) and **live** (`sk_live_…`, `pk_live_…`) flavours
+with the **same variable names**; only the values differ. Bring up test first.
 
 | Key | Prefix | Lives in | Exposed to browser? |
 |---|---|---|---|
 | Secret key | `sk_test_…` / `sk_live_…` | **Backend only** (`STRIPE__SECRET_KEY`) | ❌ never |
 | Webhook signing secret | `whsec_…` | **Backend only** (`STRIPE__WEBHOOK_SECRET`) | ❌ never |
-| Publishable key | `pk_test_…` / `pk_live_…` | Backend + Frontend | ✅ safe (it's public by design) |
-
-> The publishable key is typically returned to the browser by the backend's
-> create-checkout response (`publishable_key`) and/or read from
-> `NEXT_PUBLIC_STRIPE_PK`. The secret and webhook keys **never** leave the server.
-
-### Backend (Django) — `STRIPE__*`
-
-This package is frontend-only; it pairs with any Django backend that creates
-PaymentIntents (a built-in `django_cfg.apps.payments` module is planned — see
-`@dev/active/payments-v1`). Paths below are the reference host's; adjust env
-names to your backend. Set the keys server-side (git-ignored secrets file):
+| Publishable key | `pk_test_…` / `pk_live_…` | Backend + Frontend | ✅ safe (public by design) |
 
 ```dotenv
-# --- Stripe (test) ---
+# backend, git-ignored secrets file
 STRIPE__SECRET_KEY=sk_test_xxx
 STRIPE__PUBLISHABLE_KEY=pk_test_xxx
 STRIPE__WEBHOOK_SECRET=whsec_xxx          # comma-separate to rotate: whsec_new,whsec_old
 
-# --- Stripe (live) — same names, live values ---
-# STRIPE__SECRET_KEY=sk_live_xxx
-# STRIPE__PUBLISHABLE_KEY=pk_live_xxx
-# STRIPE__WEBHOOK_SECRET=whsec_live_xxx
-```
-
-### Frontend — `NEXT_PUBLIC_STRIPE_PK`
-
-```dotenv
-# your Next.js app .env  (test → pk_test_…, live → pk_live_…)
+# your Next.js app .env
 NEXT_PUBLIC_STRIPE_PK=pk_test_xxx
 ```
 
 With **no** `NEXT_PUBLIC_STRIPE_PK` set, the host falls back to the **mock
-adapter** — the whole checkout UX still renders (no real charge), which is the
-mock-first dev path.
+adapter** — the whole UX still renders (no real charge).
 
-> ⚠️ **Security:** the secret (`sk_`) and webhook (`whsec_`) keys must live in a
-> **git-ignored** file or a secret manager — never commit them. If the project's
-> `.env*` files are tracked by git, add the secrets file to `.gitignore` and
-> `git rm --cached` it first. Only `pk_…` (publishable) is safe in tracked config.
+> ⚠️ The secret (`sk_`) and webhook (`whsec_`) keys must live in a git-ignored
+> file or a secret manager. Only `pk_…` is safe in tracked config.
 
 ## Stripe setup (test mode)
 
-1. **Get test keys** — Stripe Dashboard → Developers → API keys (toggle "test
-   mode"): copy `pk_test_…` and `sk_test_…`.
-2. **Webhook** — for local dev, use the Stripe CLI (it prints a `whsec_…` signing
-   secret for the forwarded endpoint):
+1. **Test keys** — Dashboard → Developers → API keys (toggle "test mode").
+2. **Webhook** — locally, the Stripe CLI prints a `whsec_…` for the forwarded
+   endpoint:
    ```bash
-   stripe login
    stripe listen --forward-to localhost:8000/<your-webhook-path>/
-   # → copy the "whsec_…" it prints into STRIPE__WEBHOOK_SECRET
    ```
-   For a deployed env, create the endpoint in Dashboard → Developers → Webhooks
-   pointing at your backend's webhook URL and subscribe to:
-   `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`.
-3. **Test a payment** — open an order, hit **Pay**, use a Stripe **test card**
-   (`4242 4242 4242 4242`, any future expiry/CVC). Trigger events directly with:
+   Deployed: create the endpoint in the Dashboard and subscribe to
+   `payment_intent.succeeded`, `payment_intent.payment_failed`,
+   `charge.refunded` (plus the invoice/subscription events your dunning needs).
+3. **Test a payment** — card `4242 4242 4242 4242`, any future expiry/CVC.
    ```bash
    stripe trigger payment_intent.succeeded
    stripe events resend <evt_id>   # test idempotency / replay
@@ -170,9 +182,7 @@ mock-first dev path.
 
 ## Going live
 
-1. Switch all three `STRIPE__*` values to their `…_live_…` counterparts and
-   `NEXT_PUBLIC_STRIPE_PK` to `pk_live_…`.
-2. Create a **live** webhook endpoint in the Dashboard (live mode has its own
-   signing secret — set it in `STRIPE__WEBHOOK_SECRET`).
+1. Switch all three `STRIPE__*` values and `NEXT_PUBLIC_STRIPE_PK` to live.
+2. Create a **live** webhook endpoint (live mode has its own signing secret).
 3. Register your domain for Apple Pay / Google Pay if you enable wallets.
 4. Do a small real charge to confirm end-to-end.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/payments",
-  "version": "2.1.561",
+  "version": "2.1.562",
   "description": "Provider-agnostic React payments module (Stripe-first): checkout state machine, Payment Element wrapper, close-guard context, mock adapter for keyless development",
   "keywords": [
     "payments",
@@ -42,11 +42,12 @@
     "dist",
     "src",
     "!src/**/*.stories.tsx",
+    "@docs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && node scripts/check-stripe-imports.mjs",
     "lint": "eslint . --max-warnings 0"
   },
   "dependencies": {
@@ -54,15 +55,15 @@
     "@stripe/stripe-js": "^9.9.0"
   },
   "peerDependencies": {
-    "@djangocfg/ui-core": "^2.1.561",
+    "@djangocfg/ui-core": "^2.1.562",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/eslint-config": "^2.1.561",
-    "@djangocfg/typescript-config": "^2.1.561",
-    "@djangocfg/ui-core": "^2.1.561",
+    "@djangocfg/eslint-config": "^2.1.562",
+    "@djangocfg/typescript-config": "^2.1.562",
+    "@djangocfg/ui-core": "^2.1.562",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/components/CardSetupForm.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — CardSetupForm (save a card, charge nothing)
+// ============================================================================
+// ui-core only — no Stripe import; the provider's field arrives via the
+// `paymentField` slot, exactly as CheckoutForm takes it.
+//
+// NOT CheckoutForm with amount=0. That form is built around a sum: its CTA
+// reads `Pay {amount}`, its summary states what is being bought, its success
+// state says "Paid". A card being saved has no amount, buys nothing, and ends
+// at "Card saved" — passing a meaningless zero through all three would produce
+// a form that lies in three places.
+//
+// CONSENT IS NOT DECORATION. Stripe's `mandate_data.customer_acceptance` is
+// sent as `infer_from_client`, which derives the mandate from the text ON
+// SCREEN. `consentText` is that text. Off-session charging requires it, so the
+// component renders a default rather than allowing an empty one.
+
+import React, { useCallback, useRef } from 'react';
+import { Alert, AlertDescription, Button, Spinner } from '@djangocfg/ui-core';
+import { AlertTriangle, Lock, ShieldCheck } from 'lucide-react';
+import { isCheckoutLocked, usePublishCheckoutStatus } from '../context/CheckoutGuard';
+import type { UseCardSetupResult } from '../hooks/useCardSetup';
+
+export interface CardSetupFormProps {
+  /** The setup machine, created by the parent so it also owns the clientSecret. */
+  setup: UseCardSetupResult;
+  /** Slot for the provider's card field (Stripe PaymentElement / mock input). */
+  paymentField?: React.ReactNode;
+  /** Renders a `4242…` stub when no `paymentField` is supplied. Mock path only. */
+  isMock?: boolean;
+  /** Confirm payload passed to the adapter (a Stripe Elements instance). */
+  elementsContext?: unknown;
+  /** Where the provider returns after a 3DS redirect. */
+  returnUrl?: string;
+  onSuccess?: (setupIntentId: string) => void;
+  onFailure?: (error: string) => void;
+  onCancel?: () => void;
+  submitLabel?: string;
+  cancelLabel?: string;
+  /** The mandate text. Shown to the customer AND inferred by Stripe. */
+  consentText?: string;
+  className?: string;
+}
+
+const DEFAULT_CONSENT =
+  'By saving this card you authorise us to charge it for your subscription renewals, including when you are not present.';
+
+export function CardSetupForm({
+  setup,
+  paymentField,
+  isMock = false,
+  elementsContext,
+  returnUrl,
+  onSuccess,
+  onFailure,
+  onCancel,
+  submitLabel = 'Save card',
+  cancelLabel = 'Cancel',
+  consentText = DEFAULT_CONSENT,
+  className,
+}: CardSetupFormProps) {
+  const { status, error, isBusy, confirm, intent } = setup;
+
+  // Same guard CheckoutForm publishes into: a SetupIntent mid-confirm is a
+  // real authorisation with the issuer, so the dialog must not close over it.
+  usePublishCheckoutStatus(status);
+  const locked = isCheckoutLocked(status);
+
+  const isDone = status === 'succeeded';
+  const needsAction = status === 'requires_action';
+
+  // A ref, not the disabled prop: between `start` and `confirm` the status sits
+  // at `requires_payment` with `isBusy` false, so a second Enter would confirm
+  // the same SetupIntent twice. A ref flips with no render in between.
+  const submittingRef = useRef(false);
+
+  const handleSubmit = useCallback(
+    async (e: React.FormEvent) => {
+      e.preventDefault();
+      if (submittingRef.current) return;
+      submittingRef.current = true;
+      try {
+        await confirm(elementsContext, returnUrl);
+      } finally {
+        submittingRef.current = false;
+      }
+    },
+    [confirm, elementsContext, returnUrl],
+  );
+
+  React.useEffect(() => {
+    if (status === 'succeeded' && intent) onSuccess?.(intent.id);
+    if (status === 'failed' && error) onFailure?.(error);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [status]);
+
+  return (
+    <form onSubmit={handleSubmit} className={className}>
+      <div className="space-y-5">
+        <div>
+          {paymentField ? (
+            <div className="min-h-[40px]">{paymentField}</div>
+          ) : isMock ? (
+            <div className="border-border bg-muted/30 text-muted-foreground flex h-10 items-center rounded-md border px-3 text-sm">
+              4242 4242 4242 4242
+            </div>
+          ) : null}
+        </div>
+
+        <p className="text-muted-foreground text-xs leading-relaxed">{consentText}</p>
+
+        {error ? (
+          <Alert variant="destructive">
+            <AlertDescription>{error}</AlertDescription>
+          </Alert>
+        ) : null}
+
+        {needsAction ? (
+          <Alert>
+            <AlertTriangle className="h-4 w-4" />
+            <AlertDescription>
+              Your bank needs to confirm this card before it can be saved.
+            </AlertDescription>
+          </Alert>
+        ) : null}
+
+        <Button type="submit" size="lg" className="w-full" disabled={isBusy || isDone}>
+          {isBusy ? (
+            <>
+              <Spinner className="mr-1.5 h-4 w-4" />
+              Saving…
+            </>
+          ) : isDone ? (
+            <>
+              <ShieldCheck className="mr-1.5 h-4 w-4" />
+              Card saved
+            </>
+          ) : (
+            submitLabel
+          )}
+        </Button>
+
+        {onCancel && !locked ? (
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="text-muted-foreground w-full"
+            onClick={onCancel}
+            disabled={isBusy}
+          >
+            {cancelLabel}
+          </Button>
+        ) : null}
+
+        <p className="text-muted-foreground flex items-center justify-center gap-1.5 text-xs">
+          <Lock className="h-3 w-3" />
+          Secure · Powered by Stripe
+        </p>
+      </div>
+    </form>
+  );
+}

package/src/components/SavedCardList.tsx

@@ -0,0 +1,225 @@
+'use client';
+
+// ============================================================================
+// @djangocfg/payments — SavedCardList
+// ============================================================================
+// The cards-on-file table. Pure presentational: the host feeds `phase` (from
+// useSavedCards) and the action callbacks. ui-core Table, like PaymentHistory
+// — no data-grid, since a package may not depend on a widget.
+//
+// FOUR STATES, NOT TWO. `unavailable` (the adapter has no card methods),
+// `loading` (never read), `ready` (possibly empty), `error` (with whatever was
+// last known). Collapsing the first three into an empty table shows "no cards
+// on file" to a host that simply never wired the endpoints.
+
+import React from 'react';
+import {
+  Alert,
+  AlertDescription,
+  Badge,
+  Button,
+  Skeleton,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@djangocfg/ui-core';
+import { AlertTriangle, CreditCard, Plus } from 'lucide-react';
+import type { SavedCard, SavedCardsPhase } from '../domain/types';
+import { cardsOf, formatCardExpiry, isCardExpired, isCardExpiringSoon } from '../domain/cards';
+
+export interface SavedCardListProps {
+  phase: SavedCardsPhase;
+  /** Open the add-card dialog. Omit to hide the action entirely. */
+  onAddCard?: () => void;
+  /** Make a card the default for renewals. Omit to hide the row action. */
+  onSetDefault?: (id: string) => void;
+  /** Detach a card. Omit to hide the row action. */
+  onRemove?: (id: string) => void;
+  /** Disables every action (a write is in flight). */
+  busy?: boolean;
+  /** Host-supplied words — this package ships no locale. */
+  labels?: Partial<SavedCardListLabels>;
+  className?: string;
+}
+
+export interface SavedCardListLabels {
+  card: string;
+  expires: string;
+  addCard: string;
+  setDefault: string;
+  remove: string;
+  defaultBadge: string;
+  expiringSoon: string;
+  expired: string;
+  empty: string;
+  unavailable: string;
+  /** Why the only card on an active subscription cannot be detached. */
+  lastCardLocked: string;
+}
+
+const DEFAULT_LABELS: SavedCardListLabels = {
+  card: 'Card',
+  expires: 'Expires',
+  addCard: 'Add card',
+  setDefault: 'Make default',
+  remove: 'Remove',
+  defaultBadge: 'Default',
+  expiringSoon: 'Expires soon',
+  expired: 'Expired',
+  empty: 'No card on file.',
+  unavailable: 'Card management is not available for this account.',
+  lastCardLocked: 'Renewals need a card — add another one first.',
+};
+
+/** `visa` → `Visa`. Display only; never branch on a brand. */
+function formatBrand(brand: string): string {
+  if (!brand) return 'Card';
+  return brand.charAt(0).toUpperCase() + brand.slice(1);
+}
+
+interface CardRow {
+  card: SavedCard;
+  label: string;
+  expiry: string;
+  expired: boolean;
+  expiringSoon: boolean;
+  /** Detaching the only card would leave renewals with nothing to charge. */
+  removalLocked: boolean;
+}
+
+export function SavedCardList({
+  phase,
+  onAddCard,
+  onSetDefault,
+  onRemove,
+  busy = false,
+  labels,
+  className,
+}: SavedCardListProps) {
+  const text = { ...DEFAULT_LABELS, ...labels };
+
+  // Not memoized: a customer has a handful of cards, and this surface renders
+  // on one page. Memoizing here would buy nothing and hide the derivation.
+  const cards = cardsOf(phase);
+  const now = new Date();
+  const rows: CardRow[] = cards.map((card) => ({
+    card,
+    label: `${formatBrand(card.brand)} ···· ${card.last4}`,
+    expiry: formatCardExpiry(card),
+    expired: isCardExpired(card, now),
+    expiringSoon: isCardExpiringSoon(card, now),
+    removalLocked: cards.length === 1,
+  }));
+
+  if (phase.kind === 'unavailable') {
+    return (
+      <div className={className}>
+        <p className="text-muted-foreground py-6 text-center text-sm">{text.unavailable}</p>
+      </div>
+    );
+  }
+
+  // A reserved-height skeleton, not nothing: this lane crosses the network, so
+  // content appearing seconds later would read as a bug rather than as loading.
+  if (phase.kind === 'loading') {
+    return (
+      <div className={`space-y-2 ${className ?? ''}`}>
+        <Skeleton className="h-10 w-full" />
+        <Skeleton className="h-10 w-full" />
+      </div>
+    );
+  }
+
+  const showActions = Boolean(onSetDefault || onRemove);
+  const columnCount = showActions ? 4 : 3;
+
+  return (
+    <div className={`space-y-3 ${className ?? ''}`}>
+      {phase.kind === 'error' ? (
+        <Alert variant="destructive">
+          <AlertTriangle className="h-4 w-4" />
+          <AlertDescription>{phase.message}</AlertDescription>
+        </Alert>
+      ) : null}
+
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>{text.card}</TableHead>
+            <TableHead>{text.expires}</TableHead>
+            <TableHead />
+            {showActions ? <TableHead className="text-right" /> : null}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.length === 0 ? (
+            <TableRow>
+              <TableCell colSpan={columnCount} className="text-muted-foreground py-8 text-center">
+                {text.empty}
+              </TableCell>
+            </TableRow>
+          ) : (
+            rows.map((row) => (
+              <TableRow key={row.card.id}>
+                <TableCell className="flex items-center gap-2 font-medium">
+                  <CreditCard className="text-muted-foreground h-4 w-4" aria-hidden />
+                  {row.label}
+                </TableCell>
+                <TableCell>{row.expiry}</TableCell>
+                <TableCell className="space-x-1">
+                  {row.card.isDefault ? (
+                    <Badge variant="secondary">{text.defaultBadge}</Badge>
+                  ) : null}
+                  {row.expired ? (
+                    <Badge variant="destructive">{text.expired}</Badge>
+                  ) : row.expiringSoon ? (
+                    <Badge variant="outline">{text.expiringSoon}</Badge>
+                  ) : null}
+                </TableCell>
+                {showActions ? (
+                  <TableCell className="space-x-2 text-right whitespace-nowrap">
+                    {onSetDefault && !row.card.isDefault ? (
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="sm"
+                        disabled={busy}
+                        onClick={() => onSetDefault(row.card.id)}
+                      >
+                        {text.setDefault}
+                      </Button>
+                    ) : null}
+                    {onRemove ? (
+                      // Disabled WITH a reason, never hidden: a control that
+                      // vanishes reads as a bug, one that explains itself teaches.
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="sm"
+                        disabled={busy || row.removalLocked}
+                        title={row.removalLocked ? text.lastCardLocked : undefined}
+                        onClick={() => onRemove(row.card.id)}
+                      >
+                        {text.remove}
+                      </Button>
+                    ) : null}
+                  </TableCell>
+                ) : null}
+              </TableRow>
+            ))
+          )}
+        </TableBody>
+      </Table>
+
+      {onAddCard ? (
+        <Button type="button" variant="outline" disabled={busy} onClick={onAddCard}>
+          <Plus className="mr-1 h-4 w-4" aria-hidden />
+          {text.addCard}
+        </Button>
+      ) : null}
+    </div>
+  );
+}

package/src/components/StripePaymentElement.tsx

@@ -3,7 +3,8 @@
 // ============================================================================
 // @djangocfg/payments — StripePaymentElement
 // ============================================================================
-// One of TWO files allowed to import @stripe/* (the other is stripe-adapter).
+// One of two files allowed a RUNTIME @stripe/* import (the other is
+// stripe-adapter.ts). Enforced by scripts/check-stripe-imports.mjs.
 // 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`).