@cartbase/storefront 0.1.0

package/src/checkout/use-checkout-orchestration.ts

@@ -0,0 +1,1504 @@
+"use client"
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+} from "react"
+
+import type { StorefrontClient } from "../api/http"
+import {
+  completeCart,
+  updateCart,
+  type Cart,
+  type CartAddress,
+  type CompletedOrder,
+  type UpdateCartInput,
+} from "../api/carts"
+import {
+  calculateShippingOption,
+  prepareCheckout,
+  refreshPaymentIfTerminal as refreshPaymentIfTerminalApi,
+  syncPaymentAmount as syncPaymentAmountApi,
+  type PrepareCheckoutInput,
+  type RefreshPaymentResult,
+  type StorePaymentProvider,
+  type StoreShippingOption,
+  type SyncPaymentAmountResult,
+} from "../api/checkout"
+import {
+  updateMe,
+  type CustomerAddress,
+  type StoreCustomer,
+  type UpdateCustomerInput,
+} from "../api/customers"
+import type { PublicCodConfig } from "../api/integrations"
+import { isManual, isStripeLike } from "../lib/payment-constants"
+import compareAddresses from "./compare-addresses"
+import { translateAddressError } from "./address-error-copy"
+import { translatePaymentError } from "./payment-error-copy"
+import { useOrderConfirmedPath } from "./context"
+import type { EcontOffice } from "./econt-office-selector"
+import type { BoxNowLocker } from "../api/integrations"
+
+/**
+ * useCheckoutOrchestration — single source of truth for checkout-page
+ * orchestration. All race-condition guards, payment-session lifecycle,
+ * shipping/address mutations, carrier metadata, completed-cart detection
+ * and 3DS-return handling live here. Library's CheckoutClient and any
+ * store's custom orchestration component consume this hook — they own only
+ * the layout and any store-specific concerns (tracking, sessionStorage form
+ * persistence, custom summary).
+ *
+ * Ported from `@1click/ui/src/checkout/use-checkout-orchestration.ts`
+ * (v2.3.1, the deferred-intent architecture) with the barter data seam:
+ *
+ *  - Server actions → `@cartbase/storefront/api` calls on a caller-supplied
+ *    `StorefrontClient` (`updateCart`, `prepareCheckout`,
+ *    `syncPaymentAmount`, `refreshPaymentIfTerminal`, `completeCart`,
+ *    `calculateShippingOption`, `updateMe`).
+ *  - `placeOrder` (server action with baked-in redirect) →
+ *    `completeCart()` + template navigation (`orderConfirmedPath` with
+ *    `{id}`/`{country}` substitution) or the `onOrderPlaced` callback.
+ *  - **Zero-remainder gift path** (barter gift-card tender,
+ *    docs/storefront/checkout.md): when applied gift cards cover the whole
+ *    total, `prepareCheckout` returns `client_secret: null` +
+ *    `provider_id: null` and the card path SKIPS `stripe.confirmPayment`
+ *    entirely — the cart completes on the gift session alone. The @1click
+ *    original threw on a missing client_secret; barter treats
+ *    null-secret + null-provider as the documented gift path.
+ *  - COD fee: barter's fee is CART-LEVEL decoration (`cod_fee_total` /
+ *    `cod_fee_label`, folded into `cart.total` while a live pp_cod session
+ *    exists) — not a metadata-flagged line item. The optimistic-fee math
+ *    reads `cart.cod_fee_total`; the prediction comes from the
+ *    integrations config `cod` block (never hardcoded).
+ *  - Provider ids: `pp_stripe` / `pp_cod` / `pp_manual` exactly
+ *    (lib/payment-constants + the pp_cod resolution below).
+ *  - `logCheckoutError`/`logEvent` (Supabase-side sinks in @1click) have no
+ *    barter store endpoint — the hook takes an optional `logError` callback
+ *    so stores wire their own sink; all production log points are kept.
+ *  - Barter regions carry NO embedded countries array (api/regions.ts
+ *    divergence note) — the country list is a `countries` option with a
+ *    `countryCode` single-entry fallback.
+ *
+ * Why a hook and not a base component:
+ *   - Stores fork the layout for legitimate reasons (tracking, custom
+ *     summary). They should NOT have to fork the orchestration logic too —
+ *     that's how a fork DROPPED the session guard + syncPaymentAmount flow
+ *     during the v1.15 → v1.16 cycle, producing zombie Stripe sessions on
+ *     rapid payment-tab toggles. Centralizing the logic here makes that
+ *     class of fork-rot bug structurally impossible.
+ */
+
+/** COD checkout config — the integrations `cod` block (api/integrations). */
+export type CheckoutCodConfig = PublicCodConfig | null
+
+/** Minimal provider row the hook accepts (SDK DTO or bare `{id}`). */
+export type PaymentProviderLike = StorePaymentProvider | { id: string }
+
+export type CheckoutLogError = (
+  errorType: string,
+  message: string,
+  context?: Record<string, unknown>
+) => void
+
+export type UseCheckoutOrchestrationOptions = {
+  /** The SDK transport — all server calls go through it. */
+  client: StorefrontClient
+  cart: Cart
+  customer: StoreCustomer | null
+  availableShippingMethods: StoreShippingOption[] | null
+  availablePaymentMethods: PaymentProviderLike[] | null
+  /** Default country code when the cart has no shipping address yet. */
+  countryCode?: string
+  /**
+   * Countries offered in the address form. Barter regions do NOT embed a
+   * countries array (store-API divergence), so the host app supplies the
+   * list; omitted → a single entry derived from `countryCode`.
+   */
+  countries?: Array<{ iso_2: string; display_name: string }>
+  /**
+   * Per-store rule for filtering payment methods based on the currently
+   * selected shipping option (e.g. hide COD when BoxNow is selected).
+   */
+  paymentMethodFilter?: (
+    methods: PaymentProviderLike[] | null,
+    selectedShippingOption: StoreShippingOption | null
+  ) => PaymentProviderLike[] | null
+  /**
+   * Optional cash-on-delivery configuration — pass the integrations config
+   * `cod` block (`getIntegrationsConfig(client).cod`). When present, the
+   * hook paints `optimisticCodFee` on tab-toggle so the totals row updates
+   * before the server-side fee (applied at prepare) arrives.
+   */
+  codConfig?: CheckoutCodConfig
+  /**
+   * Order-confirmed redirect path template (`{id}` → order.id,
+   * `{country}` → shipping country). Falls back to the CheckoutProvider
+   * context value.
+   */
+  orderConfirmedPath?: string
+  /**
+   * Called after a successful complete INSTEAD of the default
+   * `window.location.assign` navigation — stores using next/navigation
+   * router push their own way.
+   */
+  onOrderPlaced?: (order: CompletedOrder) => void
+  /**
+   * Tracking-attribution metadata written into `cart.metadata` right
+   * before complete (consent-gated by the CALLER — pass undefined when
+   * consent denies). Use `getTrackingAttribution()` from
+   * `@cartbase/storefront/tracking` + engagement time. Cart completion
+   * copies cart.metadata to order.metadata so the backend `order.placed`
+   * forwarder inherits fbp/fbc/ga signals (docs/storefront/
+   * integrations.md).
+   */
+  resolveTrackingMetadata?: () => Record<string, unknown> | undefined
+  /**
+   * Operational-visibility sink (successor of @1click's logCheckoutError /
+   * logEvent Supabase writers — barter has no store-side log endpoint).
+   * Called with (errorType, message, context). Optional; defaults to no-op.
+   */
+  logError?: CheckoutLogError
+}
+
+/**
+ * Address form fields the orchestration tracks. Matches the keys the
+ * library's `CheckoutAddressForm` writes via `name=...`.
+ *
+ * `shipping_address.phone` is required — Bulgarian carriers (Econt,
+ * BoxNow) need it to contact the customer; it's the courier's primary
+ * recovery channel when the address is ambiguous. (Barter's
+ * prepare-checkout schema requires it too — docs/storefront/checkout.md.)
+ */
+const REQUIRED_ADDRESS_FIELDS = [
+  "email",
+  "shipping_address.country_code",
+  "shipping_address.first_name",
+  "shipping_address.last_name",
+  "shipping_address.address_1",
+  "shipping_address.city",
+  "shipping_address.postal_code",
+  "shipping_address.phone",
+] as const
+
+/**
+ * Debounce window for the auto-save effect — long enough that a user
+ * typing through fields without blurring triggers ONE save at the end,
+ * short enough that clicking a shipping option after the last keystroke
+ * doesn't race the persistence (the pre-action `flushAddressSave` is
+ * the belt-and-braces backstop for that race).
+ */
+const ADDRESS_AUTO_SAVE_DEBOUNCE_MS = 600
+
+/** Barter COD provider resolution: `pp_cod` exactly, with the Medusa-era
+ * `pp_system_default*` prefix kept as fallback (lib/payment-constants),
+ * and `pp_manual` accepted as the offline tab when no true COD provider
+ * is enabled. Fee prediction only ever applies via `codConfig` (pp_cod). */
+const isCodLikeId = (id?: string): boolean =>
+  !!id && (id === "pp_cod" || isManual(id))
+
+/**
+ * Snapshot the address-relevant subset of formData. Used to skip
+ * redundant saves: if the snapshot matches what was last persisted,
+ * there's nothing to do. JSON-stringify keeps comparison cheap and
+ * correct (string keys + string values, no nested objects).
+ */
+function snapshotAddressForm(
+  formData: Record<string, string>,
+  sameAsBilling: boolean
+): string {
+  return JSON.stringify({
+    email: formData.email ?? "",
+    first_name: formData["shipping_address.first_name"] ?? "",
+    last_name: formData["shipping_address.last_name"] ?? "",
+    address_1: formData["shipping_address.address_1"] ?? "",
+    company: formData["shipping_address.company"] ?? "",
+    postal_code: formData["shipping_address.postal_code"] ?? "",
+    city: formData["shipping_address.city"] ?? "",
+    country_code: formData["shipping_address.country_code"] ?? "",
+    province: formData["shipping_address.province"] ?? "",
+    phone: formData["shipping_address.phone"] ?? "",
+    company_name: formData.company_name ?? "",
+    company_vat: formData.company_vat ?? "",
+    company_mol: formData.company_mol ?? "",
+    company_address: formData.company_address ?? "",
+    sameAsBilling,
+  })
+}
+
+/** Resolve the confirmed-order path template. Pure — unit-tested. */
+export function resolveOrderConfirmedPath(
+  template: string,
+  order: { id: string },
+  countryCode?: string | null
+): string {
+  return template
+    .replace("{id}", order.id)
+    .replace("{country}", (countryCode ?? "").toLowerCase())
+}
+
+export function useCheckoutOrchestration({
+  client,
+  cart,
+  customer,
+  availableShippingMethods,
+  availablePaymentMethods,
+  countryCode = "",
+  countries,
+  paymentMethodFilter,
+  codConfig,
+  orderConfirmedPath: orderConfirmedPathProp,
+  onOrderPlaced,
+  resolveTrackingMetadata,
+  logError,
+}: UseCheckoutOrchestrationOptions) {
+  // Resolve the order-confirmed path. Prop wins; otherwise fall back to
+  // the value provided by CheckoutProvider context.
+  const contextOrderConfirmedPath = useOrderConfirmedPath()
+  const orderConfirmedPath =
+    orderConfirmedPathProp ?? contextOrderConfirmedPath
+
+  // ── Completed-cart detection ────────────────────────────────────────
+  // Surfaced as a flag so the page-level server component can redirect
+  // before any client-side mutation runs. The cart cookie can outlive a
+  // completed checkout (back button after order, second tab on the same
+  // session) and the storefront previously rendered the full form on
+  // top — leading to a second complete attempt that returns a raw
+  // English error.
+  const cartIsCompleted = useMemo(
+    () => Boolean(cart?.completed_at),
+    [cart]
+  )
+
+  // ── Address form ────────────────────────────────────────────────────
+  const [addressError, setAddressError] = useState<string | null>(null)
+  const [, setAddressSaving] = useState(false)
+  const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // In-flight guard against concurrent saveAddress calls. Without this,
+  // rapid blur events (email → tab → phone → tab) queue parallel
+  // updateCart writes; the later-resolving one wins, and any field the
+  // user edited between the two clicks gets reverted to the earlier
+  // snapshot.
+  const addressSavingRef = useRef(false)
+  // Snapshot of the formData that was last successfully persisted.
+  // Used to skip redundant saves and to detect when the user changed
+  // form fields while a save was in flight (so we re-fire after).
+  const lastSavedSnapshotRef = useRef<string>("")
+  // When a save is in flight and formData changes, we set this to the
+  // latest snapshot. The in-flight save's `finally` checks it and
+  // re-fires saveAddress so the latest form state always wins.
+  const pendingSnapshotRef = useRef<string | null>(null)
+
+  const [formData, setFormData] = useState<Record<string, string>>(() => ({
+    "shipping_address.first_name":
+      cart?.shipping_address?.first_name || customer?.first_name || "",
+    "shipping_address.last_name":
+      cart?.shipping_address?.last_name || customer?.last_name || "",
+    "shipping_address.address_1": cart?.shipping_address?.address_1 || "",
+    "shipping_address.company": cart?.shipping_address?.company || "",
+    "shipping_address.postal_code": cart?.shipping_address?.postal_code || "",
+    "shipping_address.city": cart?.shipping_address?.city || "",
+    "shipping_address.country_code":
+      cart?.shipping_address?.country_code || countryCode || "",
+    "shipping_address.province": cart?.shipping_address?.province || "",
+    "shipping_address.phone": cart?.shipping_address?.phone || "",
+    email: cart?.email || customer?.email || "",
+    company_name: (cart?.metadata?.company_name as string) || "",
+    company_vat: (cart?.metadata?.company_vat as string) || "",
+    company_mol: (cart?.metadata?.company_mol as string) || "",
+    company_address: (cart?.metadata?.company_address as string) || "",
+  }))
+
+  const [sameAsBilling] = useState(
+    cart?.shipping_address && cart?.billing_address
+      ? compareAddresses(
+          cart.shipping_address as unknown as Record<string, unknown>,
+          cart.billing_address as unknown as Record<string, unknown>
+        )
+      : true
+  )
+
+  // Barter regions have no embedded countries — the caller-supplied list
+  // (or the countryCode fallback) is the authority for both the select
+  // options and the saved-address region filter.
+  const regionCountries = useMemo(
+    () =>
+      countries && countries.length
+        ? countries
+        : countryCode
+          ? [{ iso_2: countryCode, display_name: "" }]
+          : [],
+    [countries, countryCode]
+  )
+
+  const countriesInRegion = useMemo(
+    () => regionCountries.map((c) => c.iso_2).filter(Boolean),
+    [regionCountries]
+  )
+
+  const addressesInRegion = useMemo(
+    () =>
+      customer?.addresses?.filter(
+        (a) =>
+          !countriesInRegion.length ||
+          (a.country_code && countriesInRegion.includes(a.country_code))
+      ),
+    [customer?.addresses, countriesInRegion]
+  )
+
+  const setFormAddress = useCallback(
+    (
+      address?: Partial<CartAddress> | Partial<CustomerAddress>,
+      email?: string
+    ) => {
+      if (address) {
+        setFormData((prev) => ({
+          ...prev,
+          "shipping_address.first_name": address.first_name || "",
+          "shipping_address.last_name": address.last_name || "",
+          "shipping_address.address_1": address.address_1 || "",
+          "shipping_address.company": address.company || "",
+          "shipping_address.postal_code": address.postal_code || "",
+          "shipping_address.city": address.city || "",
+          "shipping_address.country_code": address.country_code || "",
+          "shipping_address.province": address.province || "",
+          "shipping_address.phone": address.phone || "",
+        }))
+      }
+      if (email) setFormData((prev) => ({ ...prev, email }))
+    },
+    []
+  )
+
+  // Re-seed formData from cart when it changes id (e.g. region switch
+  // creates a fresh cart). Disabled within the same cart id so user's
+  // in-progress edits aren't clobbered by a refresh after a
+  // shipping/payment mutation.
+  useEffect(() => {
+    if (cart?.shipping_address)
+      setFormAddress(cart.shipping_address, cart.email ?? undefined)
+    if (cart && !cart.email && customer?.email)
+      setFormAddress(undefined, customer.email)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [cart?.id])
+
+  const allRequiredFilled = REQUIRED_ADDRESS_FIELDS.every(
+    (f) => (formData[f] ?? "").trim().length > 0
+  )
+
+  // ── 3-second idle attention cue ────────────────────────────────────
+  // After 3 seconds of no typing/focus activity AND not all required
+  // fields filled, flag the empty required fields with a soft-blue
+  // pulse so the customer knows where to look. Production UX fix
+  // (2026-05-06) after a real customer reported being stuck on the
+  // shipping section without realising one address field was empty.
+  //
+  // Color: sky-500 (in the Field primitive). Distinct from focus
+  // (orange/primary) and error (red/destructive).
+  // Threshold: 3s of no formData change. Resets per-field (a field
+  // unflags itself the moment it becomes non-empty).
+  // First load: yes — we want stuck customers to see the cue
+  // immediately, not only after they've already tried to interact.
+  const PULSE_IDLE_MS = 3000
+  const [pulseFields, setPulseFields] = useState<Set<string>>(new Set())
+  useEffect(() => {
+    if (allRequiredFilled) {
+      if (pulseFields.size > 0) setPulseFields(new Set())
+      return
+    }
+    const timer = setTimeout(() => {
+      const empty = REQUIRED_ADDRESS_FIELDS.filter(
+        (f) => !((formData[f] ?? "").trim().length > 0)
+      )
+      setPulseFields(new Set(empty))
+    }, PULSE_IDLE_MS)
+    return () => clearTimeout(timer)
+    // We intentionally depend on the FULL formData object so any
+    // keystroke / saved-address selection / blur-driven update resets
+    // the timer. allRequiredFilled is also tracked so the cue clears
+    // the moment the last empty required field gets a value.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [formData, allRequiredFilled])
+
+  // First-render seed of lastSavedSnapshotRef. When a returning user
+  // lands on /checkout with a cart that already has email + shipping
+  // address persisted server-side, formData initializes from the cart
+  // and matches what's already saved. Without this seed, the auto-save
+  // effect sees ref="" (not yet seeded) vs a populated snapshot and
+  // schedules a redundant `updateCart` 600ms after mount — delaying the
+  // Place Order button render by a full round-trip on every reload.
+  //
+  // Guard with `cart?.email && cart?.shipping_address?.first_name` so
+  // we only seed when the cart genuinely has the data persisted; a
+  // half-populated cart leaves ref="" so the user's first save fires
+  // normally.
+  const snapshotSeededRef = useRef(false)
+  if (
+    !snapshotSeededRef.current &&
+    allRequiredFilled &&
+    cart?.email &&
+    cart?.shipping_address?.first_name
+  ) {
+    snapshotSeededRef.current = true
+    lastSavedSnapshotRef.current = snapshotAddressForm(formData, sameAsBilling)
+  }
+
+  const saveAddress = useCallback(async () => {
+    if (!allRequiredFilled) return
+    const snapshot = snapshotAddressForm(formData, sameAsBilling)
+    // Skip redundant saves — if the form hasn't changed since last
+    // successful persist, don't re-hit the network. Critical for the
+    // debounced auto-save: every formData change triggers the effect,
+    // but only meaningful changes should reach the server.
+    if (snapshot === lastSavedSnapshotRef.current) return
+    // If a save is already in flight, register this snapshot as
+    // pending. The in-flight save's `finally` will re-fire saveAddress
+    // so the latest form state always wins. Without this, formData
+    // edits that happen during a save get silently dropped.
+    if (addressSavingRef.current) {
+      pendingSnapshotRef.current = snapshot
+      return
+    }
+    addressSavingRef.current = true
+    setAddressSaving(true)
+    setAddressError(null)
+    try {
+      const shippingAddress = {
+        first_name: formData["shipping_address.first_name"],
+        last_name: formData["shipping_address.last_name"],
+        address_1: formData["shipping_address.address_1"],
+        address_2: "",
+        company: formData["shipping_address.company"] || "",
+        postal_code: formData["shipping_address.postal_code"],
+        city: formData["shipping_address.city"],
+        country_code: formData["shipping_address.country_code"],
+        province: formData["shipping_address.province"] || "",
+        phone: formData["shipping_address.phone"] || "",
+      }
+      const addressData: UpdateCartInput = {
+        shipping_address: shippingAddress,
+        email: formData.email,
+      }
+      if (sameAsBilling) addressData.billing_address = shippingAddress
+
+      const hasCompany = formData.company_name?.trim()
+      if (hasCompany) {
+        addressData.metadata = {
+          ...(cart?.metadata ?? {}),
+          company_name: formData.company_name,
+          company_vat: formData.company_vat || "",
+          company_mol: formData.company_mol || "",
+          company_address: formData.company_address || "",
+        }
+      }
+
+      await updateCart(client, cart.id, addressData)
+      lastSavedSnapshotRef.current = snapshot
+
+      if (customer) {
+        // Sync the profile best-effort. Barter has first-class company
+        // fields on the customer (company_name / company_eik —
+        // api/customers.ts), so the invoice data also lands on the
+        // profile — an upgrade over the @1click cart-metadata-only
+        // storage (its KNOWN_ISSUES entry).
+        const patch: UpdateCustomerInput = {
+          first_name: formData["shipping_address.first_name"],
+          last_name: formData["shipping_address.last_name"],
+          phone: formData["shipping_address.phone"] || undefined,
+        }
+        if (hasCompany) {
+          patch.company_name = formData.company_name
+          if (formData.company_vat) patch.company_eik = formData.company_vat
+        }
+        updateMe(client, patch).catch(() => {})
+      }
+    } catch (e: unknown) {
+      // ── Visibility ─────────────────────────────────────────────────
+      // Without this log point, address-save failures are completely
+      // silent operationally. PII discipline: log only structured/
+      // non-PII fields (country_code, postal_code, flags). No names,
+      // email, phone, address line, or company VAT/MOL.
+      const errObj = e instanceof Error ? e : null
+      logError?.(
+        "address_save_failed",
+        errObj?.message ?? String(e),
+        {
+          err_name: errObj?.name ?? null,
+          err_code:
+            (e as { code?: string } | null)?.code ?? null,
+          err_status:
+            (e as { status?: number } | null)?.status ?? null,
+          cart_id: cart?.id,
+          customer_id: customer?.id,
+          all_required_filled: allRequiredFilled,
+          same_as_billing: sameAsBilling,
+          has_company: Boolean(formData.company_name?.trim()),
+          country_code: formData["shipping_address.country_code"] || null,
+          postal_code: formData["shipping_address.postal_code"] || null,
+        }
+      )
+      // Translate to Bulgarian — the raw error.message is technical
+      // English (or a validation envelope). Neither is acceptable to
+      // show a Bulgarian shopper at the moment of failure. Unknown
+      // errors get the generic fallback rather than half-translated
+      // text.
+      setAddressError(translateAddressError(errObj ?? e))
+    } finally {
+      setAddressSaving(false)
+      addressSavingRef.current = false
+      // If formData changed during the save, fire again with the
+      // latest state. Loops at most once per real user edit because
+      // the snapshot guard skips duplicates.
+      const pending = pendingSnapshotRef.current
+      pendingSnapshotRef.current = null
+      if (pending && pending !== lastSavedSnapshotRef.current) {
+        void saveAddressRef.current?.()
+      }
+    }
+  }, [
+    client,
+    formData,
+    allRequiredFilled,
+    sameAsBilling,
+    customer,
+    cart?.id,
+    cart?.metadata,
+    logError,
+  ])
+
+  // Self-reference for the post-save re-fire path. Captured via ref so
+  // the callback can call the latest version of itself without making
+  // useCallback's dep list circular.
+  const saveAddressRef = useRef(saveAddress)
+  useEffect(() => {
+    saveAddressRef.current = saveAddress
+  }, [saveAddress])
+
+  // ── Auto-save effect ───────────────────────────────────────────────
+  // The single source of truth for "form data → server cart" sync.
+  // Watches formData and fires saveAddress after a debounce window.
+  // This is what makes the persistence robust to:
+  //   - Browser autofill (1Password, Bitwarden, Chrome) which can fill
+  //     multiple fields without firing per-field blur events
+  //   - sessionStorage form restore on mount
+  //   - Programmatic / paste-driven fills with no blur
+  //   - Saved-customer-address selection (setFormAddress)
+  //
+  // Before this effect, persistence relied on `handleFieldBlur` —
+  // which made the cart silently empty whenever the form got filled
+  // by a non-blur path. That's the bug that left cart.email NULL on
+  // anonymous carts and kept the Place Order button disabled even
+  // when the form looked complete.
+  //
+  // `handleFieldBlur` is preserved as the immediate-save shortcut so
+  // the typical typing path doesn't wait for the debounce.
+  useEffect(() => {
+    if (!allRequiredFilled) return
+    const snapshot = snapshotAddressForm(formData, sameAsBilling)
+    if (snapshot === lastSavedSnapshotRef.current) return
+    if (saveTimerRef.current) clearTimeout(saveTimerRef.current)
+    saveTimerRef.current = setTimeout(() => {
+      saveTimerRef.current = null
+      void saveAddress()
+    }, ADDRESS_AUTO_SAVE_DEBOUNCE_MS)
+    return () => {
+      if (saveTimerRef.current) {
+        clearTimeout(saveTimerRef.current)
+        saveTimerRef.current = null
+      }
+    }
+  }, [formData, allRequiredFilled, sameAsBilling, saveAddress])
+
+  // flushAddressSave — used by shipping/payment selection handlers to
+  // guarantee the latest form state is persisted BEFORE a state-
+  // advancing mutation runs. Cancels any pending debounce and awaits
+  // the save synchronously. Without this, a fast user (clicks Econt
+  // < 600ms after their last keystroke) advances on a stale cart.
+  const flushAddressSave = useCallback(async () => {
+    if (saveTimerRef.current) {
+      clearTimeout(saveTimerRef.current)
+      saveTimerRef.current = null
+    }
+    if (!allRequiredFilled) return
+    await saveAddress()
+  }, [allRequiredFilled, saveAddress])
+
+  const handleFormChange = useCallback(
+    (e: ChangeEvent<HTMLInputElement | HTMLSelectElement>) => {
+      const updated = { ...formData, [e.target.name]: e.target.value }
+      setFormData(updated)
+
+      // For selects (country), save immediately on change since there's
+      // no blur. Reads from `updated` (not `formData`) so the post-set
+      // value is what gets validated and persisted.
+      if (e.target.tagName === "SELECT") {
+        const filled = REQUIRED_ADDRESS_FIELDS.every(
+          (f) => (updated[f] ?? "").trim().length > 0
+        )
+        if (filled) saveAddress()
+      }
+    },
+    [formData, saveAddress]
+  )
+
+  const handleFieldBlur = useCallback(() => {
+    if (allRequiredFilled) saveAddress()
+  }, [allRequiredFilled, saveAddress])
+
+  const addressReady =
+    allRequiredFilled || !!(cart?.shipping_address && cart?.email)
+
+  const addressInput = useMemo(
+    () =>
+      ({
+        first_name: formData["shipping_address.first_name"],
+        last_name: formData["shipping_address.last_name"],
+        address_1: formData["shipping_address.address_1"],
+        company: formData["shipping_address.company"],
+        postal_code: formData["shipping_address.postal_code"],
+        city: formData["shipping_address.city"],
+        country_code: formData["shipping_address.country_code"],
+        province: formData["shipping_address.province"],
+        phone: formData["shipping_address.phone"],
+      }) as Record<string, string>,
+    [formData]
+  )
+
+  // ── Shipping ────────────────────────────────────────────────────────
+  const [shippingLoading] = useState(false)
+  const [shippingError, setShippingError] = useState<string | null>(null)
+  const [optimisticShippingCost, setOptimisticShippingCost] = useState<
+    number | null
+  >(null)
+  const [selectedShippingMethod, setSelectedShippingMethod] = useState<
+    string | null
+  >(cart?.shipping_methods?.at(-1)?.shipping_option_id || null)
+
+  const shippingMethods = useMemo(
+    () =>
+      (availableShippingMethods ?? []).filter(
+        (sm) =>
+          (sm as { service_zone?: { fulfillment_set?: { type?: string } } })
+            .service_zone?.fulfillment_set?.type !== "pickup"
+      ),
+    [availableShippingMethods]
+  )
+
+  const selectedShippingOption = useMemo(
+    () =>
+      shippingMethods.find((sm) => sm.id === selectedShippingMethod) ?? null,
+    [shippingMethods, selectedShippingMethod]
+  )
+
+  const effectiveAvailablePaymentMethods = useMemo(
+    () =>
+      paymentMethodFilter
+        ? paymentMethodFilter(availablePaymentMethods, selectedShippingOption)
+        : availablePaymentMethods,
+    [paymentMethodFilter, availablePaymentMethods, selectedShippingOption]
+  )
+
+  // Calculated-rate price resolution. Barter serves flat prices today
+  // (`price_type: "flat"` always — api/checkout.ts), so this effect
+  // normally resolves immediately; the calculated branch is kept for
+  // forward-compat with calculated-rate carriers (the /calculate route
+  // already exists).
+  const [calculatedPricesMap, setCalculatedPricesMap] = useState<
+    Record<string, number>
+  >({})
+  const [isLoadingPrices, setIsLoadingPrices] = useState(true)
+
+  useEffect(() => {
+    if (!shippingMethods.length) {
+      setIsLoadingPrices(false)
+      return
+    }
+    setIsLoadingPrices(true)
+    const calculated = shippingMethods.filter(
+      (sm) => (sm.price_type as string) === "calculated"
+    )
+    if (!calculated.length) {
+      setIsLoadingPrices(false)
+      return
+    }
+    Promise.allSettled(
+      calculated.map((sm) =>
+        calculateShippingOption(client, sm.id, { cart_id: cart.id })
+      )
+    ).then((res) => {
+      const map: Record<string, number> = {}
+      res.forEach((p) => {
+        if (p.status === "fulfilled" && p.value?.shipping_option)
+          map[p.value.shipping_option.id ?? ""] =
+            p.value.shipping_option.amount ?? 0
+      })
+      setCalculatedPricesMap(map)
+      setIsLoadingPrices(false)
+    })
+  }, [availableShippingMethods, cart.id, shippingMethods, client])
+
+  // ── Carrier metadata ────────────────────────────────────────────────
+  // Carrier metadata is held in client state ONLY and written to the cart
+  // exactly once at Buy click via prepareCheckout's `carrier_metadata`.
+  // No eager updateCart on selection — that path was the source of the
+  // office-vs-direct-address and BoxNow-vs-Econt mismatched-data bugs.
+  // Server-side, prepare-checkout removes the PREVIOUS prepare's carrier
+  // keys before merging (the `_prepared_carrier_keys` marker), so
+  // switching carriers can never leak stale fields into the order.
+  const [selectedEcontOffice, setSelectedEcontOffice] =
+    useState<EcontOffice | null>(
+      cart?.metadata?.econt_office_code
+        ? ({
+            code: cart.metadata.econt_office_code as string,
+            name: cart.metadata.econt_office_name as string,
+          } as EcontOffice)
+        : null
+    )
+
+  const handleSelectEcontOffice = useCallback(
+    (office: EcontOffice | null) => {
+      setSelectedEcontOffice(office)
+    },
+    []
+  )
+
+  const [selectedBoxnowLocker, setSelectedBoxnowLocker] =
+    useState<BoxNowLocker | null>(
+      cart?.metadata?.boxnow_locker_id
+        ? ({
+            id: cart.metadata.boxnow_locker_id as string,
+            title: (cart.metadata.boxnow_locker_title as string) ?? "",
+            addressLine1:
+              (cart.metadata.boxnow_locker_address as string) ?? "",
+            addressLine2: "",
+            postalCode: (cart.metadata.boxnow_locker_postal as string) ?? "",
+            country: "",
+            lat: null,
+            lng: null,
+            note: "",
+          } as BoxNowLocker)
+        : null
+    )
+
+  const handleSelectBoxnowLocker = useCallback(
+    (locker: BoxNowLocker | null) => {
+      setSelectedBoxnowLocker(locker)
+    },
+    []
+  )
+
+  // ── Payment ─────────────────────────────────────────────────────────
+  const [paymentError, setPaymentError] = useState<string | null>(null)
+
+  const hasCard = !!effectiveAvailablePaymentMethods?.some((m) =>
+    isStripeLike(m.id)
+  )
+  const hasCod = !!effectiveAvailablePaymentMethods?.some(
+    (m) => isCodLikeId(m.id) || m.id === "pp_manual"
+  )
+  const cardId = effectiveAvailablePaymentMethods?.find((m) =>
+    isStripeLike(m.id)
+  )?.id
+  // Prefer the true COD provider; fall back to pp_manual so single-
+  // provider stores still get an offline tab.
+  const codId =
+    effectiveAvailablePaymentMethods?.find((m) => isCodLikeId(m.id))?.id ??
+    effectiveAvailablePaymentMethods?.find((m) => m.id === "pp_manual")?.id
+
+  // Default tab: card when available, else COD. The eager-session model
+  // used to seed from the cart's pending session provider; in the
+  // deferred-intent model there is no session at mount.
+  const [paymentTab, setPaymentTab] = useState<"card" | "cod">(
+    hasCard ? "card" : "cod"
+  )
+
+  // Optimistic COD-fee state. Painted instantly on tab toggle so the
+  // totals row shows the predicted fee BEFORE the server applies the
+  // native fee (barter: at prepare, when the pp_cod session is minted).
+  // Three values:
+  //   - null         → no prediction; render whatever the cart says
+  //   - 0            → predict no fee (toggling away from COD)
+  //   - positive     → predict the fee at this amount (toggling to COD)
+  const [optimisticCodFee, setOptimisticCodFee] = useState<number | null>(
+    null
+  )
+
+  // Payment tab selection is client state only pre-Buy. No payment
+  // session is created until Buy click — this eliminates the entire
+  // class of session-rotation / amount-drift / iframe-remount bugs
+  // caused by the old eager-session model. AFTER a prepare (failed Buy
+  // retry state) a pending session may exist — the best-effort sync
+  // below rotates it to the newly picked provider per the
+  // sync-payment-amount matrix (docs/storefront/checkout.md);
+  // pre-Buy it no-ops with `no_payment_collection`.
+  const handlePaymentTab = useCallback(
+    (tab: "card" | "cod") => {
+      setPaymentTab(tab)
+      setPaymentError(null)
+
+      // Optimistic COD-fee prediction so the totals row updates instantly.
+      // Currency must match the configured fee currency or the backend
+      // skips the fee at apply time, so we mirror that gate here. The
+      // prediction ONLY applies when the offline tab is the true pp_cod
+      // provider — pp_manual carries no fee.
+      if (codConfig) {
+        const codCurrencyMatches =
+          codConfig.fee_currency.toLowerCase() ===
+          (cart.currency_code || "").toLowerCase()
+        if (tab === "cod" && codCurrencyMatches && codId === "pp_cod") {
+          setOptimisticCodFee(codConfig.fee_amount)
+        } else {
+          setOptimisticCodFee(0)
+        }
+      }
+
+      const provider = tab === "card" ? cardId : codId
+      if (provider) {
+        void syncPaymentAmountApi(client, cart.id, {
+          provider_id: provider,
+        }).catch(() => {})
+      }
+    },
+    [cart.currency_code, cart.id, client, codConfig, cardId, codId]
+  )
+
+  // Shipping selection is client state only. No addShippingMethod call,
+  // no metadata-clear updateCart — all of those wrote to the cart
+  // between toggles and produced the stale-data bug class. The shipping
+  // method ID is sent to the backend exactly once at Buy click via
+  // prepareCheckout.
+  const handleSelectShipping = useCallback(
+    (id: string) => {
+      setShippingError(null)
+      setSelectedShippingMethod(id)
+
+      // Optimistic shipping cost — paint the totals row immediately so
+      // the customer sees the right number before any network call.
+      const option = shippingMethods.find((m) => m.id === id)
+      if (option) {
+        const price =
+          option.price_type === "flat"
+            ? option.amount
+            : calculatedPricesMap[option.id]
+        if (price !== undefined && price !== null)
+          setOptimisticShippingCost(price)
+      }
+
+      // Switching shipping invalidates any previously-selected carrier-
+      // specific destination (e.g. picking direct address after BoxNow
+      // locker). All client state — no eager metadata-clear updateCart.
+      setSelectedBoxnowLocker(null)
+      setSelectedEcontOffice(null)
+    },
+    [shippingMethods, calculatedPricesMap]
+  )
+
+  // ── Delivery readiness ──────────────────────────────────────────────
+  const selectedFulfillmentOptionId = useMemo(() => {
+    const data = selectedShippingOption?.data as
+      | { id?: string }
+      | undefined
+      | null
+    return typeof data?.id === "string" ? data.id : null
+  }, [selectedShippingOption])
+  const selectedIsBoxnow = selectedFulfillmentOptionId === "boxnow-locker"
+  const selectedIsEcont = selectedFulfillmentOptionId === "econt-office"
+
+  // Defensive: trust cart.metadata for locker/office IDs in addition to
+  // local React state. On mobile the BoxNow locker selector was seen
+  // firing its onSelect handler in a way that updated cart.metadata
+  // cleanly but left the local `selectedBoxnowLocker` stale (touch event
+  // timing / hydration race). Without this fallback, the local-null kept
+  // `deliveryReady` false and the entire payment section turned into a
+  // ghost — even though the cart server-side knew the locker was set.
+  const hasBoxnowLockerInCart = !!cart?.metadata?.boxnow_locker_id
+  const hasEcontOfficeInCart = !!cart?.metadata?.econt_office_code
+
+  const deliveryReady =
+    (!!selectedShippingMethod ||
+      (cart?.shipping_methods?.length ?? 0) > 0) &&
+    (!selectedIsBoxnow || !!selectedBoxnowLocker || hasBoxnowLockerInCart) &&
+    (!selectedIsEcont || !!selectedEcontOffice || hasEcontOfficeInCart)
+
+  // Reconcile paymentTab with currently-available methods. When the
+  // store's paymentMethodFilter strips a method in response to a shipping
+  // change (e.g. BoxNow → no COD), the previously selected tab can point
+  // to a method that's no longer rendered — leaving the remaining tab's
+  // radio looking unselected and the form collapsed.
+  useEffect(() => {
+    if (!deliveryReady) return
+    if (paymentTab === "cod" && !hasCod && hasCard) {
+      handlePaymentTab("card")
+    } else if (paymentTab === "card" && !hasCard && hasCod) {
+      handlePaymentTab("cod")
+    }
+  }, [deliveryReady, paymentTab, hasCard, hasCod, handlePaymentTab])
+
+  const handlePaymentElementChange = useCallback(
+    (_e: { complete: boolean; selectedMethod: string | null }) => {
+      setPaymentError(null)
+    },
+    []
+  )
+
+  // ── Place order (complete + navigate) ───────────────────────────────
+  // Successor of @1click's placeOrder server action: write tracking
+  // attribution into cart.metadata (consent-gated by the caller), then
+  // POST /complete via the SDK, then navigate to the confirmed page (or
+  // hand the order to `onOrderPlaced`).
+  const placeOrder = useCallback(async (): Promise<CompletedOrder> => {
+    const trackingMeta = resolveTrackingMetadata?.()
+    if (trackingMeta && Object.keys(trackingMeta).length > 0) {
+      // Best-effort — a failed attribution write must never block the
+      // order. Cart completion copies cart.metadata → order.metadata,
+      // which the backend order.placed forwarder reads.
+      await updateCart(client, cart.id, {
+        metadata: { ...(cart.metadata ?? {}), ...trackingMeta },
+      }).catch(() => {})
+    }
+
+    const { order } = await completeCart(client, cart.id)
+
+    if (onOrderPlaced) {
+      onOrderPlaced(order)
+    } else if (typeof window !== "undefined") {
+      window.location.assign(
+        resolveOrderConfirmedPath(
+          orderConfirmedPath,
+          order,
+          formData["shipping_address.country_code"]
+        )
+      )
+    }
+    return order
+  }, [
+    client,
+    cart.id,
+    cart.metadata,
+    onOrderPlaced,
+    orderConfirmedPath,
+    resolveTrackingMetadata,
+    formData,
+  ])
+
+  // ── Amount sync + dead-PI recovery (SDK-wrapped, exposed) ───────────
+  // syncPaymentAmount: call after anything that changes the total while
+  // a pending session exists (gift-card apply/remove, quantity change,
+  // shipping switch post-prepare). Happy path keeps the SAME
+  // client_secret so <Elements> never remounts.
+  const syncPaymentAmount = useCallback(
+    (providerId?: string): Promise<SyncPaymentAmountResult> =>
+      syncPaymentAmountApi(
+        client,
+        cart.id,
+        providerId ? { provider_id: providerId } : {}
+      ),
+    [client, cart.id]
+  )
+
+  // refreshPaymentIfTerminal: REACTIVE dead-PI recovery — call from
+  // Stripe Elements `loaderror` or on page mount for aged carts, never
+  // proactively per render (the proactive variant caused a production
+  // reload loop; transient Stripe errors deliberately refuse to rotate).
+  const refreshPaymentIfTerminal = useCallback(
+    (): Promise<RefreshPaymentResult> =>
+      refreshPaymentIfTerminalApi(client, cart.id),
+    [client, cart.id]
+  )
+
+  // ── 3DS / bank-redirect return handler ──────────────────────────────
+  // Stripe confirmPayment with redirect: "if_required" navigates to
+  // return_url ONLY when the method demands it (3DS challenge, bank-
+  // redirect APMs). On return the browser carries
+  //   ?payment_intent=...&redirect_status=succeeded|...
+  //
+  // In the deferred-intent flow, the PaymentIntent was created at Buy
+  // click via prepareCheckout; the cart already has a pending session
+  // pointing at that PI. After 3DS succeeds the PI is in
+  // requires_capture / succeeded — complete can authorize. We just
+  // call placeOrder (= POST /complete).
+  //
+  // Strips query params before async work so a refresh / re-render
+  // doesn't re-trigger this effect.
+  const threeDSHandledRef = useRef(false)
+  useEffect(() => {
+    if (typeof window === "undefined") return
+    if (threeDSHandledRef.current) return
+
+    const url = new URL(window.location.href)
+    const redirectStatus = url.searchParams.get("redirect_status")
+    const paymentIntentId = url.searchParams.get("payment_intent")
+    if (!redirectStatus || !paymentIntentId) return
+
+    threeDSHandledRef.current = true
+
+    ;[
+      "redirect_status",
+      "payment_intent",
+      "payment_intent_client_secret",
+    ].forEach((k) => url.searchParams.delete(k))
+    window.history.replaceState({}, "", url.toString())
+
+    if (redirectStatus === "succeeded") {
+      placeOrder().catch((err: unknown) => {
+        const translated = translatePaymentError(err, "card")
+        setPaymentError(translated)
+        logError?.(
+          "place_order_error",
+          err instanceof Error ? err.message : String(err),
+          {
+            via: "3ds_return",
+            cartId: cart.id,
+            paymentIntentId,
+          }
+        )
+      })
+    } else {
+      setPaymentError(
+        "Плащането не беше потвърдено. Моля, опитайте отново или изберете друг метод."
+      )
+      logError?.("place_order_error", "redirect_not_succeeded", {
+        via: "3ds_return",
+        cartId: cart.id,
+        paymentIntentId,
+        redirectStatus,
+      })
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const summaryCart = cart
+
+  // ── Optimistic total (display, EUR major units) ─────────────────────
+  // Single source of truth for "what total to show on every checkout
+  // surface that previously read cart.total" — order summary, Place
+  // Order button.
+  //
+  // Why this exists. The deferred-checkout architecture made cart.total
+  // stale until Buy click: shipping & COD fee are now client state, not
+  // written to the cart pre-Buy. Surfaces reading cart.total raw drift
+  // visibly. This memo applies the compensating math once, hoisted so
+  // every consumer shares one formula.
+  //
+  // Formula:
+  //   start = cart.total (covers subtotal + tax + any already-written
+  //                       shipping/fee)
+  //   if optimisticShippingCost set: replace cart.shipping_total with it
+  //   if optimisticCodFee set: replace cart.cod_fee_total with it
+  //     (barter: the COD fee is CART-LEVEL decoration folded into total,
+  //      not a fee line item)
+  // When nothing is optimistic, this collapses to cart.total.
+  const optimisticTotal = useMemo(() => {
+    const realCodFeeAmount = cart?.cod_fee_total ?? 0
+    let total = cart?.total ?? 0
+    if (optimisticShippingCost !== null) {
+      total = total - (cart?.shipping_total ?? 0) + optimisticShippingCost
+    }
+    if (optimisticCodFee !== null && optimisticCodFee !== undefined) {
+      total = total - realCodFeeAmount + optimisticCodFee
+    }
+    return total
+  }, [
+    cart?.total,
+    cart?.shipping_total,
+    cart?.cod_fee_total,
+    optimisticShippingCost,
+    optimisticCodFee,
+  ])
+
+  // ── Optimistic total in cents (for Stripe Elements deferred-intent) ─
+  // Stripe's deferred-intent <Elements> needs `amount` + `currency` at
+  // mount time (no PaymentIntent on the backend yet). Same value as
+  // `optimisticTotal` above, just in the smallest currency unit and
+  // floor-clamped to Stripe's minimum charge. Round to protect against
+  // float drift in optimistic deltas. (Store-API money is EUR major
+  // units — minor-unit conversion happens ONLY at this Stripe display
+  // boundary; the charged amount is always the server's.)
+  const optimisticTotalCents = useMemo(
+    () => Math.max(50, Math.round(optimisticTotal * 100)),
+    [optimisticTotal]
+  )
+
+  // ── Buy-click payload builder ───────────────────────────────────────
+  // Constructs the prepareCheckout request body from current client
+  // state. Called by PaymentButton on click.
+  const buildPrepareCheckoutPayload =
+    useCallback((): PrepareCheckoutInput => {
+      const carrierMetadata: Record<string, unknown> = {}
+      if (selectedEcontOffice) {
+        const addr = [
+          selectedEcontOffice.address?.street,
+          selectedEcontOffice.address?.num,
+        ]
+          .filter(Boolean)
+          .join(" ")
+        carrierMetadata.econt_office_code = selectedEcontOffice.code
+        carrierMetadata.econt_office_name = selectedEcontOffice.name
+        carrierMetadata.econt_office_city =
+          selectedEcontOffice.address?.city?.name || ""
+        carrierMetadata.econt_office_address = addr
+        carrierMetadata.econt_office_phone =
+          selectedEcontOffice.phones?.[0] || ""
+      }
+      if (selectedBoxnowLocker) {
+        carrierMetadata.boxnow_locker_id = selectedBoxnowLocker.id
+        carrierMetadata.boxnow_locker_title = selectedBoxnowLocker.title
+        carrierMetadata.boxnow_locker_address =
+          selectedBoxnowLocker.addressLine1 ?? ""
+        carrierMetadata.boxnow_locker_postal =
+          selectedBoxnowLocker.postalCode ?? ""
+      }
+
+      const shippingMethodId = selectedShippingMethod
+      if (!shippingMethodId) {
+        throw new Error("No shipping method selected")
+      }
+      const paymentProvider = paymentTab === "card" ? cardId : codId
+      if (!paymentProvider) {
+        throw new Error("No payment provider available")
+      }
+
+      return {
+        shipping_address: {
+          first_name: formData["shipping_address.first_name"] ?? "",
+          last_name: formData["shipping_address.last_name"] ?? "",
+          address_1: formData["shipping_address.address_1"] ?? "",
+          address_2: "",
+          city: formData["shipping_address.city"] ?? "",
+          postal_code: formData["shipping_address.postal_code"] ?? "",
+          country_code: formData["shipping_address.country_code"] ?? "",
+          phone: formData["shipping_address.phone"] ?? "",
+        },
+        shipping_method_id: shippingMethodId,
+        carrier_metadata: carrierMetadata,
+        payment_provider: paymentProvider,
+      }
+    }, [
+      formData,
+      selectedShippingMethod,
+      selectedEcontOffice,
+      selectedBoxnowLocker,
+      paymentTab,
+      cardId,
+      codId,
+    ])
+
+  // ── Buy click ───────────────────────────────────────────────────────
+  // Single source of truth for the Buy-click flow. Called by PaymentButton.
+  // Steps:
+  //   1. Flush any pending address auto-save (so the server has the
+  //      latest email/name/phone for tracking + abandoned-cart).
+  //   2. (Card path) elements.submit() — validates the form inside the
+  //      Stripe iframe before any server call.
+  //   3. POST /api/store/carts/:id/prepare-checkout — ONE atomic,
+  //      compensated write of address + shipping + carrier metadata +
+  //      payment collection + session at the FINAL amount.
+  //   4. (Card path) stripe.confirmPayment(elements, clientSecret) —
+  //      attaches the payment method and confirms. On 3DS this redirects
+  //      and we resume in the threeDSHandledRef effect. SKIPPED entirely
+  //      on the zero-remainder gift path (client_secret === null &&
+  //      provider_id === null — gift cards cover the whole total).
+  //   5. placeOrder() (POST /complete) — authorize passes because the PI
+  //      is now in requires_capture / succeeded (or the gift session
+  //      covers everything).
+  type BuyClickStripe = {
+    submit: () => Promise<{ error?: { message?: string } | null }>
+    stripe: {
+      confirmPayment: (args: {
+        elements: unknown
+        clientSecret: string
+        confirmParams: { return_url: string }
+        redirect: "if_required"
+      }) => Promise<{ error?: { message?: string } | null }>
+    }
+    elements: unknown
+  }
+
+  const performBuyClick = useCallback(
+    async (stripeBundle?: BuyClickStripe): Promise<void> => {
+      setPaymentError(null)
+
+      // STATE-AT-CLICK SNAPSHOT — logs the EXACT state the storefront sees
+      // when the customer clicks Buy. Diagnostic-only; no PII beyond
+      // what's already in the order.
+      const stateSnapshot = {
+        cart_id: cart.id,
+        paymentTab,
+        cardId,
+        codId,
+        selectedShippingMethod,
+        selectedEcontOffice: selectedEcontOffice
+          ? { code: selectedEcontOffice.code, name: selectedEcontOffice.name }
+          : null,
+        selectedBoxnowLocker: selectedBoxnowLocker
+          ? {
+              id: selectedBoxnowLocker.id,
+              title: selectedBoxnowLocker.title,
+            }
+          : null,
+        hasStripeBundle: !!stripeBundle,
+      }
+      // eslint-disable-next-line no-console
+      console.log("[buy-click] STATE", stateSnapshot)
+      logError?.("other", "buy_click_state", stateSnapshot)
+
+      await flushAddressSave()
+
+      if (paymentTab === "card") {
+        if (!stripeBundle) {
+          // eslint-disable-next-line no-console
+          console.error("[buy-click] card path but no stripe bundle")
+          throw new Error("Stripe not ready")
+        }
+        // eslint-disable-next-line no-console
+        console.log("[buy-click] elements.submit() …")
+        const { error: submitError } = await stripeBundle.submit()
+        if (submitError) {
+          // eslint-disable-next-line no-console
+          console.error("[buy-click] elements.submit() error", submitError)
+          throw submitError
+        }
+      }
+
+      const payload = buildPrepareCheckoutPayload()
+      // eslint-disable-next-line no-console
+      console.log("[buy-click] PAYLOAD →", payload)
+      logError?.("other", "buy_click_payload", {
+        provider_id: payload.payment_provider,
+        shipping_method_id: payload.shipping_method_id,
+        carrier_metadata_keys: Object.keys(payload.carrier_metadata ?? {}),
+        country_code: payload.shipping_address.country_code,
+      })
+
+      const prep = await prepareCheckout(client, cart.id, payload).catch(
+        (e: unknown) => {
+          // eslint-disable-next-line no-console
+          console.error("[buy-click] prepareCheckout threw", e)
+          throw e
+        }
+      )
+      // eslint-disable-next-line no-console
+      console.log("[buy-click] prepareCheckout response", {
+        has_client_secret: !!prep.client_secret,
+        provider_id: prep.provider_id,
+      })
+
+      // ── Zero-remainder gift path (barter gift-card tender) ──────────
+      // When applied gift cards cover the whole total, prepare skips the
+      // provider session: client_secret AND provider_id come back null
+      // and the cart completes on the internal pp_giftcard session alone
+      // — no Stripe involved (docs/storefront/checkout.md +
+      // gift-cards.md). Detect it BEFORE the card branch so a card-tab
+      // Buy click on a fully-covered cart doesn't demand a secret.
+      const zeroRemainderGiftPath =
+        prep.client_secret === null && prep.provider_id === null
+
+      if (paymentTab === "card" && !zeroRemainderGiftPath) {
+        if (!stripeBundle || !prep.client_secret) {
+          // eslint-disable-next-line no-console
+          console.error(
+            "[buy-click] card path missing client_secret",
+            { has_bundle: !!stripeBundle, has_secret: !!prep.client_secret }
+          )
+          throw new Error("Stripe client_secret missing after prepare")
+        }
+        const returnUrl =
+          typeof window !== "undefined" ? window.location.href : ""
+
+        // billing_details — passed for AVS / Radar / 3DS risk scoring /
+        // dispute defense. PaymentElement is NO LONGER mounted with
+        // fields.billingDetails.address = "never" (see payment-method-
+        // list.tsx) — that flag put Stripe into strict-completeness mode
+        // and threw IntegrationError on the first missing sub-field
+        // (country → state → next), which is what blocked card payments
+        // on 2026-05-06. Without it, Stripe accepts whatever billing
+        // details we provide and falls back to its iframe-collected data
+        // for anything missing. We still pass full billing_details here
+        // because the data improves auth rates regardless.
+        //
+        // `null` (not `undefined`) for empty fields — explicit null is
+        // robust against any future Stripe SDK reintroducing presence
+        // checks; undefined would read as "missing".
+        const firstName = formData["shipping_address.first_name"] ?? ""
+        const lastName = formData["shipping_address.last_name"] ?? ""
+        const fullName = `${firstName} ${lastName}`.trim()
+        const billingDetails = {
+          name: fullName || null,
+          email: formData.email || null,
+          phone: formData["shipping_address.phone"] || null,
+          address: {
+            line1: formData["shipping_address.address_1"] || null,
+            line2: null,
+            city: formData["shipping_address.city"] || null,
+            state: formData["shipping_address.province"] || null,
+            postal_code: formData["shipping_address.postal_code"] || null,
+            // ISO 3166-1 alpha-2, uppercase per Stripe convention.
+            country:
+              formData["shipping_address.country_code"]?.toUpperCase() || null,
+          },
+        }
+
+        // eslint-disable-next-line no-console
+        console.log("[buy-click] stripe.confirmPayment() …", {
+          has_country: !!billingDetails.address.country,
+        })
+        const { error } = await (stripeBundle.stripe as unknown as {
+          confirmPayment: (args: unknown) => Promise<{ error?: unknown }>
+        }).confirmPayment({
+          elements: stripeBundle.elements,
+          clientSecret: prep.client_secret,
+          confirmParams: {
+            return_url: returnUrl,
+            payment_method_data: {
+              billing_details: billingDetails,
+            },
+          },
+          redirect: "if_required",
+        })
+        if (error) {
+          const stripeErr = error as {
+            type?: string
+            code?: string
+            decline_code?: string
+            message?: string
+            payment_intent?: { id?: string; status?: string }
+          }
+          // eslint-disable-next-line no-console
+          console.error("[buy-click] stripe.confirmPayment error", stripeErr)
+          // Log so the actual Stripe error code + message is readable
+          // without needing the customer's browser console.
+          logError?.(
+            "stripe_confirm_error",
+            stripeErr.message ?? "unknown",
+            {
+              type: stripeErr.type,
+              code: stripeErr.code,
+              decline_code: stripeErr.decline_code,
+              pi_id: stripeErr.payment_intent?.id,
+              pi_status: stripeErr.payment_intent?.status,
+              cart_id: cart.id,
+              client_secret_prefix: prep.client_secret.slice(0, 8),
+            }
+          )
+          throw error
+        }
+        // confirmPayment succeeded synchronously (no redirect needed,
+        // e.g. non-3DS card flow). The PaymentIntent is now in
+        // requires_capture or succeeded — complete will pass authorize.
+        // eslint-disable-next-line no-console
+        console.log("[buy-click] stripe.confirmPayment SUCCESS (no redirect)")
+        logError?.("stripe_confirm_succeeded", "ok", {
+          cart_id: cart.id,
+          client_secret_prefix: prep.client_secret.slice(0, 8),
+        })
+      } else if (zeroRemainderGiftPath) {
+        // eslint-disable-next-line no-console
+        console.log(
+          "[buy-click] zero-remainder gift path — skipping Stripe, completing on the gift session"
+        )
+        logError?.("other", "zero_remainder_gift_path", { cart_id: cart.id })
+      }
+
+      // eslint-disable-next-line no-console
+      console.log("[buy-click] placeOrder() …")
+      logError?.("order_placed", "called", {
+        cart_id: cart.id,
+        path: paymentTab,
+      })
+      await placeOrder().catch((e: unknown) => {
+        // eslint-disable-next-line no-console
+        console.error("[buy-click] placeOrder threw", e)
+        throw e
+      })
+    },
+    [
+      client,
+      cart.id,
+      paymentTab,
+      cardId,
+      codId,
+      selectedShippingMethod,
+      selectedEcontOffice,
+      selectedBoxnowLocker,
+      flushAddressSave,
+      buildPrepareCheckoutPayload,
+      placeOrder,
+      formData,
+      logError,
+    ]
+  )
+
+  return {
+    // Completed-cart guard
+    cartIsCompleted,
+
+    // Address form
+    formData,
+    setFormData,
+    addressError,
+    addressReady,
+    allRequiredFilled,
+    setFormAddress,
+    handleFormChange,
+    handleFieldBlur,
+    addressInput,
+    regionCountries,
+    addressesInRegion,
+    saveAddress,
+    flushAddressSave,
+    pulseFields,
+
+    // Shipping
+    shippingMethods,
+    calculatedPricesMap,
+    isLoadingPrices,
+    selectedShippingMethod,
+    selectedShippingOption,
+    selectedFulfillmentOptionId,
+    selectedIsBoxnow,
+    selectedIsEcont,
+    shippingLoading,
+    shippingError,
+    optimisticShippingCost,
+    setOptimisticShippingCost,
+    handleSelectShipping,
+
+    // Carriers
+    selectedEcontOffice,
+    handleSelectEcontOffice,
+    selectedBoxnowLocker,
+    handleSelectBoxnowLocker,
+
+    // Payment
+    paymentTab,
+    hasCard,
+    hasCod,
+    cardId,
+    codId,
+    paymentError,
+    setPaymentError,
+    deliveryReady,
+    optimisticCodFee,
+    setOptimisticCodFee,
+    handlePaymentTab,
+    handlePaymentElementChange,
+
+    // Amount sync + recovery (SDK-wrapped)
+    syncPaymentAmount,
+    refreshPaymentIfTerminal,
+
+    // Buy click (deferred-intent flow)
+    optimisticTotal,
+    optimisticTotalCents,
+    buildPrepareCheckoutPayload,
+    performBuyClick,
+    placeOrder,
+
+    // Misc
+    summaryCart,
+  }
+}