create-brainerce-store 1.76.0 → 1.77.0

package/templates/nextjs/base/src/app/checkout/page.tsx

@@ -1,1179 +1,1272 @@
-'use client';
-
-import { Suspense, useEffect, useState, useCallback, useRef } from 'react';
-import { useSearchParams } from 'next/navigation';
-import { CdnImage as Image } from '@/ui/shared/cdn-image';
-import { Link } from '@/core/lib/navigation';
-import type {
-  Checkout,
-  ShippingRate,
-  SetShippingAddressDto,
-  ShippingDestinations,
-  PickupLocation,
-  CheckoutBumpsResponse,
-  CheckoutCustomFieldDefinition,
-} from 'brainerce';
-import { formatPrice } from 'brainerce';
-import { getClient } from '@/core/lib/brainerce';
-import { useStoreInfo, useCart, useAuth, useRegion } from '@/core/providers/store-provider';
-import { useCurrency } from '@/core/lib/use-currency';
-import { CheckoutForm } from '@/components/checkout/checkout-form';
-import { ShippingStep } from '@/components/checkout/shipping-step';
-import { PaymentStep } from '@/components/checkout/payment-step';
-import { DeliveryMethodStep } from '@/components/checkout/delivery-method-step';
-import { PickupStep } from '@/components/checkout/pickup-step';
-import { CustomFieldsStep } from '@/components/checkout/custom-fields-step';
-import { TaxDisplay } from '@/components/checkout/tax-display';
-import { OrderBumpCard } from '@/components/checkout/order-bump-card';
-import { OrderCustomizations } from '@/components/account/order-customizations';
-import { CouponInput } from '@/ui/cart/coupon-input';
-import { GiftCardInput } from '@/ui/cart/gift-card-input';
-import { ReservationCountdown } from '@/ui/cart/reservation-countdown';
-import { LoadingSpinner } from '@/ui/shared/loading-spinner';
-import { useTranslations } from '@/core/lib/translations';
-import { cn } from '@/core/lib/utils';
-import { isValidCheckoutId } from '@/core/lib/safe-redirect';
-import { trackBeginCheckout } from '@/core/lib/tracking';
-
-type CheckoutStep = 'method' | 'address' | 'shipping' | 'pickup' | 'custom-fields' | 'payment';
-
-function CheckoutContent() {
-  const searchParams = useSearchParams();
-  const { storeInfo } = useStoreInfo();
-  const { cart, refreshCart } = useCart();
-  const { isLoggedIn } = useAuth();
-  // ⛔ THE call the region feature exists for. Product reads alone and the
-  // shopper is SHOWN one price and CHARGED another: the checkout records the
-  // region for reporting and for scoping which payment providers are offered.
-  // `undefined` on a store with no regions, and the field is then omitted.
-  const { regionId } = useRegion();
-  const currency = useCurrency();
-  const t = useTranslations('checkout');
-  const tc = useTranslations('common');
-  const tr = useTranslations('reservation');
-
-  const [step, setStep] = useState<CheckoutStep>('address');
-  const [checkout, setCheckout] = useState<Checkout | null>(null);
-  const [shippingRates, setShippingRates] = useState<ShippingRate[]>([]);
-  const [selectedRateId, setSelectedRateId] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [initializing, setInitializing] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [destinations, setDestinations] = useState<ShippingDestinations | null>(null);
-  const [pickupLocations, setPickupLocations] = useState<PickupLocation[]>([]);
-  const [deliveryType, setDeliveryType] = useState<'shipping' | 'pickup'>('shipping');
-  const [isAllDigital, setIsAllDigital] = useState(false);
-  const [prefillAddress, setPrefillAddress] = useState<SetShippingAddressDto | null>(null);
-  const [prefillCustomer, setPrefillCustomer] = useState<{
-    email: string;
-    firstName?: string;
-    lastName?: string;
-    phone?: string;
-  } | null>(null);
-  const [hasSavedAddress, setHasSavedAddress] = useState(false);
-  const [orderBumps, setOrderBumps] = useState<CheckoutBumpsResponse | null>(null);
-  const [addedBumpIds, setAddedBumpIds] = useState<Set<string>>(new Set());
-  const [bumpLoading, setBumpLoading] = useState<string | null>(null);
-  const [customFields, setCustomFields] = useState<CheckoutCustomFieldDefinition[]>([]);
-  const [customFieldValues, setCustomFieldValues] = useState<Record<string, unknown>>({});
-  const [customFieldsLoading, setCustomFieldsLoading] = useState(false);
-
-  // ---- Reservation expiry blocks payment ----
-  //
-  // When the reservation window runs out the held stock goes back on sale, so
-  // the amount and the line items on this page may no longer be deliverable.
-  // Payment is blocked until the shopper revisits the cart. Both pieces of
-  // state key on the reservation's `expiresAt` rather than a bare boolean, so
-  // the block survives a remount of the countdown and the ref stops the cart
-  // refresh from looping. This page does not refetch the checkout, so the
-  // block stands for the rest of the session once it closes.
-  const reservationExpiresAt = checkout?.reservation?.expiresAt ?? null;
-  const handledExpiryRef = useRef<string | null>(null);
-  const [expiredWindow, setExpiredWindow] = useState<string | null>(null);
-  const reservationExpired = expiredWindow !== null && expiredWindow === reservationExpiresAt;
-
-  const handleReservationExpired = useCallback(() => {
-    if (!reservationExpiresAt) return;
-    setExpiredWindow(reservationExpiresAt);
-    if (handledExpiryRef.current === reservationExpiresAt) return;
-    handledExpiryRef.current = reservationExpiresAt;
-    // Keep the header badge honest: the server may have dropped lines that
-    // are no longer purchasable.
-    void refreshCart();
-  }, [reservationExpiresAt, refreshCart]);
-
-  // `begin_checkout` — fired once the cart is loaded, guarded by a ref so a
-  // re-render (or the shopper returning from a canceled payment) doesn't
-  // report a second checkout start for the same cart.
-  const beganCheckoutForCartRef = useRef<string | null>(null);
-  useEffect(() => {
-    if (!cart?.id || !cart.items?.length) return;
-    if (beganCheckoutForCartRef.current === cart.id) return;
-    beganCheckoutForCartRef.current = cart.id;
-    trackBeginCheckout(cart, currency);
-  }, [cart, currency]);
-
-  // Check for returning from canceled payment
-  const canceled = searchParams.get('canceled') === 'true';
-  const checkoutIdParam = searchParams.get('checkout_id');
-  const existingCheckoutId = isValidCheckoutId(checkoutIdParam) ? checkoutIdParam : null;
-
-  // ---- Partial checkout ----
-  //
-  // The cart page hands the ticked lines over as `?items=id1,id2` and omits
-  // the param entirely for a full cart. Read as a raw string here and resolved
-  // against the live cart inside initCheckout: it is URL input, so it is only
-  // ever used after filtering against ids the cart actually has, and it is
-  // read once at init rather than added to the effect's deps — a change must
-  // not silently create a SECOND checkout for the same cart.
-  const selectedItemsParam = searchParams.get('items');
-
-  // Pre-fill address and customer data from profile when logged in
-  useEffect(() => {
-    if (!isLoggedIn) return;
-    getClient()
-      .getCheckoutPrefillData()
-      .then((data) => {
-        if (data.customer) setPrefillCustomer(data.customer);
-        if (data.shippingAddress) {
-          setPrefillAddress(data.shippingAddress);
-          setHasSavedAddress(true);
-        }
-      })
-      .catch(() => {});
-  }, [isLoggedIn]);
-
-  // Initialize or resume checkout (only once)
-  const checkoutInitRef = useRef(false);
-  const cartIdRef = useRef<string | null>(null);
-
-  useEffect(() => {
-    // Only init once, or if cart ID actually changed (e.g. cart was replaced)
-    if (!cart?.id) return;
-    if (checkoutInitRef.current && cartIdRef.current === cart.id) return;
-    checkoutInitRef.current = true;
-    cartIdRef.current = cart.id;
-
-    const initCheckout = async () => {
-      try {
-        setInitializing(true);
-        setError(null);
-        const client = getClient();
-
-        // Fetch shipping destinations and pickup locations in parallel
-        client
-          .getShippingDestinations()
-          .then(setDestinations)
-          .catch(() => {});
-
-        const locations = await client.getPickupLocations().catch(() => [] as PickupLocation[]);
-        setPickupLocations(locations);
-
-        // If returning with existing checkout ID, resume it
-        if (existingCheckoutId) {
-          const existing = await client.getCheckout(existingCheckoutId);
-          setCheckout(existing);
-
-          // Preload custom field definitions and any existing values so the
-          // step indicator and "change options" affordance work on resume.
-          client
-            .getCheckoutCustomFields(existing.id)
-            .then((fields) => {
-              setCustomFields(fields);
-              const existingValues = (
-                existing as unknown as {
-                  customFieldValues?: Record<string, unknown> | null;
-                }
-              ).customFieldValues;
-              if (existingValues) setCustomFieldValues(existingValues);
-            })
-            .catch(() => {
-              setCustomFields([]);
-            });
-
-          // Determine step based on checkout state
-          const allDigital = existing.lineItems.every(
-            (i) => (i.product as unknown as { isDownloadable?: boolean }).isDownloadable
-          );
-          setIsAllDigital(allDigital);
-          if (allDigital) {
-            // Digital products: show contact info step if email not set, else payment
-            setStep(existing.email ? 'payment' : 'address');
-          } else if (existing.deliveryType === 'pickup' && existing.pickupLocation) {
-            setDeliveryType('pickup');
-            setStep('payment');
-          } else if (existing.shippingAddress && existing.shippingRateId) {
-            setStep('payment');
-          } else if (existing.shippingAddress) {
-            // Fetch shipping rates
-            const rates = await client.getShippingRates(existing.id);
-            setShippingRates(rates);
-            setStep('shipping');
-          } else if (locations.length > 0) {
-            setStep('method');
-          }
-          return;
-        }
-
-        // Create new checkout — cart is always server-side now.
-        //
-        // `selectedItemIds` scopes the checkout to a subset of the cart: after
-        // payment those lines are removed and the rest stay in the still-ACTIVE
-        // cart. Sent ONLY when the shopper picked a strict, non-empty subset —
-        // an empty result (a stale link, or ids from another cart) and a
-        // full-cart selection both fall through to the normal whole-cart call,
-        // because omitting the field is what "check out everything" means.
-        const cartItemIds = new Set(cart.items.map((item) => item.id));
-        const requestedItemIds = (selectedItemsParam ?? '')
-          .split(',')
-          .map((id) => id.trim())
-          .filter((id) => cartItemIds.has(id));
-        const isStrictSubset =
-          requestedItemIds.length > 0 && requestedItemIds.length < cartItemIds.size;
-
-        const newCheckout = await client.createCheckout({
-          cartId: cart.id,
-          ...(isStrictSubset ? { selectedItemIds: requestedItemIds } : {}),
-          ...(regionId ? { regionId } : {}),
-        });
-        setCheckout(newCheckout);
-
-        // If all items are downloadable, skip shipping — show contact info step
-        const allDigital = newCheckout.lineItems.every(
-          (i) => (i.product as unknown as { isDownloadable?: boolean }).isDownloadable
-        );
-        setIsAllDigital(allDigital);
-        if (allDigital) {
-          setStep('address');
-          return;
-        }
-
-        // If pickup locations exist, start with delivery method selection
-        if (locations.length > 0) {
-          setStep('method');
-        }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : t('failedToInitCheckout');
-        setError(message);
-      } finally {
-        setInitializing(false);
-      }
-    };
-
-    initCheckout();
-    // `regionId` is a dependency because a checkout is created ONCE per cart:
-    // if the shopper switches region on the cart page and lands here, the
-    // effect has to re-run or the checkout is stamped with the region they
-    // just left.
-  }, [cart?.id, existingCheckoutId, regionId]);
-
-  // Load order bumps when checkout is available
-  useEffect(() => {
-    if (!checkout?.id || storeInfo?.upsell?.checkoutOrderBumpEnabled === false) {
-      setOrderBumps(null);
-      return;
-    }
-    const client = getClient();
-    client
-      .getCheckoutBumps(checkout.id)
-      .then((data) => {
-        setOrderBumps(data);
-        // Detect already-added bumps from cart
-        if (cart?.items) {
-          const existingBumpIds = new Set<string>();
-          for (const item of cart.items) {
-            const meta = item.metadata as Record<string, unknown> | undefined;
-            if (meta?.isOrderBump && meta?.orderBumpId) {
-              existingBumpIds.add(meta.orderBumpId as string);
-            }
-          }
-          setAddedBumpIds(existingBumpIds);
-        }
-      })
-      .catch(() => {});
-  }, [checkout?.id, storeInfo?.upsell?.checkoutOrderBumpEnabled]);
-
-  // Handle bump toggle
-  async function handleBumpToggle(bumpId: string, add: boolean, variantId?: string) {
-    if (!cart?.id || bumpLoading) return;
-    try {
-      setBumpLoading(bumpId);
-      const client = getClient();
-      if (add) {
-        await client.addOrderBump(cart.id, bumpId, variantId);
-        setAddedBumpIds((prev) => new Set([...prev, bumpId]));
-      } else {
-        await client.removeOrderBump(cart.id, bumpId);
-        setAddedBumpIds((prev) => {
-          const next = new Set(prev);
-          next.delete(bumpId);
-          return next;
-        });
-      }
-      await refreshCart();
-    } catch (err) {
-      console.error('Failed to toggle order bump:', err);
-    } finally {
-      setBumpLoading(null);
-    }
-  }
-
-  // Handle shipping address submission
-  async function handleAddressSubmit(
-    address: SetShippingAddressDto,
-    consent: { acceptsMarketing: boolean; saveDetails: boolean }
-  ) {
-    if (!checkout) return;
-
-    try {
-      setLoading(true);
-      setError(null);
-      const client = getClient();
-
-      if (isAllDigital) {
-        // Digital products: set customer info only, skip shipping
-        const updated = await client.setCheckoutCustomer(checkout.id, {
-          email: address.email,
-          firstName: address.firstName,
-          lastName: address.lastName,
-          phone: address.phone,
-          acceptsMarketing: consent.acceptsMarketing,
-          notes: address.notes,
-        });
-        setCheckout(updated);
-        setStep('payment');
-      } else {
-        const response = await client.setShippingAddress(checkout.id, address);
-        setCheckout(response.checkout);
-        setShippingRates(response.rates);
-        setStep('shipping');
-      }
-
-      // Update marketing preference for logged-in users
-      if (isLoggedIn) {
-        try {
-          await client.updateMyProfile({ acceptsMarketing: consent.acceptsMarketing });
-        } catch {
-          // non-critical
-        }
-      }
-
-      // Save address to profile if checkbox was checked and no existing saved address
-      if (isLoggedIn && consent.saveDetails && !hasSavedAddress && !isAllDigital) {
-        try {
-          await client.addMyAddress({
-            firstName: address.firstName,
-            lastName: address.lastName,
-            line1: address.line1,
-            line2: address.line2,
-            city: address.city,
-            region: address.region,
-            postalCode: address.postalCode,
-            country: address.country,
-            phone: address.phone,
-            isDefault: true,
-          });
-        } catch {
-          // non-critical
-        }
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : t('failedToSaveAddress');
-      setError(message);
-    } finally {
-      setLoading(false);
-    }
-  }
-
-  // After shipping/pickup is set, decide whether to show the custom-fields step
-  // or jump straight to payment. Returns the next step.
-  async function loadCustomFieldsOrSkip(checkoutId: string): Promise<CheckoutStep> {
-    try {
-      const fields = await getClient().getCheckoutCustomFields(checkoutId);
-      setCustomFields(fields);
-      return fields.length > 0 ? 'custom-fields' : 'payment';
-    } catch {
-      // If the endpoint isn't available or fails, fall through to payment
-      // rather than blocking the customer.
-      setCustomFields([]);
-      return 'payment';
-    }
-  }
-
-  // Handle shipping method selection
-  async function handleShippingSelect(rateId: string) {
-    if (!checkout) return;
-
-    try {
-      setLoading(true);
-      setError(null);
-      setSelectedRateId(rateId);
-      const client = getClient();
-
-      const updated = await client.selectShippingMethod(checkout.id, rateId);
-      setCheckout(updated);
-      setStep(await loadCustomFieldsOrSkip(updated.id));
-    } catch (err) {
-      const message = err instanceof Error ? err.message : t('failedToSelectShipping');
-      setError(message);
-    } finally {
-      setLoading(false);
-    }
-  }
-
-  // Submit custom fields
-  async function handleCustomFieldsApply() {
-    if (!checkout) return;
-    try {
-      setCustomFieldsLoading(true);
-      setError(null);
-      const updated = await getClient().setCheckoutCustomFields(checkout.id, customFieldValues);
-      setCheckout(updated);
-      setStep('payment');
-    } catch (err) {
-      const message = err instanceof Error ? err.message : t('customFieldsFailed');
-      setError(message);
-    } finally {
-      setCustomFieldsLoading(false);
-    }
-  }
-
-  // Handle delivery method selection
-  async function handleDeliveryTypeSelect(method: 'shipping' | 'pickup') {
-    if (!checkout) return;
-
-    try {
-      setLoading(true);
-      setError(null);
-      setDeliveryType(method);
-      const client = getClient();
-
-      await client.setDeliveryType(checkout.id, method);
-
-      if (method === 'shipping') {
-        setStep('address');
-      } else {
-        setStep('pickup');
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : t('failedToSetDeliveryMethod');
-      setError(message);
-    } finally {
-      setLoading(false);
-    }
-  }
-
-  // Handle pickup location selection
-  async function handlePickupSelect(
-    locationId: string,
-    customerInfo: { email: string; firstName?: string; lastName?: string; phone?: string }
-  ) {
-    if (!checkout) return;
-
-    try {
-      setLoading(true);
-      setError(null);
-      const client = getClient();
-
-      const updated = await client.selectPickupLocation(checkout.id, {
-        pickupRateId: locationId,
-        email: customerInfo.email,
-        firstName: customerInfo.firstName,
-        lastName: customerInfo.lastName,
-        phone: customerInfo.phone,
-      });
-      setCheckout(updated);
-      setStep(await loadCustomFieldsOrSkip(updated.id));
-    } catch (err) {
-      const message = err instanceof Error ? err.message : t('failedToSelectPickup');
-      setError(message);
-    } finally {
-      setLoading(false);
-    }
-  }
-
-  // Refresh cart after coupon apply/remove.
-  // The checkout totals are updated server-side by applyCheckoutCoupon/removeCheckoutCoupon,
-  // so we re-fetch the checkout to get the updated discountAmount and total.
-  const handleCouponUpdate = useCallback(async () => {
-    await refreshCart();
-    if (checkout) {
-      try {
-        const client = getClient();
-        const updated = await client.getCheckout(checkout.id);
-        setCheckout(updated);
-      } catch (err) {
-        console.error('Failed to refresh checkout after coupon update:', err);
-      }
-    }
-  }, [checkout, refreshCart]);
-
-  if (initializing) {
-    return (
-      <div className="flex min-h-[60vh] items-center justify-center">
-        <LoadingSpinner size="lg" />
-      </div>
-    );
-  }
-
-  // Empty cart
-  if (!cart || cart.items.length === 0) {
-    return (
-      <div className="mx-auto max-w-7xl px-4 py-16 text-center sm:px-6 lg:px-8">
-        <h1 className="text-foreground text-2xl font-bold">{t('emptyCart')}</h1>
-        <p className="text-muted-foreground mt-2">{t('emptyCartSubtitle')}</p>
-        <Link
-          href="/products"
-          className="bg-primary text-primary-foreground mt-6 inline-flex items-center rounded px-6 py-3 font-medium transition-opacity hover:opacity-90"
-        >
-          {tc('shopNow')}
-        </Link>
-      </div>
-    );
-  }
-
-  if (error && !checkout) {
-    return (
-      <div className="mx-auto max-w-7xl px-4 py-16 text-center sm:px-6 lg:px-8">
-        <h1 className="text-foreground text-2xl font-bold">{t('errorTitle')}</h1>
-        <p className="text-destructive mt-2">{error}</p>
-        <Link
-          href="/cart"
-          className="bg-primary text-primary-foreground mt-6 inline-flex items-center rounded px-6 py-3 font-medium transition-opacity hover:opacity-90"
-        >
-          {t('returnToCart')}
-        </Link>
-      </div>
-    );
-  }
-
-  const customFieldsStep =
-    customFields.length > 0
-      ? [{ key: 'custom-fields' as CheckoutStep, label: t('stepCustomFields') }]
-      : [];
-
-  const steps: { key: CheckoutStep; label: string }[] = isAllDigital
-    ? [
-        { key: 'address', label: t('stepContactInfo') },
-        ...customFieldsStep,
-        { key: 'payment', label: t('stepPayment') },
-      ]
-    : pickupLocations.length > 0
-      ? deliveryType === 'pickup'
-        ? [
-            { key: 'method', label: t('stepMethod') },
-            { key: 'pickup', label: t('stepPickup') },
-            ...customFieldsStep,
-            { key: 'payment', label: t('stepPayment') },
-          ]
-        : [
-            { key: 'method', label: t('stepMethod') },
-            { key: 'address', label: t('stepAddress') },
-            { key: 'shipping', label: t('stepShipping') },
-            ...customFieldsStep,
-            { key: 'payment', label: t('stepPayment') },
-          ]
-      : [
-          { key: 'address', label: t('stepAddress') },
-          { key: 'shipping', label: t('stepShipping') },
-          ...customFieldsStep,
-          { key: 'payment', label: t('stepPayment') },
-        ];
-
-  const currentStepIndex = steps.findIndex((s) => s.key === step);
-
-  return (
-    <div className="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
-      <h1 className="text-foreground mb-6 text-2xl font-bold">{t('title')}</h1>
-
-      {/* Canceled payment banner */}
-      {canceled && (
-        <div className="mb-6 rounded-lg border border-orange-200 bg-orange-50 px-4 py-3 text-sm text-orange-800 dark:border-orange-800 dark:bg-orange-950/30 dark:text-orange-300">
-          {t('paymentCanceledBanner')}
-        </div>
-      )}
-
-      {/* Reservation countdown. onExpire is what blocks payment below. */}
-      {checkout?.reservation?.hasReservation && (
-        <ReservationCountdown
-          reservation={checkout.reservation}
-          onExpire={handleReservationExpired}
-          className="mb-6"
-        />
-      )}
-
-      {/* Expired reservation: payment is off the table until the cart is
-          reviewed, so say so on every step, not only on the payment step. */}
-      {reservationExpired && (
-        <div className="bg-destructive/10 border-destructive/20 text-destructive mb-6 rounded-lg border px-4 py-3 text-sm">
-          <p>{tr('expiredCheckout')}</p>
-          <Link href="/cart" className="mt-2 inline-flex font-medium underline">
-            {tr('backToCart')}
-          </Link>
-        </div>
-      )}
-
-      {/* Step indicator */}
-      <div className="mb-8 flex items-center gap-2">
-        {steps.map((s, index) => (
-          <div key={s.key} className="flex items-center">
-            {index > 0 && (
-              <div
-                className={cn(
-                  'mx-2 h-px w-8 sm:w-12',
-                  index <= currentStepIndex ? 'bg-primary' : 'bg-border'
-                )}
-              />
-            )}
-            <div className="flex items-center gap-2">
-              <div
-                className={cn(
-                  'flex h-7 w-7 items-center justify-center rounded-full text-xs font-medium',
-                  index < currentStepIndex
-                    ? 'bg-primary text-primary-foreground'
-                    : index === currentStepIndex
-                      ? 'bg-primary text-primary-foreground'
-                      : 'bg-muted text-muted-foreground'
-                )}
-              >
-                {index < currentStepIndex ? (
-                  <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <path
-                      strokeLinecap="round"
-                      strokeLinejoin="round"
-                      strokeWidth={2}
-                      d="M5 13l4 4L19 7"
-                    />
-                  </svg>
-                ) : (
-                  index + 1
-                )}
-              </div>
-              <span
-                className={cn(
-                  'hidden text-sm sm:block',
-                  index <= currentStepIndex
-                    ? 'text-foreground font-medium'
-                    : 'text-muted-foreground'
-                )}
-              >
-                {s.label}
-              </span>
-            </div>
-          </div>
-        ))}
-      </div>
-
-      {/* Error banner */}
-      {error && checkout && (
-        <div className="bg-destructive/10 border-destructive/20 text-destructive mb-6 rounded-lg border px-4 py-3 text-sm">
-          {error}
-        </div>
-      )}
-
-      <div className="grid grid-cols-1 gap-8 lg:grid-cols-3">
-        {/* Main content */}
-        <div className="lg:col-span-2">
-          {/* Delivery Method */}
-          {step === 'method' && (
-            <div>
-              <h2 className="text-foreground mb-4 text-lg font-semibold">{t('deliveryMethod')}</h2>
-              <DeliveryMethodStep onSelect={handleDeliveryTypeSelect} />
-            </div>
-          )}
-
-          {/* Address */}
-          {step === 'address' && (
-            <div>
-              <div className="mb-4 flex items-center justify-between">
-                <h2 className="text-foreground text-lg font-semibold">
-                  {isAllDigital ? t('contactInfo') : t('shippingAddress')}
-                </h2>
-                {!isAllDigital && pickupLocations.length > 0 && (
-                  <button
-                    type="button"
-                    onClick={() => setStep('method')}
-                    className="text-primary text-sm hover:underline"
-                  >
-                    {t('changeMethod')}
-                  </button>
-                )}
-              </div>
-              <CheckoutForm
-                onSubmit={handleAddressSubmit}
-                loading={loading}
-                destinations={isAllDigital ? null : destinations}
-                showSaveDetails={isLoggedIn && !hasSavedAddress && !isAllDigital}
-                emailOnly={isAllDigital}
-                initialValues={
-                  checkout?.shippingAddress
-                    ? {
-                        email: checkout.email || '',
-                        firstName: checkout.shippingAddress.firstName,
-                        lastName: checkout.shippingAddress.lastName,
-                        line1: checkout.shippingAddress.line1,
-                        line2: checkout.shippingAddress.line2 || '',
-                        city: checkout.shippingAddress.city,
-                        region: checkout.shippingAddress.region || '',
-                        postalCode: checkout.shippingAddress.postalCode,
-                        country: checkout.shippingAddress.country,
-                        phone: checkout.shippingAddress.phone || '',
-                      }
-                    : prefillAddress
-                      ? {
-                          email: prefillAddress.email,
-                          firstName: prefillAddress.firstName,
-                          lastName: prefillAddress.lastName,
-                          line1: prefillAddress.line1,
-                          line2: prefillAddress.line2 || '',
-                          city: prefillAddress.city,
-                          region: prefillAddress.region || '',
-                          postalCode: prefillAddress.postalCode,
-                          country: prefillAddress.country,
-                          phone: prefillAddress.phone || '',
-                        }
-                      : prefillCustomer
-                        ? {
-                            email: prefillCustomer.email,
-                            firstName: prefillCustomer.firstName || '',
-                            lastName: prefillCustomer.lastName || '',
-                            phone: prefillCustomer.phone || '',
-                          }
-                        : undefined
-                }
-              />
-            </div>
-          )}
-
-          {/* Step 2: Shipping */}
-          {step === 'shipping' && (
-            <div>
-              <div className="mb-4 flex items-center justify-between">
-                <h2 className="text-foreground text-lg font-semibold">{t('shippingMethod')}</h2>
-                <button
-                  type="button"
-                  onClick={() => setStep('address')}
-                  className="text-primary text-sm hover:underline"
-                >
-                  {t('editAddress')}
-                </button>
-              </div>
-
-              <ShippingStep
-                rates={shippingRates}
-                selectedRateId={selectedRateId}
-                onSelect={handleShippingSelect}
-                loading={loading}
-              />
-            </div>
-          )}
-
-          {/* Pickup */}
-          {step === 'pickup' && (
-            <div>
-              <div className="mb-4 flex items-center justify-between">
-                <h2 className="text-foreground text-lg font-semibold">{t('pickupLocation')}</h2>
-                <button
-                  type="button"
-                  onClick={() => setStep('method')}
-                  className="text-primary text-sm hover:underline"
-                >
-                  {t('changeMethod')}
-                </button>
-              </div>
-              <PickupStep
-                locations={pickupLocations}
-                onSelect={handlePickupSelect}
-                loading={loading}
-                initialEmail={checkout?.email || ''}
-              />
-            </div>
-          )}
-
-          {/* Custom Fields (optional, between shipping/pickup and payment) */}
-          {step === 'custom-fields' && checkout && (
-            <div>
-              <div className="mb-4 flex items-center justify-between">
-                <h2 className="text-foreground text-lg font-semibold">{t('customFieldsTitle')}</h2>
-                <button
-                  type="button"
-                  onClick={() => setStep(deliveryType === 'pickup' ? 'pickup' : 'shipping')}
-                  className="text-primary text-sm hover:underline"
-                >
-                  {deliveryType === 'pickup' ? t('changePickup') : t('changeShipping')}
-                </button>
-              </div>
-              <CustomFieldsStep
-                fields={customFields}
-                values={customFieldValues}
-                onChange={(key, value) =>
-                  setCustomFieldValues((prev) => ({ ...prev, [key]: value }))
-                }
-                onApply={handleCustomFieldsApply}
-                onUploadFile={(file) => getClient().uploadCustomizationFile(file)}
-                timezone={storeInfo?.timezone}
-                loading={customFieldsLoading}
-              />
-            </div>
-          )}
-
-          {/* Payment */}
-          {step === 'payment' && checkout && (
-            <div>
-              <div className="mb-4 flex items-center justify-between">
-                <h2 className="text-foreground text-lg font-semibold">{t('payment')}</h2>
-                {customFields.length > 0 ? (
-                  <button
-                    type="button"
-                    onClick={() => setStep('custom-fields')}
-                    className="text-primary text-sm hover:underline"
-                  >
-                    {t('changeOptions')}
-                  </button>
-                ) : (
-                  !isAllDigital && (
-                    <button
-                      type="button"
-                      onClick={() => setStep(deliveryType === 'pickup' ? 'pickup' : 'shipping')}
-                      className="text-primary text-sm hover:underline"
-                    >
-                      {deliveryType === 'pickup' ? t('changePickup') : t('changeShipping')}
-                    </button>
-                  )
-                )}
-              </div>
-
-              {/* Never mount the payment form on an expired reservation: the
-                  stock behind these lines is back on sale, so a charge here
-                  can take money for something that cannot ship. */}
-              {reservationExpired ? (
-                <div className="border-border rounded-lg border px-4 py-6 text-center">
-                  <p className="text-foreground text-sm font-medium">{tr('expired')}</p>
-                  <p className="text-muted-foreground mt-1 text-sm">{tr('expiredCheckout')}</p>
-                  <Link
-                    href="/cart"
-                    className="bg-primary text-primary-foreground mt-4 inline-flex items-center rounded px-6 py-3 text-sm font-medium transition-opacity hover:opacity-90"
-                  >
-                    {tr('backToCart')}
-                  </Link>
-                </div>
-              ) : (
-                <PaymentStep checkoutId={checkout.id} />
-              )}
-            </div>
-          )}
-        </div>
-
-        {/* Order summary sidebar */}
-        <div className="lg:col-span-1">
-          <div className="bg-muted/50 border-border sticky top-24 rounded-lg border p-6">
-            <h3 className="text-foreground mb-4 text-lg font-semibold">{t('orderSummary')}</h3>
-
-            {/* Line items */}
-            {checkout?.lineItems && checkout.lineItems.length > 0 ? (
-              <div className="mb-4 space-y-3">
-                {checkout.lineItems.map((item) => {
-                  const imageUrl = item.product.images?.[0]?.url || null;
-                  const name = item.variant?.name || item.product.name;
-                  const lineTotal = parseFloat(item.unitPrice) * item.quantity;
-
-                  return (
-                    <div key={item.id} className="space-y-1">
-                      <div className="flex gap-3">
-                        <div className="bg-muted relative h-12 w-12 flex-shrink-0 overflow-hidden rounded">
-                          {imageUrl ? (
-                            <Image
-                              src={imageUrl}
-                              alt={name}
-                              fill
-                              sizes="48px"
-                              className="object-cover"
-                            />
-                          ) : (
-                            <div className="text-muted-foreground absolute inset-0 flex items-center justify-center">
-                              <svg
-                                className="h-5 w-5"
-                                fill="none"
-                                viewBox="0 0 24 24"
-                                stroke="currentColor"
-                              >
-                                <path
-                                  strokeLinecap="round"
-                                  strokeLinejoin="round"
-                                  strokeWidth={1.5}
-                                  d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
-                                />
-                              </svg>
-                            </div>
-                          )}
-                        </div>
-
-                        <div className="min-w-0 flex-1">
-                          <p className="text-foreground truncate text-sm">{name}</p>
-                          <p className="text-muted-foreground text-xs">
-                            {tc('qty')} {item.quantity}
-                          </p>
-                        </div>
-
-                        <span className="text-foreground flex-shrink-0 text-sm font-medium">
-                          {formatPrice(lineTotal, { currency }) as string}
-                        </span>
-                      </div>
-
-                      {/* The buyer's own input on this line — engraving text,
-                          uploaded photo, picked colour — so it can be checked
-                          before paying. `CheckoutLineItem.customizations` is
-                          the SDK's resolved label/value/type map, absent on a
-                          line with no customization, so a plain order renders
-                          exactly as before. */}
-                      {item.customizations && (
-                        <OrderCustomizations customizations={item.customizations} />
-                      )}
-                    </div>
-                  );
-                })}
-              </div>
-            ) : (
-              // Fallback to cart items if checkout line items aren't loaded yet
-              cart && (
-                <div className="mb-4 space-y-2">
-                  <p className="text-muted-foreground text-sm">
-                    {cart.items.length} {cart.items.length === 1 ? tc('item') : tc('items')}
-                  </p>
-                </div>
-              )
-            )}
-
-            {/* Order bumps */}
-            {orderBumps?.bumps && orderBumps.bumps.length > 0 && (
-              <div className="border-border space-y-2 border-t pt-4">
-                <p className="text-foreground text-xs font-semibold uppercase tracking-wide">
-                  {t('addToYourOrder')}
-                </p>
-                {orderBumps.bumps.map((bump) => (
-                  <OrderBumpCard
-                    key={bump.id}
-                    bump={bump}
-                    isAdded={addedBumpIds.has(bump.id)}
-                    onToggle={handleBumpToggle}
-                    loading={bumpLoading === bump.id}
-                  />
-                ))}
-              </div>
-            )}
-
-            {/* Coupon input — show from shipping/pickup step onwards (or immediately if digital) */}
-            {cart &&
-              (isAllDigital || step === 'shipping' || step === 'pickup' || step === 'payment') && (
-                <div className="border-border border-t pt-4">
-                  <CouponInput
-                    cart={cart}
-                    checkoutId={checkout?.id}
-                    onUpdate={handleCouponUpdate}
-                  />
-                  {/* Beside the coupon field, and deliberately NOT inside it. A
-                      coupon reduces what the order is worth; a gift card pays
-                      for an order still worth the same. They look adjacent
-                      because a shopper reaches for them at the same moment, and
-                      they behave differently because they are different things. */}
-                  {checkout?.id && (
-                    <GiftCardInput
-                      className="mt-3"
-                      checkoutId={checkout.id}
-                      tenders={checkout.tenders ?? []}
-                      formatAmount={(value) =>
-                        formatPrice(parseFloat(value), { currency }) as string
-                      }
-                      onUpdate={handleCouponUpdate}
-                    />
-                  )}
-                </div>
-              )}
-
-            {/* Totals */}
-            {checkout &&
-              (() => {
-                // When the store prices include tax (VAT-style), the on-row
-                // `checkout.subtotal` is GROSS — it already contains the tax.
-                // Show the net (tax-excluded) value here, then a separate VAT
-                // line below, so the customer sees the breakdown the merchant
-                // asked for. Falls back to the raw subtotal when no breakdown
-                // is available yet (e.g. shipping address not entered).
-                const isInclusive = checkout.taxBreakdown?.pricesIncludeTax === true;
-                const displayedSubtotal =
-                  isInclusive && typeof checkout.taxBreakdown?.subtotal === 'number'
-                    ? checkout.taxBreakdown.subtotal
-                    : parseFloat(checkout.subtotal);
-                const subtotalLabel = isInclusive ? tc('subtotalExclTax') : tc('subtotal');
-                return (
-                  <div className="border-border space-y-2 border-t pt-4 text-sm">
-                    <div className="flex items-center justify-between">
-                      <span className="text-muted-foreground">{subtotalLabel}</span>
-                      <span className="text-foreground">
-                        {formatPrice(displayedSubtotal, { currency }) as string}
-                      </span>
-                    </div>
-
-                    {(() => {
-                      const totalDiscount = parseFloat(checkout.discountAmount);
-                      const ruleAmt = parseFloat(checkout.ruleDiscountAmount || '0');
-                      const couponAmt = totalDiscount - ruleAmt;
-                      const rules = cart?.appliedDiscounts;
-                      if (totalDiscount <= 0) return null;
-                      return (
-                        <>
-                          {rules && rules.length > 0
-                            ? rules.map((rule) => (
-                                <div
-                                  key={rule.ruleId}
-                                  className="flex items-center justify-between"
-                                >
-                                  <span className="text-muted-foreground">{rule.ruleName}</span>
-                                  <span className="text-destructive">
-                                    -
-                                    {
-                                      formatPrice(parseFloat(rule.discountAmount), {
-                                        currency,
-                                      }) as string
-                                    }
-                                  </span>
-                                </div>
-                              ))
-                            : ruleAmt > 0 && (
-                                <div className="flex items-center justify-between">
-                                  <span className="text-muted-foreground">
-                                    {tc('generalDiscount')}
-                                  </span>
-                                  <span className="text-destructive">
-                                    -{formatPrice(ruleAmt, { currency }) as string}
-                                  </span>
-                                </div>
-                              )}
-                          {checkout.couponCode && couponAmt > 0 && (
-                            <div className="flex items-center justify-between">
-                              <span className="text-muted-foreground">
-                                {tc('couponDiscount')} ({checkout.couponCode})
-                              </span>
-                              <span className="text-destructive">
-                                -{formatPrice(couponAmt, { currency }) as string}
-                              </span>
-                            </div>
-                          )}
-                          {!checkout.couponCode &&
-                            ruleAmt <= 0 &&
-                            (!rules || rules.length === 0) && (
-                              <div className="flex items-center justify-between">
-                                <span className="text-muted-foreground">{tc('discount')}</span>
-                                <span className="text-destructive">
-                                  -{formatPrice(totalDiscount, { currency }) as string}
-                                </span>
-                              </div>
-                            )}
-                        </>
-                      );
-                    })()}
-
-                    {(parseFloat(checkout.shippingAmount) > 0 ||
-                      checkout.deliveryType === 'pickup') && (
-                      <div className="flex items-center justify-between">
-                        <span className="text-muted-foreground">
-                          {checkout.deliveryType === 'pickup' ? tc('pickup') : tc('shipping')}
-                        </span>
-                        <span className="text-foreground">
-                          {parseFloat(checkout.shippingAmount) === 0
-                            ? tc('free')
-                            : (formatPrice(parseFloat(checkout.shippingAmount), {
-                                currency,
-                              }) as string)}
-                        </span>
-                      </div>
-                    )}
-
-                    <TaxDisplay
-                      addressSet={!!checkout.shippingAddress}
-                      taxAmount={checkout.taxAmount}
-                      taxBreakdown={checkout.taxBreakdown}
-                    />
-
-                    {/* Custom field surcharges (one line per applied surcharge) */}
-                    {checkout.appliedSurcharges && checkout.appliedSurcharges.length > 0 && (
-                      <>
-                        {checkout.appliedSurcharges.map((s) => (
-                          <div key={s.key} className="flex items-center justify-between">
-                            <span className="text-muted-foreground">{s.name}</span>
-                            <span className="text-foreground">
-                              {formatPrice(Number(s.amount), { currency }) as string}
-                            </span>
-                          </div>
-                        ))}
-                      </>
-                    )}
-
-                    <div className="border-border mt-2 border-t pt-2">
-                      <div className="flex items-center justify-between">
-                        <span className="text-foreground font-semibold">{tc('total')}</span>
-                        <span className="text-foreground text-base font-semibold">
-                          {formatPrice(parseFloat(checkout.total), { currency }) as string}
-                        </span>
-                      </div>
-
-                      {/* Gift cards sit BELOW the total, not among the discounts
-                          above it. The total is what the order is worth and does
-                          not move; what changes is only what the card leaves for
-                          the payment provider to charge. Putting this in the
-                          discount block would understate the taxable base to the
-                          shopper and on the receipt. */}
-                      {checkout.tenders && checkout.tenders.length > 0 && (
-                        <>
-                          {checkout.tenders.map((tender) => (
-                            <div
-                              key={tender.tenderId}
-                              className="mt-2 flex items-center justify-between text-sm"
-                            >
-                              <span className="text-muted-foreground">{tc('giftCard')}</span>
-                              <span className="text-primary">
-                                -
-                                {
-                                  formatPrice(parseFloat(tender.amountApplied), {
-                                    currency,
-                                  }) as string
-                                }
-                              </span>
-                            </div>
-                          ))}
-                          <div className="border-border mt-2 flex items-center justify-between border-t pt-2">
-                            <span className="text-foreground font-semibold">{tc('amountDue')}</span>
-                            <span className="text-foreground text-base font-semibold">
-                              {
-                                formatPrice(parseFloat(checkout.providerAmountDue ?? checkout.total), {
-                                  currency,
-                                }) as string
-                              }
-                            </span>
-                          </div>
-                        </>
-                      )}
-                    </div>
-                  </div>
-                );
-              })()}
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-export default function CheckoutPage() {
-  return (
-    <Suspense
-      fallback={
-        <div className="flex min-h-[60vh] items-center justify-center">
-          <LoadingSpinner size="lg" />
-        </div>
-      }
-    >
-      <CheckoutContent />
-    </Suspense>
-  );
-}
+'use client';
+
+import { Suspense, useEffect, useState, useCallback, useRef } from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
+import { Link } from '@/core/lib/navigation';
+import type {
+  Checkout,
+  ShippingRate,
+  SetShippingAddressDto,
+  ShippingDestinations,
+  PickupLocation,
+  CheckoutBumpsResponse,
+  CheckoutCustomFieldDefinition,
+} from 'brainerce';
+import { formatPrice } from 'brainerce';
+import { getClient } from '@/core/lib/brainerce';
+import { useStoreInfo, useCart, useAuth, useRegion } from '@/core/providers/store-provider';
+import { useCurrency } from '@/core/lib/use-currency';
+import { CheckoutForm } from '@/components/checkout/checkout-form';
+import { ShippingStep } from '@/components/checkout/shipping-step';
+import { PaymentStep } from '@/components/checkout/payment-step';
+import { DeliveryMethodStep } from '@/components/checkout/delivery-method-step';
+import { PickupStep } from '@/components/checkout/pickup-step';
+import { CustomFieldsStep } from '@/components/checkout/custom-fields-step';
+import { TaxDisplay } from '@/components/checkout/tax-display';
+import { OrderBumpCard } from '@/components/checkout/order-bump-card';
+import { OrderCustomizations } from '@/components/account/order-customizations';
+import { CouponInput } from '@/ui/cart/coupon-input';
+import { GiftCardInput } from '@/ui/cart/gift-card-input';
+import { ReservationCountdown } from '@/ui/cart/reservation-countdown';
+import { LoadingSpinner } from '@/ui/shared/loading-spinner';
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+import { isValidCheckoutId } from '@/core/lib/safe-redirect';
+import { trackBeginCheckout } from '@/core/lib/tracking';
+
+type CheckoutStep = 'method' | 'address' | 'shipping' | 'pickup' | 'custom-fields' | 'payment';
+
+function CheckoutContent() {
+  const searchParams = useSearchParams();
+  const { storeInfo } = useStoreInfo();
+  const { cart, refreshCart } = useCart();
+  const { isLoggedIn } = useAuth();
+  // ⛔ THE call the region feature exists for. Product reads alone and the
+  // shopper is SHOWN one price and CHARGED another: the checkout records the
+  // region for reporting and for scoping which payment providers are offered.
+  // `undefined` on a store with no regions, and the field is then omitted.
+  const { regionId } = useRegion();
+  const currency = useCurrency();
+  const router = useRouter();
+  const t = useTranslations('checkout');
+  const tc = useTranslations('common');
+  const tr = useTranslations('reservation');
+
+  const [step, setStep] = useState<CheckoutStep>('address');
+  const [checkout, setCheckout] = useState<Checkout | null>(null);
+  const [placing, setPlacing] = useState(false);
+  const [placeError, setPlaceError] = useState<string | null>(null);
+  const [shippingRates, setShippingRates] = useState<ShippingRate[]>([]);
+  const [selectedRateId, setSelectedRateId] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [initializing, setInitializing] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [destinations, setDestinations] = useState<ShippingDestinations | null>(null);
+  const [pickupLocations, setPickupLocations] = useState<PickupLocation[]>([]);
+  const [deliveryType, setDeliveryType] = useState<'shipping' | 'pickup'>('shipping');
+  const [isAllDigital, setIsAllDigital] = useState(false);
+  const [prefillAddress, setPrefillAddress] = useState<SetShippingAddressDto | null>(null);
+  const [prefillCustomer, setPrefillCustomer] = useState<{
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+  } | null>(null);
+  const [hasSavedAddress, setHasSavedAddress] = useState(false);
+  const [orderBumps, setOrderBumps] = useState<CheckoutBumpsResponse | null>(null);
+  const [addedBumpIds, setAddedBumpIds] = useState<Set<string>>(new Set());
+  const [bumpLoading, setBumpLoading] = useState<string | null>(null);
+  const [customFields, setCustomFields] = useState<CheckoutCustomFieldDefinition[]>([]);
+  const [customFieldValues, setCustomFieldValues] = useState<Record<string, unknown>>({});
+  const [customFieldsLoading, setCustomFieldsLoading] = useState(false);
+
+  // ---- Reservation expiry blocks payment ----
+  //
+  // When the reservation window runs out the held stock goes back on sale, so
+  // the amount and the line items on this page may no longer be deliverable.
+  // Payment is blocked until the shopper revisits the cart. Both pieces of
+  // state key on the reservation's `expiresAt` rather than a bare boolean, so
+  // the block survives a remount of the countdown and the ref stops the cart
+  // refresh from looping. This page does not refetch the checkout, so the
+  // block stands for the rest of the session once it closes.
+  const reservationExpiresAt = checkout?.reservation?.expiresAt ?? null;
+  const handledExpiryRef = useRef<string | null>(null);
+  const [expiredWindow, setExpiredWindow] = useState<string | null>(null);
+  const reservationExpired = expiredWindow !== null && expiredWindow === reservationExpiresAt;
+
+  const handleReservationExpired = useCallback(() => {
+    if (!reservationExpiresAt) return;
+    setExpiredWindow(reservationExpiresAt);
+    if (handledExpiryRef.current === reservationExpiresAt) return;
+    handledExpiryRef.current = reservationExpiresAt;
+    // Keep the header badge honest: the server may have dropped lines that
+    // are no longer purchasable.
+    void refreshCart();
+  }, [reservationExpiresAt, refreshCart]);
+
+  // `begin_checkout` — fired once the cart is loaded, guarded by a ref so a
+  // re-render (or the shopper returning from a canceled payment) doesn't
+  // report a second checkout start for the same cart.
+  const beganCheckoutForCartRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!cart?.id || !cart.items?.length) return;
+    if (beganCheckoutForCartRef.current === cart.id) return;
+    beganCheckoutForCartRef.current = cart.id;
+    trackBeginCheckout(cart, currency);
+  }, [cart, currency]);
+
+  /**
+   * Whether gift cards already cover the whole order.
+   *
+   * Read from `providerAmountDue`, which the SERVER computes — never from a
+   * subtraction done here. The total is deliberately unchanged by a gift card,
+   * so any figure derived in the browser would have to re-implement the tender
+   * arithmetic and could disagree with what the backend will actually charge.
+   */
+  const isFullyCovered =
+    !!checkout && parseFloat(checkout.providerAmountDue ?? checkout.total) <= 0;
+
+  const handlePlaceFreeOrder = async () => {
+    if (!checkout || placing) return;
+    try {
+      setPlacing(true);
+      setPlaceError(null);
+      const { orderId } = await getClient().completeCheckout(checkout.id);
+      router.push(`/order-confirmation?orderId=${encodeURIComponent(orderId)}`);
+    } catch (err) {
+      // Said out loud. A silent failure here leaves someone staring at a button
+      // that did nothing, holding a card they believe they have already spent.
+      setPlaceError(err instanceof Error ? err.message : t('placeFailed'));
+      setPlacing(false);
+    }
+  };
+
+  // Check for returning from canceled payment
+  const canceled = searchParams.get('canceled') === 'true';
+  const checkoutIdParam = searchParams.get('checkout_id');
+  const existingCheckoutId = isValidCheckoutId(checkoutIdParam) ? checkoutIdParam : null;
+
+  // ---- Partial checkout ----
+  //
+  // The cart page hands the ticked lines over as `?items=id1,id2` and omits
+  // the param entirely for a full cart. Read as a raw string here and resolved
+  // against the live cart inside initCheckout: it is URL input, so it is only
+  // ever used after filtering against ids the cart actually has, and it is
+  // read once at init rather than added to the effect's deps — a change must
+  // not silently create a SECOND checkout for the same cart.
+  const selectedItemsParam = searchParams.get('items');
+
+  // Pre-fill address and customer data from profile when logged in
+  useEffect(() => {
+    if (!isLoggedIn) return;
+    getClient()
+      .getCheckoutPrefillData()
+      .then((data) => {
+        if (data.customer) setPrefillCustomer(data.customer);
+        if (data.shippingAddress) {
+          setPrefillAddress(data.shippingAddress);
+          setHasSavedAddress(true);
+        }
+      })
+      .catch(() => {});
+  }, [isLoggedIn]);
+
+  // Initialize or resume checkout (only once)
+  const checkoutInitRef = useRef(false);
+  const cartIdRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    // Only init once, or if cart ID actually changed (e.g. cart was replaced)
+    if (!cart?.id) return;
+    if (checkoutInitRef.current && cartIdRef.current === cart.id) return;
+    checkoutInitRef.current = true;
+    cartIdRef.current = cart.id;
+
+    const initCheckout = async () => {
+      try {
+        setInitializing(true);
+        setError(null);
+        const client = getClient();
+
+        // Fetch shipping destinations and pickup locations in parallel
+        client
+          .getShippingDestinations()
+          .then(setDestinations)
+          .catch(() => {});
+
+        const locations = await client.getPickupLocations().catch(() => [] as PickupLocation[]);
+        setPickupLocations(locations);
+
+        // If returning with existing checkout ID, resume it
+        if (existingCheckoutId) {
+          const existing = await client.getCheckout(existingCheckoutId);
+          setCheckout(existing);
+
+          // Preload custom field definitions and any existing values so the
+          // step indicator and "change options" affordance work on resume.
+          client
+            .getCheckoutCustomFields(existing.id)
+            .then((fields) => {
+              setCustomFields(fields);
+              const existingValues = (
+                existing as unknown as {
+                  customFieldValues?: Record<string, unknown> | null;
+                }
+              ).customFieldValues;
+              if (existingValues) setCustomFieldValues(existingValues);
+            })
+            .catch(() => {
+              setCustomFields([]);
+            });
+
+          // Determine step based on checkout state
+          const allDigital = existing.lineItems.every(
+            (i) => (i.product as unknown as { isDownloadable?: boolean }).isDownloadable
+          );
+          setIsAllDigital(allDigital);
+          if (allDigital) {
+            // Digital products: show contact info step if email not set, else payment
+            setStep(existing.email ? 'payment' : 'address');
+          } else if (existing.deliveryType === 'pickup' && existing.pickupLocation) {
+            setDeliveryType('pickup');
+            setStep('payment');
+          } else if (existing.shippingAddress && existing.shippingRateId) {
+            setStep('payment');
+          } else if (existing.shippingAddress) {
+            // Fetch shipping rates
+            const rates = await client.getShippingRates(existing.id);
+            setShippingRates(rates);
+            setStep('shipping');
+          } else if (locations.length > 0) {
+            setStep('method');
+          }
+          return;
+        }
+
+        // Create new checkout — cart is always server-side now.
+        //
+        // `selectedItemIds` scopes the checkout to a subset of the cart: after
+        // payment those lines are removed and the rest stay in the still-ACTIVE
+        // cart. Sent ONLY when the shopper picked a strict, non-empty subset —
+        // an empty result (a stale link, or ids from another cart) and a
+        // full-cart selection both fall through to the normal whole-cart call,
+        // because omitting the field is what "check out everything" means.
+        const cartItemIds = new Set(cart.items.map((item) => item.id));
+        const requestedItemIds = (selectedItemsParam ?? '')
+          .split(',')
+          .map((id) => id.trim())
+          .filter((id) => cartItemIds.has(id));
+        const isStrictSubset =
+          requestedItemIds.length > 0 && requestedItemIds.length < cartItemIds.size;
+
+        const newCheckout = await client.createCheckout({
+          cartId: cart.id,
+          ...(isStrictSubset ? { selectedItemIds: requestedItemIds } : {}),
+          ...(regionId ? { regionId } : {}),
+        });
+        setCheckout(newCheckout);
+
+        // Put the id in the URL so a RELOAD resumes instead of starting over.
+        //
+        // The resume path above already reads `?checkout_id=`, but until now only
+        // a payment provider's return URL ever set it. A shopper who refreshed
+        // lost their address, their shipping choice, and — visibly — any gift
+        // card they had applied, because a fresh checkout cannot see holds that
+        // belong to the abandoned one. The money was never lost, but it looked
+        // lost, and re-entering the same code was correctly refused because the
+        // old hold still reserved it.
+        //
+        // `replaceState`, not router.replace: this is the same page and the same
+        // checkout, so it must not push history, re-render, or move the scroll
+        // position out from under someone mid-form.
+        if (typeof window !== 'undefined') {
+          const url = new URL(window.location.href);
+          url.searchParams.set('checkout_id', newCheckout.id);
+          window.history.replaceState(window.history.state, '', url);
+        }
+
+        // If all items are downloadable, skip shipping — show contact info step
+        const allDigital = newCheckout.lineItems.every(
+          (i) => (i.product as unknown as { isDownloadable?: boolean }).isDownloadable
+        );
+        setIsAllDigital(allDigital);
+        if (allDigital) {
+          setStep('address');
+          return;
+        }
+
+        // If pickup locations exist, start with delivery method selection
+        if (locations.length > 0) {
+          setStep('method');
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : t('failedToInitCheckout');
+        setError(message);
+      } finally {
+        setInitializing(false);
+      }
+    };
+
+    initCheckout();
+    // `regionId` is a dependency because a checkout is created ONCE per cart:
+    // if the shopper switches region on the cart page and lands here, the
+    // effect has to re-run or the checkout is stamped with the region they
+    // just left.
+  }, [cart?.id, existingCheckoutId, regionId]);
+
+  // Load order bumps when checkout is available
+  useEffect(() => {
+    if (!checkout?.id || storeInfo?.upsell?.checkoutOrderBumpEnabled === false) {
+      setOrderBumps(null);
+      return;
+    }
+    const client = getClient();
+    client
+      .getCheckoutBumps(checkout.id)
+      .then((data) => {
+        setOrderBumps(data);
+        // Detect already-added bumps from cart
+        if (cart?.items) {
+          const existingBumpIds = new Set<string>();
+          for (const item of cart.items) {
+            const meta = item.metadata as Record<string, unknown> | undefined;
+            if (meta?.isOrderBump && meta?.orderBumpId) {
+              existingBumpIds.add(meta.orderBumpId as string);
+            }
+          }
+          setAddedBumpIds(existingBumpIds);
+        }
+      })
+      .catch(() => {});
+  }, [checkout?.id, storeInfo?.upsell?.checkoutOrderBumpEnabled]);
+
+  // Handle bump toggle
+  async function handleBumpToggle(bumpId: string, add: boolean, variantId?: string) {
+    if (!cart?.id || bumpLoading) return;
+    try {
+      setBumpLoading(bumpId);
+      const client = getClient();
+      if (add) {
+        await client.addOrderBump(cart.id, bumpId, variantId);
+        setAddedBumpIds((prev) => new Set([...prev, bumpId]));
+      } else {
+        await client.removeOrderBump(cart.id, bumpId);
+        setAddedBumpIds((prev) => {
+          const next = new Set(prev);
+          next.delete(bumpId);
+          return next;
+        });
+      }
+      await refreshCart();
+    } catch (err) {
+      console.error('Failed to toggle order bump:', err);
+    } finally {
+      setBumpLoading(null);
+    }
+  }
+
+  // Handle shipping address submission
+  async function handleAddressSubmit(
+    address: SetShippingAddressDto,
+    consent: { acceptsMarketing: boolean; saveDetails: boolean }
+  ) {
+    if (!checkout) return;
+
+    try {
+      setLoading(true);
+      setError(null);
+      const client = getClient();
+
+      if (isAllDigital) {
+        // Digital products: set customer info only, skip shipping
+        const updated = await client.setCheckoutCustomer(checkout.id, {
+          email: address.email,
+          firstName: address.firstName,
+          lastName: address.lastName,
+          phone: address.phone,
+          acceptsMarketing: consent.acceptsMarketing,
+          notes: address.notes,
+        });
+        setCheckout(updated);
+        setStep('payment');
+      } else {
+        const response = await client.setShippingAddress(checkout.id, address);
+        setCheckout(response.checkout);
+        setShippingRates(response.rates);
+        setStep('shipping');
+      }
+
+      // Update marketing preference for logged-in users
+      if (isLoggedIn) {
+        try {
+          await client.updateMyProfile({ acceptsMarketing: consent.acceptsMarketing });
+        } catch {
+          // non-critical
+        }
+      }
+
+      // Save address to profile if checkbox was checked and no existing saved address
+      if (isLoggedIn && consent.saveDetails && !hasSavedAddress && !isAllDigital) {
+        try {
+          await client.addMyAddress({
+            firstName: address.firstName,
+            lastName: address.lastName,
+            line1: address.line1,
+            line2: address.line2,
+            city: address.city,
+            region: address.region,
+            postalCode: address.postalCode,
+            country: address.country,
+            phone: address.phone,
+            isDefault: true,
+          });
+        } catch {
+          // non-critical
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('failedToSaveAddress');
+      setError(message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  // After shipping/pickup is set, decide whether to show the custom-fields step
+  // or jump straight to payment. Returns the next step.
+  async function loadCustomFieldsOrSkip(checkoutId: string): Promise<CheckoutStep> {
+    try {
+      const fields = await getClient().getCheckoutCustomFields(checkoutId);
+      setCustomFields(fields);
+      return fields.length > 0 ? 'custom-fields' : 'payment';
+    } catch {
+      // If the endpoint isn't available or fails, fall through to payment
+      // rather than blocking the customer.
+      setCustomFields([]);
+      return 'payment';
+    }
+  }
+
+  // Handle shipping method selection
+  async function handleShippingSelect(rateId: string) {
+    if (!checkout) return;
+
+    try {
+      setLoading(true);
+      setError(null);
+      setSelectedRateId(rateId);
+      const client = getClient();
+
+      const updated = await client.selectShippingMethod(checkout.id, rateId);
+      setCheckout(updated);
+      setStep(await loadCustomFieldsOrSkip(updated.id));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('failedToSelectShipping');
+      setError(message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  // Submit custom fields
+  async function handleCustomFieldsApply() {
+    if (!checkout) return;
+    try {
+      setCustomFieldsLoading(true);
+      setError(null);
+      const updated = await getClient().setCheckoutCustomFields(checkout.id, customFieldValues);
+      setCheckout(updated);
+      setStep('payment');
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('customFieldsFailed');
+      setError(message);
+    } finally {
+      setCustomFieldsLoading(false);
+    }
+  }
+
+  // Handle delivery method selection
+  async function handleDeliveryTypeSelect(method: 'shipping' | 'pickup') {
+    if (!checkout) return;
+
+    try {
+      setLoading(true);
+      setError(null);
+      setDeliveryType(method);
+      const client = getClient();
+
+      await client.setDeliveryType(checkout.id, method);
+
+      if (method === 'shipping') {
+        setStep('address');
+      } else {
+        setStep('pickup');
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('failedToSetDeliveryMethod');
+      setError(message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  // Handle pickup location selection
+  async function handlePickupSelect(
+    locationId: string,
+    customerInfo: { email: string; firstName?: string; lastName?: string; phone?: string }
+  ) {
+    if (!checkout) return;
+
+    try {
+      setLoading(true);
+      setError(null);
+      const client = getClient();
+
+      const updated = await client.selectPickupLocation(checkout.id, {
+        pickupRateId: locationId,
+        email: customerInfo.email,
+        firstName: customerInfo.firstName,
+        lastName: customerInfo.lastName,
+        phone: customerInfo.phone,
+      });
+      setCheckout(updated);
+      setStep(await loadCustomFieldsOrSkip(updated.id));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('failedToSelectPickup');
+      setError(message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  // Refresh cart after coupon apply/remove.
+  // The checkout totals are updated server-side by applyCheckoutCoupon/removeCheckoutCoupon,
+  // so we re-fetch the checkout to get the updated discountAmount and total.
+  const handleCouponUpdate = useCallback(async () => {
+    await refreshCart();
+    if (checkout) {
+      try {
+        const client = getClient();
+        const updated = await client.getCheckout(checkout.id);
+        setCheckout(updated);
+      } catch (err) {
+        console.error('Failed to refresh checkout after coupon update:', err);
+      }
+    }
+  }, [checkout, refreshCart]);
+
+  if (initializing) {
+    return (
+      <div className="flex min-h-[60vh] items-center justify-center">
+        <LoadingSpinner size="lg" />
+      </div>
+    );
+  }
+
+  // Empty cart
+  if (!cart || cart.items.length === 0) {
+    return (
+      <div className="mx-auto max-w-7xl px-4 py-16 text-center sm:px-6 lg:px-8">
+        <h1 className="text-foreground text-2xl font-bold">{t('emptyCart')}</h1>
+        <p className="text-muted-foreground mt-2">{t('emptyCartSubtitle')}</p>
+        <Link
+          href="/products"
+          className="bg-primary text-primary-foreground mt-6 inline-flex items-center rounded px-6 py-3 font-medium transition-opacity hover:opacity-90"
+        >
+          {tc('shopNow')}
+        </Link>
+      </div>
+    );
+  }
+
+  if (error && !checkout) {
+    return (
+      <div className="mx-auto max-w-7xl px-4 py-16 text-center sm:px-6 lg:px-8">
+        <h1 className="text-foreground text-2xl font-bold">{t('errorTitle')}</h1>
+        <p className="text-destructive mt-2">{error}</p>
+        <Link
+          href="/cart"
+          className="bg-primary text-primary-foreground mt-6 inline-flex items-center rounded px-6 py-3 font-medium transition-opacity hover:opacity-90"
+        >
+          {t('returnToCart')}
+        </Link>
+      </div>
+    );
+  }
+
+  const customFieldsStep =
+    customFields.length > 0
+      ? [{ key: 'custom-fields' as CheckoutStep, label: t('stepCustomFields') }]
+      : [];
+
+  const steps: { key: CheckoutStep; label: string }[] = isAllDigital
+    ? [
+        { key: 'address', label: t('stepContactInfo') },
+        ...customFieldsStep,
+        { key: 'payment', label: t('stepPayment') },
+      ]
+    : pickupLocations.length > 0
+      ? deliveryType === 'pickup'
+        ? [
+            { key: 'method', label: t('stepMethod') },
+            { key: 'pickup', label: t('stepPickup') },
+            ...customFieldsStep,
+            { key: 'payment', label: t('stepPayment') },
+          ]
+        : [
+            { key: 'method', label: t('stepMethod') },
+            { key: 'address', label: t('stepAddress') },
+            { key: 'shipping', label: t('stepShipping') },
+            ...customFieldsStep,
+            { key: 'payment', label: t('stepPayment') },
+          ]
+      : [
+          { key: 'address', label: t('stepAddress') },
+          { key: 'shipping', label: t('stepShipping') },
+          ...customFieldsStep,
+          { key: 'payment', label: t('stepPayment') },
+        ];
+
+  const currentStepIndex = steps.findIndex((s) => s.key === step);
+
+  return (
+    <div className="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
+      <h1 className="text-foreground mb-6 text-2xl font-bold">{t('title')}</h1>
+
+      {/* Canceled payment banner */}
+      {canceled && (
+        <div className="mb-6 rounded-lg border border-orange-200 bg-orange-50 px-4 py-3 text-sm text-orange-800 dark:border-orange-800 dark:bg-orange-950/30 dark:text-orange-300">
+          {t('paymentCanceledBanner')}
+        </div>
+      )}
+
+      {/* Reservation countdown. onExpire is what blocks payment below. */}
+      {checkout?.reservation?.hasReservation && (
+        <ReservationCountdown
+          reservation={checkout.reservation}
+          onExpire={handleReservationExpired}
+          className="mb-6"
+        />
+      )}
+
+      {/* Expired reservation: payment is off the table until the cart is
+          reviewed, so say so on every step, not only on the payment step. */}
+      {reservationExpired && (
+        <div className="bg-destructive/10 border-destructive/20 text-destructive mb-6 rounded-lg border px-4 py-3 text-sm">
+          <p>{tr('expiredCheckout')}</p>
+          <Link href="/cart" className="mt-2 inline-flex font-medium underline">
+            {tr('backToCart')}
+          </Link>
+        </div>
+      )}
+
+      {/* Step indicator */}
+      <div className="mb-8 flex items-center gap-2">
+        {steps.map((s, index) => (
+          <div key={s.key} className="flex items-center">
+            {index > 0 && (
+              <div
+                className={cn(
+                  'mx-2 h-px w-8 sm:w-12',
+                  index <= currentStepIndex ? 'bg-primary' : 'bg-border'
+                )}
+              />
+            )}
+            <div className="flex items-center gap-2">
+              <div
+                className={cn(
+                  'flex h-7 w-7 items-center justify-center rounded-full text-xs font-medium',
+                  index < currentStepIndex
+                    ? 'bg-primary text-primary-foreground'
+                    : index === currentStepIndex
+                      ? 'bg-primary text-primary-foreground'
+                      : 'bg-muted text-muted-foreground'
+                )}
+              >
+                {index < currentStepIndex ? (
+                  <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M5 13l4 4L19 7"
+                    />
+                  </svg>
+                ) : (
+                  index + 1
+                )}
+              </div>
+              <span
+                className={cn(
+                  'hidden text-sm sm:block',
+                  index <= currentStepIndex
+                    ? 'text-foreground font-medium'
+                    : 'text-muted-foreground'
+                )}
+              >
+                {s.label}
+              </span>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* Error banner */}
+      {error && checkout && (
+        <div className="bg-destructive/10 border-destructive/20 text-destructive mb-6 rounded-lg border px-4 py-3 text-sm">
+          {error}
+        </div>
+      )}
+
+      <div className="grid grid-cols-1 gap-8 lg:grid-cols-3">
+        {/* Main content */}
+        <div className="lg:col-span-2">
+          {/* Delivery Method */}
+          {step === 'method' && (
+            <div>
+              <h2 className="text-foreground mb-4 text-lg font-semibold">{t('deliveryMethod')}</h2>
+              <DeliveryMethodStep onSelect={handleDeliveryTypeSelect} />
+            </div>
+          )}
+
+          {/* Address */}
+          {step === 'address' && (
+            <div>
+              <div className="mb-4 flex items-center justify-between">
+                <h2 className="text-foreground text-lg font-semibold">
+                  {isAllDigital ? t('contactInfo') : t('shippingAddress')}
+                </h2>
+                {!isAllDigital && pickupLocations.length > 0 && (
+                  <button
+                    type="button"
+                    onClick={() => setStep('method')}
+                    className="text-primary text-sm hover:underline"
+                  >
+                    {t('changeMethod')}
+                  </button>
+                )}
+              </div>
+              <CheckoutForm
+                onSubmit={handleAddressSubmit}
+                loading={loading}
+                destinations={isAllDigital ? null : destinations}
+                showSaveDetails={isLoggedIn && !hasSavedAddress && !isAllDigital}
+                emailOnly={isAllDigital}
+                initialValues={
+                  checkout?.shippingAddress
+                    ? {
+                        email: checkout.email || '',
+                        firstName: checkout.shippingAddress.firstName,
+                        lastName: checkout.shippingAddress.lastName,
+                        line1: checkout.shippingAddress.line1,
+                        line2: checkout.shippingAddress.line2 || '',
+                        city: checkout.shippingAddress.city,
+                        region: checkout.shippingAddress.region || '',
+                        postalCode: checkout.shippingAddress.postalCode,
+                        country: checkout.shippingAddress.country,
+                        phone: checkout.shippingAddress.phone || '',
+                      }
+                    : prefillAddress
+                      ? {
+                          email: prefillAddress.email,
+                          firstName: prefillAddress.firstName,
+                          lastName: prefillAddress.lastName,
+                          line1: prefillAddress.line1,
+                          line2: prefillAddress.line2 || '',
+                          city: prefillAddress.city,
+                          region: prefillAddress.region || '',
+                          postalCode: prefillAddress.postalCode,
+                          country: prefillAddress.country,
+                          phone: prefillAddress.phone || '',
+                        }
+                      : prefillCustomer
+                        ? {
+                            email: prefillCustomer.email,
+                            firstName: prefillCustomer.firstName || '',
+                            lastName: prefillCustomer.lastName || '',
+                            phone: prefillCustomer.phone || '',
+                          }
+                        : undefined
+                }
+              />
+            </div>
+          )}
+
+          {/* Step 2: Shipping */}
+          {step === 'shipping' && (
+            <div>
+              <div className="mb-4 flex items-center justify-between">
+                <h2 className="text-foreground text-lg font-semibold">{t('shippingMethod')}</h2>
+                <button
+                  type="button"
+                  onClick={() => setStep('address')}
+                  className="text-primary text-sm hover:underline"
+                >
+                  {t('editAddress')}
+                </button>
+              </div>
+
+              <ShippingStep
+                rates={shippingRates}
+                selectedRateId={selectedRateId}
+                onSelect={handleShippingSelect}
+                loading={loading}
+              />
+            </div>
+          )}
+
+          {/* Pickup */}
+          {step === 'pickup' && (
+            <div>
+              <div className="mb-4 flex items-center justify-between">
+                <h2 className="text-foreground text-lg font-semibold">{t('pickupLocation')}</h2>
+                <button
+                  type="button"
+                  onClick={() => setStep('method')}
+                  className="text-primary text-sm hover:underline"
+                >
+                  {t('changeMethod')}
+                </button>
+              </div>
+              <PickupStep
+                locations={pickupLocations}
+                onSelect={handlePickupSelect}
+                loading={loading}
+                initialEmail={checkout?.email || ''}
+              />
+            </div>
+          )}
+
+          {/* Custom Fields (optional, between shipping/pickup and payment) */}
+          {step === 'custom-fields' && checkout && (
+            <div>
+              <div className="mb-4 flex items-center justify-between">
+                <h2 className="text-foreground text-lg font-semibold">{t('customFieldsTitle')}</h2>
+                <button
+                  type="button"
+                  onClick={() => setStep(deliveryType === 'pickup' ? 'pickup' : 'shipping')}
+                  className="text-primary text-sm hover:underline"
+                >
+                  {deliveryType === 'pickup' ? t('changePickup') : t('changeShipping')}
+                </button>
+              </div>
+              <CustomFieldsStep
+                fields={customFields}
+                values={customFieldValues}
+                onChange={(key, value) =>
+                  setCustomFieldValues((prev) => ({ ...prev, [key]: value }))
+                }
+                onApply={handleCustomFieldsApply}
+                onUploadFile={(file) => getClient().uploadCustomizationFile(file)}
+                timezone={storeInfo?.timezone}
+                loading={customFieldsLoading}
+              />
+            </div>
+          )}
+
+          {/* Payment */}
+          {step === 'payment' && checkout && (
+            <div>
+              <div className="mb-4 flex items-center justify-between">
+                <h2 className="text-foreground text-lg font-semibold">{t('payment')}</h2>
+                {customFields.length > 0 ? (
+                  <button
+                    type="button"
+                    onClick={() => setStep('custom-fields')}
+                    className="text-primary text-sm hover:underline"
+                  >
+                    {t('changeOptions')}
+                  </button>
+                ) : (
+                  !isAllDigital && (
+                    <button
+                      type="button"
+                      onClick={() => setStep(deliveryType === 'pickup' ? 'pickup' : 'shipping')}
+                      className="text-primary text-sm hover:underline"
+                    >
+                      {deliveryType === 'pickup' ? t('changePickup') : t('changeShipping')}
+                    </button>
+                  )
+                )}
+              </div>
+
+              {/* Never mount the payment form on an expired reservation: the
+                  stock behind these lines is back on sale, so a charge here
+                  can take money for something that cannot ship. */}
+              {reservationExpired ? (
+                <div className="border-border rounded-lg border px-4 py-6 text-center">
+                  <p className="text-foreground text-sm font-medium">{tr('expired')}</p>
+                  <p className="text-muted-foreground mt-1 text-sm">{tr('expiredCheckout')}</p>
+                  <Link
+                    href="/cart"
+                    className="bg-primary text-primary-foreground mt-4 inline-flex items-center rounded px-6 py-3 text-sm font-medium transition-opacity hover:opacity-90"
+                  >
+                    {tr('backToCart')}
+                  </Link>
+                </div>
+              ) : isFullyCovered ? (
+                /* Nothing left for a provider to charge.
+                   Gift cards can cover an order completely, and demanding a
+                   card for 0.00 is not a formality — most providers reject a
+                   zero-amount charge outright, so the shopper is stuck holding
+                   a paid-for order they cannot place. The backend already
+                   derives this server-side (`isZeroDue`) and completes without
+                   a payment, so the only thing missing was a way to ask. */
+                <div className="border-border rounded-lg border px-4 py-6">
+                  <p className="text-foreground text-sm font-medium">{t('fullyCovered')}</p>
+                  <p className="text-muted-foreground mt-1 text-sm">
+                    {t('fullyCoveredHint')}
+                  </p>
+                  {placeError && (
+                    <p role="alert" className="text-destructive mt-3 text-sm">
+                      {placeError}
+                    </p>
+                  )}
+                  <button
+                    type="button"
+                    onClick={handlePlaceFreeOrder}
+                    disabled={placing}
+                    className="bg-primary text-primary-foreground mt-4 inline-flex items-center rounded px-6 py-3 text-sm font-medium transition-opacity hover:opacity-90 disabled:opacity-50"
+                  >
+                    {placing ? t('placing') : t('placeOrder')}
+                  </button>
+                </div>
+              ) : (
+                <PaymentStep checkoutId={checkout.id} />
+              )}
+            </div>
+          )}
+        </div>
+
+        {/* Order summary sidebar */}
+        <div className="lg:col-span-1">
+          <div className="bg-muted/50 border-border sticky top-24 rounded-lg border p-6">
+            <h3 className="text-foreground mb-4 text-lg font-semibold">{t('orderSummary')}</h3>
+
+            {/* Line items */}
+            {checkout?.lineItems && checkout.lineItems.length > 0 ? (
+              <div className="mb-4 space-y-3">
+                {checkout.lineItems.map((item) => {
+                  const imageUrl = item.product.images?.[0]?.url || null;
+                  const name = item.variant?.name || item.product.name;
+                  const lineTotal = parseFloat(item.unitPrice) * item.quantity;
+
+                  return (
+                    <div key={item.id} className="space-y-1">
+                      <div className="flex gap-3">
+                        <div className="bg-muted relative h-12 w-12 flex-shrink-0 overflow-hidden rounded">
+                          {imageUrl ? (
+                            <Image
+                              src={imageUrl}
+                              alt={name}
+                              fill
+                              sizes="48px"
+                              className="object-cover"
+                            />
+                          ) : (
+                            <div className="text-muted-foreground absolute inset-0 flex items-center justify-center">
+                              <svg
+                                className="h-5 w-5"
+                                fill="none"
+                                viewBox="0 0 24 24"
+                                stroke="currentColor"
+                              >
+                                <path
+                                  strokeLinecap="round"
+                                  strokeLinejoin="round"
+                                  strokeWidth={1.5}
+                                  d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
+                                />
+                              </svg>
+                            </div>
+                          )}
+                        </div>
+
+                        <div className="min-w-0 flex-1">
+                          <p className="text-foreground truncate text-sm">{name}</p>
+                          <p className="text-muted-foreground text-xs">
+                            {tc('qty')} {item.quantity}
+                          </p>
+                        </div>
+
+                        <span className="text-foreground flex-shrink-0 text-sm font-medium">
+                          {formatPrice(lineTotal, { currency }) as string}
+                        </span>
+                      </div>
+
+                      {/* The buyer's own input on this line — engraving text,
+                          uploaded photo, picked colour — so it can be checked
+                          before paying. `CheckoutLineItem.customizations` is
+                          the SDK's resolved label/value/type map, absent on a
+                          line with no customization, so a plain order renders
+                          exactly as before. */}
+                      {item.customizations && (
+                        <OrderCustomizations customizations={item.customizations} />
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            ) : (
+              // Fallback to cart items if checkout line items aren't loaded yet
+              cart && (
+                <div className="mb-4 space-y-2">
+                  <p className="text-muted-foreground text-sm">
+                    {cart.items.length} {cart.items.length === 1 ? tc('item') : tc('items')}
+                  </p>
+                </div>
+              )
+            )}
+
+            {/* Order bumps */}
+            {orderBumps?.bumps && orderBumps.bumps.length > 0 && (
+              <div className="border-border space-y-2 border-t pt-4">
+                <p className="text-foreground text-xs font-semibold uppercase tracking-wide">
+                  {t('addToYourOrder')}
+                </p>
+                {orderBumps.bumps.map((bump) => (
+                  <OrderBumpCard
+                    key={bump.id}
+                    bump={bump}
+                    isAdded={addedBumpIds.has(bump.id)}
+                    onToggle={handleBumpToggle}
+                    loading={bumpLoading === bump.id}
+                  />
+                ))}
+              </div>
+            )}
+
+            {/* Coupon input — show from shipping/pickup step onwards (or immediately if digital) */}
+            {cart &&
+              (isAllDigital || step === 'shipping' || step === 'pickup' || step === 'payment') && (
+                <div className="border-border border-t pt-4">
+                  <CouponInput
+                    cart={cart}
+                    checkoutId={checkout?.id}
+                    onUpdate={handleCouponUpdate}
+                  />
+                  {/* Beside the coupon field, and deliberately NOT inside it. A
+                      coupon reduces what the order is worth; a gift card pays
+                      for an order still worth the same. They look adjacent
+                      because a shopper reaches for them at the same moment, and
+                      they behave differently because they are different things. */}
+                  {checkout?.id && (
+                    <GiftCardInput
+                      className="mt-3"
+                      checkoutId={checkout.id}
+                      tenders={checkout.tenders ?? []}
+                      formatAmount={(value) =>
+                        formatPrice(parseFloat(value), { currency }) as string
+                      }
+                      onUpdate={handleCouponUpdate}
+                    />
+                  )}
+                </div>
+              )}
+
+            {/* Totals */}
+            {checkout &&
+              (() => {
+                // When the store prices include tax (VAT-style), the on-row
+                // `checkout.subtotal` is GROSS — it already contains the tax.
+                // Show the net (tax-excluded) value here, then a separate VAT
+                // line below, so the customer sees the breakdown the merchant
+                // asked for. Falls back to the raw subtotal when no breakdown
+                // is available yet (e.g. shipping address not entered).
+                const isInclusive = checkout.taxBreakdown?.pricesIncludeTax === true;
+                // `taxBreakdown.subtotal` is the NET of every taxed line, and
+                // shipping is one of those lines — so it already contains the
+                // shipping net. Rendering it and then adding `shippingAmount`
+                // below counts shipping twice: a real checkout read
+                // 54.06 + 9.99 + 7.93 = 71.98 beside a 61.99 total, three rows
+                // that visibly refuse to add up next to the figure being charged.
+                //
+                // Subtract the shipping net back out so the column reconciles.
+                // The shipping row keeps showing the GROSS amount, which is what
+                // a shopper recognises from the rate they picked.
+                // `shippingNet` comes from the server, never from
+                // `shippingAmount` minus a guess: subtracting the GROSS is only
+                // correct when shipping is untaxed, and a store that taxes
+                // shipping would silently show a short subtotal.
+                const shippingNet =
+                  typeof checkout.taxBreakdown?.shippingNet === 'number'
+                    ? checkout.taxBreakdown.shippingNet
+                    : parseFloat(checkout.shippingAmount) || 0;
+                const displayedSubtotal =
+                  isInclusive && typeof checkout.taxBreakdown?.subtotal === 'number'
+                    ? checkout.taxBreakdown.subtotal - shippingNet
+                    : parseFloat(checkout.subtotal);
+                const subtotalLabel = isInclusive ? tc('subtotalExclTax') : tc('subtotal');
+                return (
+                  <div className="border-border space-y-2 border-t pt-4 text-sm">
+                    <div className="flex items-center justify-between">
+                      <span className="text-muted-foreground">{subtotalLabel}</span>
+                      <span className="text-foreground">
+                        {formatPrice(displayedSubtotal, { currency }) as string}
+                      </span>
+                    </div>
+
+                    {(() => {
+                      const totalDiscount = parseFloat(checkout.discountAmount);
+                      const ruleAmt = parseFloat(checkout.ruleDiscountAmount || '0');
+                      const couponAmt = totalDiscount - ruleAmt;
+                      const rules = cart?.appliedDiscounts;
+                      if (totalDiscount <= 0) return null;
+                      return (
+                        <>
+                          {rules && rules.length > 0
+                            ? rules.map((rule) => (
+                                <div
+                                  key={rule.ruleId}
+                                  className="flex items-center justify-between"
+                                >
+                                  <span className="text-muted-foreground">{rule.ruleName}</span>
+                                  <span className="text-destructive">
+                                    -
+                                    {
+                                      formatPrice(parseFloat(rule.discountAmount), {
+                                        currency,
+                                      }) as string
+                                    }
+                                  </span>
+                                </div>
+                              ))
+                            : ruleAmt > 0 && (
+                                <div className="flex items-center justify-between">
+                                  <span className="text-muted-foreground">
+                                    {tc('generalDiscount')}
+                                  </span>
+                                  <span className="text-destructive">
+                                    -{formatPrice(ruleAmt, { currency }) as string}
+                                  </span>
+                                </div>
+                              )}
+                          {checkout.couponCode && couponAmt > 0 && (
+                            <div className="flex items-center justify-between">
+                              <span className="text-muted-foreground">
+                                {tc('couponDiscount')} ({checkout.couponCode})
+                              </span>
+                              <span className="text-destructive">
+                                -{formatPrice(couponAmt, { currency }) as string}
+                              </span>
+                            </div>
+                          )}
+                          {!checkout.couponCode &&
+                            ruleAmt <= 0 &&
+                            (!rules || rules.length === 0) && (
+                              <div className="flex items-center justify-between">
+                                <span className="text-muted-foreground">{tc('discount')}</span>
+                                <span className="text-destructive">
+                                  -{formatPrice(totalDiscount, { currency }) as string}
+                                </span>
+                              </div>
+                            )}
+                        </>
+                      );
+                    })()}
+
+                    {(parseFloat(checkout.shippingAmount) > 0 ||
+                      checkout.deliveryType === 'pickup') && (
+                      <div className="flex items-center justify-between">
+                        <span className="text-muted-foreground">
+                          {checkout.deliveryType === 'pickup' ? tc('pickup') : tc('shipping')}
+                        </span>
+                        <span className="text-foreground">
+                          {parseFloat(checkout.shippingAmount) === 0
+                            ? tc('free')
+                            : (formatPrice(parseFloat(checkout.shippingAmount), {
+                                currency,
+                              }) as string)}
+                        </span>
+                      </div>
+                    )}
+
+                    <TaxDisplay
+                      addressSet={!!checkout.shippingAddress}
+                      taxAmount={checkout.taxAmount}
+                      taxBreakdown={checkout.taxBreakdown}
+                    />
+
+                    {/* Custom field surcharges (one line per applied surcharge) */}
+                    {checkout.appliedSurcharges && checkout.appliedSurcharges.length > 0 && (
+                      <>
+                        {checkout.appliedSurcharges.map((s) => (
+                          <div key={s.key} className="flex items-center justify-between">
+                            <span className="text-muted-foreground">{s.name}</span>
+                            <span className="text-foreground">
+                              {formatPrice(Number(s.amount), { currency }) as string}
+                            </span>
+                          </div>
+                        ))}
+                      </>
+                    )}
+
+                    <div className="border-border mt-2 border-t pt-2">
+                      <div className="flex items-center justify-between">
+                        <span className="text-foreground font-semibold">{tc('total')}</span>
+                        <span className="text-foreground text-base font-semibold">
+                          {formatPrice(parseFloat(checkout.total), { currency }) as string}
+                        </span>
+                      </div>
+
+                      {/* Gift cards sit BELOW the total, not among the discounts
+                          above it. The total is what the order is worth and does
+                          not move; what changes is only what the card leaves for
+                          the payment provider to charge. Putting this in the
+                          discount block would understate the taxable base to the
+                          shopper and on the receipt. */}
+                      {checkout.tenders && checkout.tenders.length > 0 && (
+                        <>
+                          {checkout.tenders.map((tender) => (
+                            <div
+                              key={tender.tenderId}
+                              className="mt-2 flex items-center justify-between text-sm"
+                            >
+                              <span className="text-muted-foreground">{tc('giftCard')}</span>
+                              <span className="text-primary">
+                                -
+                                {
+                                  formatPrice(parseFloat(tender.amountApplied), {
+                                    currency,
+                                  }) as string
+                                }
+                              </span>
+                            </div>
+                          ))}
+                          <div className="border-border mt-2 flex items-center justify-between border-t pt-2">
+                            <span className="text-foreground font-semibold">{tc('amountDue')}</span>
+                            <span className="text-foreground text-base font-semibold">
+                              {
+                                formatPrice(parseFloat(checkout.providerAmountDue ?? checkout.total), {
+                                  currency,
+                                }) as string
+                              }
+                            </span>
+                          </div>
+                        </>
+                      )}
+                    </div>
+                  </div>
+                );
+              })()}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function CheckoutPage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="flex min-h-[60vh] items-center justify-center">
+          <LoadingSpinner size="lg" />
+        </div>
+      }
+    >
+      <CheckoutContent />
+    </Suspense>
+  );
+}