@cartbase/storefront 0.17.0 → 0.18.0

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

@@ -1,1592 +1,1592 @@
-"use client"
-
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type ChangeEvent,
-} from "react"
-
-import type { StorefrontClient } from "../api/http"
-import { countryName } from "../lib/country-name"
-import { listCountries, type StoreCountry } from "../api/regions"
-import {
-  completeCart,
-  updateCart,
-  type Cart,
-  type CartAddress,
-  type CompletedOrder,
-  type UpdateCartInput,
-} from "../api/carts"
-import {
-  calculateShippingOption,
-  prepareCheckout,
-  refreshPaymentIfTerminal as refreshPaymentIfTerminalApi,
-  reportCheckoutError,
-  syncPaymentAmount as syncPaymentAmountApi,
-  isMethodEntry,
-  type PrepareCheckoutInput,
-  type RefreshPaymentResult,
-  type StorePaymentEntry,
-  type StorePaymentMethodEntry,
-  type StoreShippingOption,
-  type SyncPaymentAmountResult,
-} from "../api/checkout"
-import {
-  updateMe,
-  type CustomerAddress,
-  type StoreCustomer,
-  type UpdateCustomerInput,
-} from "../api/customers"
-import { isStripeLike } from "../lib/payment-constants"
-import compareAddresses from "./compare-addresses"
-import { translateAddressError } from "./address-error-copy"
-import { translatePaymentError } from "./payment-error-copy"
-import { useCheckoutLabels, 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 Cartbase 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** (Cartbase 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; Cartbase treats
- *    null-secret + null-provider as the documented gift path.
- *  - The payment method fee: CART-LEVEL decoration
- *    (`payment_method_fee_total` / `payment_method_fee_label`, folded into
- *    `cart.total` while a live method session exists) — not a
- *    metadata-flagged line item. ANY method may carry a fee; the optimistic
- *    prediction reads `fee_amount` off the selected LISTING entry (the
- *    integrations `cod` block died 2026-08-11).
- *  - Processor ids: `pp_stripe` exactly (lib/payment-constants); merchant
- *    methods have no provider id — sessions ride `payment_method_id`.
- *  - `logCheckoutError`/`logEvent` (Supabase-side sinks in @1click) have no
- *    Cartbase store endpoint — the hook takes an optional `logError` callback
- *    so stores wire their own sink; all production log points are kept.
- *  - Cartbase 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.
- */
-
-/** A payable entry the hook accepts: a processor row (`{id}`) or a
- * merchant-method row (`{payment_method_id, name, kind}`) — the two wire
- * shapes of GET /api/store/payment-providers since the pp_* kill. */
-export type PaymentProviderLike = StorePaymentEntry | { 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. Cartbase 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
-  /**
-   * 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. Called with (errorType, message, context).
-   * DEFAULTS to reporting into the platform's checkout error log
-   * (POST /api/store/checkout-errors, step `browser`) so browser-side money
-   * failures reach the merchant without any wiring — a platform guarantee,
-   * not a merchant chore (money-chain-hardening, 2026-08-24). Override to
-   * add your own sink; fire-and-forget either way.
-   */
-  logError?: CheckoutLogError
-  /**
-   * Verbose [buy-click] console output for local debugging. OFF by default:
-   * the unguarded dumps used to print the full prepare-checkout payload —
-   * customer name, phone, email, address — into every customer's browser
-   * console. Redacted sink events fire regardless of this flag.
-   */
-  debug?: boolean
-}
-
-/**
- * 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. (Cartbase'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
-
-/** The offline tab's tender: a merchant METHOD entry (pp_* kill). The COD
- * method (kind 'cod') wins; any manual method serves as the offline tab
- * when no COD switch is on. The entry carries its own fee for prediction. */
-const findOfflineMethod = (
-  entries: PaymentProviderLike[] | null | undefined
-): StorePaymentMethodEntry | null => {
-  const methods = (entries ?? []).filter(
-    (m): m is Extract<PaymentProviderLike, { payment_method_id: string }> =>
-      "payment_method_id" in m && isMethodEntry(m as StorePaymentEntry)
-  )
-  return methods.find((m) => m.kind === "cod") ?? methods[0] ?? null
-}
-
-/**
- * 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,
-  orderConfirmedPath: orderConfirmedPathProp,
-  onOrderPlaced,
-  resolveTrackingMetadata,
-  logError: logErrorProp,
-  debug = false,
-}: UseCheckoutOrchestrationOptions) {
-  // The store's language, for the sentences a shopper reads when a save
-  // fails. English unless a locale pack is mounted above.
-  const checkoutLabels = useCheckoutLabels()
-  // The default sink: the platform's own checkout error log. Browser money
-  // failures (Stripe confirm errors, failed 3DS returns, place-order
-  // rejections) land in checkout_error_logs step `browser` with no merchant
-  // wiring. The two per-click debug snapshots are gated behind `debug` and
-  // never sent by default — the sink is for FAILURES, not telemetry.
-  const logError: CheckoutLogError = useCallback(
-    (errorType, message, context) => {
-      if (logErrorProp) {
-        logErrorProp(errorType, message, context)
-        return
-      }
-      void reportCheckoutError(client, {
-        error_type: errorType,
-        message,
-        cart_id: cart?.id,
-        context,
-      })
-    },
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [logErrorProp, client, cart?.id]
-  )
-  // Debug-gated console output — see the `debug` option's doc.
-  const dbg = debug
-    ? // eslint-disable-next-line no-console
-      (...args: unknown[]) => console.log(...args)
-    : () => {}
-  // 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
-  )
-
-  /**
-   * The store's own country list, fetched when the app did not pass one.
-   *
-   * Until 2026-09-13 an app that passed nothing got a ONE-ENTRY list built
-   * from `countryCode`, and the address form renders a read-only box for a
-   * single entry, so every scaffolded store shipped a checkout offering
-   * exactly one country that the shopper could not change. The list is the
-   * platform's to answer (`GET /api/store/countries`: the store's Markets
-   * when it has declared any, the whole catalogue when it has not), so the
-   * hook asks instead of guessing.
-   *
-   * A failure here must never block a checkout: the `countryCode` fallback
-   * below still stands, and the error is reported through `logError`.
-   */
-  const [storeCountries, setStoreCountries] = useState<StoreCountry[] | null>(null)
-  const appSuppliedCountries = !!(countries && countries.length)
-
-  useEffect(() => {
-    if (appSuppliedCountries) return
-    let alive = true
-    listCountries(client)
-      .then((res) => {
-        if (alive) setStoreCountries(res.countries)
-      })
-      .catch((e: unknown) => {
-        logError(
-          "country_list_failed",
-          e instanceof Error ? e.message : "could not load the country list"
-        )
-      })
-    return () => {
-      alive = false
-    }
-  }, [client, appSuppliedCountries, logError])
-
-  // The app's own list wins, then the store's, then the single-country
-  // fallback. This is the authority for both the select options and the
-  // saved-address region filter.
-  const regionCountries = useMemo(
-    () =>
-      countries && countries.length
-        ? countries
-        : storeCountries && storeCountries.length
-          ? storeCountries
-          : countryCode
-            ? // A fallback country still needs a NAME: this used to be an
-              // empty string, and the address form rendered a blank country
-              // field for it (evoo, 2026-09-13).
-              [{ iso_2: countryCode, display_name: countryName(countryCode) }]
-            : [],
-    [countries, storeCountries, 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. Cartbase 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,
-        }
-      )
-      // Into the store's own language. The raw error.message is technical
-      // English or a validation envelope, and neither is acceptable to
-      // show a shopper at the moment of failure. Unknown errors get the
-      // generic sentence rather than half-translated text.
-      setAddressError(translateAddressError(errObj ?? e, checkoutLabels.addressErrors))
-    } 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)
-
-  // Every listed option is offerable: the Medusa-era pickup filter read an
-  // embedded fulfillment_set the Cartbase API never sends (it never fired),
-  // and the concept itself died in the shipping vocabulary trial.
-  const shippingMethods = useMemo(
-    () => availableShippingMethods ?? [],
-    [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. Cartbase 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) => "id" in m && isStripeLike(m.id)
-  )
-  const cardId = (
-    effectiveAvailablePaymentMethods?.find(
-      (m) => "id" in m && isStripeLike(m.id)
-    ) as { id: string } | undefined
-  )?.id
-  // The offline tab = a merchant METHOD (the COD switch, else the first
-  // manual method) — sessions initiate by payment_method_id, provider NULL.
-  const offlineMethod = findOfflineMethod(effectiveAvailablePaymentMethods)
-  const hasCod = !!offlineMethod
-  const codMethodId = offlineMethod?.payment_method_id
-  const offlineIsCodKind = offlineMethod?.kind === "cod"
-
-  // 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 method-fee state. Painted instantly on tab toggle so the
-  // totals row shows the predicted fee BEFORE the server applies it (at
-  // prepare, when the method session is minted). Any method may carry a
-  // fee — the prediction reads the selected entry's own fee_amount.
-  // Three values:
-  //   - null         → no prediction; render whatever the cart says
-  //   - 0            → predict no fee (toggling to a fee-less tender)
-  //   - positive     → predict the fee at this amount
-  const [optimisticMethodFee, setOptimisticMethodFee] = 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 fee prediction so the totals row updates instantly —
-      // the selected METHOD entry carries its own fee; processors charge
-      // none. Mirrors the server exactly (resolveMethodFee reads the same
-      // row the listing serialized).
-      if (offlineMethod) {
-        const fee = Number(offlineMethod.fee_amount ?? 0)
-        setOptimisticMethodFee(tab === "cod" && fee > 0 ? fee : 0)
-      }
-
-      const tender =
-        tab === "card"
-          ? cardId
-            ? { provider_id: cardId }
-            : null
-          : codMethodId
-            ? { payment_method_id: codMethodId }
-            : null
-      if (tender) {
-        void syncPaymentAmountApi(client, cart.id, tender).catch(() => {})
-      }
-    },
-    [cart.id, client, cardId, codMethodId, offlineMethod]
-  )
-
-  // 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", checkoutLabels.paymentErrors)
-        setPaymentError(translated)
-        logError?.(
-          "place_order_error",
-          err instanceof Error ? err.message : String(err),
-          {
-            via: "3ds_return",
-            cartId: cart.id,
-            paymentIntentId,
-          }
-        )
-      })
-    } else {
-      // The store's own words. This was a hardcoded BULGARIAN sentence until
-      // 2026-09-13: the 2026-09-13 morning sweep fixed the three error-copy
-      // modules and missed this one, because it sits in the 3DS-return
-      // effect rather than in a copy module. Same meaning, from the pack.
-      setPaymentError(checkoutLabels.paymentErrors.paymentNotAuthorized)
-      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 optimisticMethodFee set: replace cart.payment_method_fee_total
-  //     with it (the 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 realMethodFeeAmount = cart?.payment_method_fee_total ?? 0
-    let total = cart?.total ?? 0
-    if (optimisticShippingCost !== null) {
-      total = total - (cart?.shipping_total ?? 0) + optimisticShippingCost
-    }
-    if (optimisticMethodFee !== null && optimisticMethodFee !== undefined) {
-      total = total - realMethodFeeAmount + optimisticMethodFee
-    }
-    return total
-  }, [
-    cart?.total,
-    cart?.shipping_total,
-    cart?.payment_method_fee_total,
-    optimisticShippingCost,
-    optimisticMethodFee,
-  ])
-
-  // ── 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")
-      }
-      // The tender: card tab → the processor; offline tab → the merchant
-      // method (provider-less session, pp_* kill).
-      const tender =
-        paymentTab === "card"
-          ? cardId
-            ? { payment_provider: cardId }
-            : null
-          : codMethodId
-            ? { payment_method_id: codMethodId }
-            : null
-      if (!tender) {
-        throw new Error("No payment method 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,
-        ...tender,
-      }
-    }, [
-      formData,
-      selectedShippingMethod,
-      selectedEcontOffice,
-      selectedBoxnowLocker,
-      paymentTab,
-      cardId,
-      codMethodId,
-    ])
-
-  // ── 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,
-        codMethodId,
-        selectedShippingMethod,
-        selectedEcontOffice: selectedEcontOffice
-          ? { code: selectedEcontOffice.code, name: selectedEcontOffice.name }
-          : null,
-        selectedBoxnowLocker: selectedBoxnowLocker
-          ? {
-              id: selectedBoxnowLocker.id,
-              title: selectedBoxnowLocker.title,
-            }
-          : null,
-        hasStripeBundle: !!stripeBundle,
-      }
-      dbg("[buy-click] STATE", stateSnapshot)
-      // Per-click telemetry goes only to a merchant-wired sink, never to the
-      // default platform error log — the sink is for failures.
-      logErrorProp?.("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")
-        }
-        dbg("[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()
-      // debug-only: the full payload carries the customer's name, phone,
-      // email and address — it must never print in a customer's console.
-      dbg("[buy-click] PAYLOAD →", payload)
-      logErrorProp?.("other", "buy_click_payload", {
-        provider_id: payload.payment_provider ?? null,
-        payment_method_id: payload.payment_method_id ?? null,
-        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
-        }
-      )
-      dbg("[buy-click] prepareCheckout response", {
-        has_client_secret: !!prep.client_secret,
-        provider_id: prep.provider_id,
-      })
-
-      // ── Zero-remainder gift path (Cartbase 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,
-          },
-        }
-
-        dbg("[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.
-        dbg("[buy-click] stripe.confirmPayment SUCCESS (no redirect)")
-        logErrorProp?.("stripe_confirm_succeeded", "ok", {
-          cart_id: cart.id,
-          client_secret_prefix: prep.client_secret.slice(0, 8),
-        })
-      } else if (zeroRemainderGiftPath) {
-        dbg(
-          "[buy-click] zero-remainder gift path — skipping Stripe, completing on the gift session"
-        )
-        logErrorProp?.("other", "zero_remainder_gift_path", { cart_id: cart.id })
-      }
-
-      dbg("[buy-click] placeOrder() …")
-      logErrorProp?.("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,
-      codMethodId,
-      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,
-    /** The offline tab's method (the COD switch or a manual method). */
-    codMethodId,
-    offlineMethod,
-    paymentError,
-    setPaymentError,
-    deliveryReady,
-    optimisticMethodFee,
-    setOptimisticMethodFee,
-    handlePaymentTab,
-    handlePaymentElementChange,
-
-    // Amount sync + recovery (SDK-wrapped)
-    syncPaymentAmount,
-    refreshPaymentIfTerminal,
-
-    // Buy click (deferred-intent flow)
-    optimisticTotal,
-    optimisticTotalCents,
-    buildPrepareCheckoutPayload,
-    performBuyClick,
-    placeOrder,
-
-    // Misc
-    summaryCart,
-  }
-}
+"use client"
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+} from "react"
+
+import type { StorefrontClient } from "../api/http"
+import { countryName } from "../lib/country-name"
+import { listCountries, type StoreCountry } from "../api/regions"
+import {
+  completeCart,
+  updateCart,
+  type Cart,
+  type CartAddress,
+  type CompletedOrder,
+  type UpdateCartInput,
+} from "../api/carts"
+import {
+  calculateShippingOption,
+  prepareCheckout,
+  refreshPaymentIfTerminal as refreshPaymentIfTerminalApi,
+  reportCheckoutError,
+  syncPaymentAmount as syncPaymentAmountApi,
+  isMethodEntry,
+  type PrepareCheckoutInput,
+  type RefreshPaymentResult,
+  type StorePaymentEntry,
+  type StorePaymentMethodEntry,
+  type StoreShippingOption,
+  type SyncPaymentAmountResult,
+} from "../api/checkout"
+import {
+  updateMe,
+  type CustomerAddress,
+  type StoreCustomer,
+  type UpdateCustomerInput,
+} from "../api/customers"
+import { isStripeLike } from "../lib/payment-constants"
+import compareAddresses from "./compare-addresses"
+import { translateAddressError } from "./address-error-copy"
+import { translatePaymentError } from "./payment-error-copy"
+import { useCheckoutLabels, 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 Cartbase 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** (Cartbase 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; Cartbase treats
+ *    null-secret + null-provider as the documented gift path.
+ *  - The payment method fee: CART-LEVEL decoration
+ *    (`payment_method_fee_total` / `payment_method_fee_label`, folded into
+ *    `cart.total` while a live method session exists) — not a
+ *    metadata-flagged line item. ANY method may carry a fee; the optimistic
+ *    prediction reads `fee_amount` off the selected LISTING entry (the
+ *    integrations `cod` block died 2026-08-11).
+ *  - Processor ids: `pp_stripe` exactly (lib/payment-constants); merchant
+ *    methods have no provider id — sessions ride `payment_method_id`.
+ *  - `logCheckoutError`/`logEvent` (Supabase-side sinks in @1click) have no
+ *    Cartbase store endpoint — the hook takes an optional `logError` callback
+ *    so stores wire their own sink; all production log points are kept.
+ *  - Cartbase 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.
+ */
+
+/** A payable entry the hook accepts: a processor row (`{id}`) or a
+ * merchant-method row (`{payment_method_id, name, kind}`) — the two wire
+ * shapes of GET /api/store/payment-providers since the pp_* kill. */
+export type PaymentProviderLike = StorePaymentEntry | { 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. Cartbase 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
+  /**
+   * 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. Called with (errorType, message, context).
+   * DEFAULTS to reporting into the platform's checkout error log
+   * (POST /api/store/checkout-errors, step `browser`) so browser-side money
+   * failures reach the merchant without any wiring — a platform guarantee,
+   * not a merchant chore (money-chain-hardening, 2026-08-24). Override to
+   * add your own sink; fire-and-forget either way.
+   */
+  logError?: CheckoutLogError
+  /**
+   * Verbose [buy-click] console output for local debugging. OFF by default:
+   * the unguarded dumps used to print the full prepare-checkout payload —
+   * customer name, phone, email, address — into every customer's browser
+   * console. Redacted sink events fire regardless of this flag.
+   */
+  debug?: boolean
+}
+
+/**
+ * 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. (Cartbase'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
+
+/** The offline tab's tender: a merchant METHOD entry (pp_* kill). The COD
+ * method (kind 'cod') wins; any manual method serves as the offline tab
+ * when no COD switch is on. The entry carries its own fee for prediction. */
+const findOfflineMethod = (
+  entries: PaymentProviderLike[] | null | undefined
+): StorePaymentMethodEntry | null => {
+  const methods = (entries ?? []).filter(
+    (m): m is Extract<PaymentProviderLike, { payment_method_id: string }> =>
+      "payment_method_id" in m && isMethodEntry(m as StorePaymentEntry)
+  )
+  return methods.find((m) => m.kind === "cod") ?? methods[0] ?? null
+}
+
+/**
+ * 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,
+  orderConfirmedPath: orderConfirmedPathProp,
+  onOrderPlaced,
+  resolveTrackingMetadata,
+  logError: logErrorProp,
+  debug = false,
+}: UseCheckoutOrchestrationOptions) {
+  // The store's language, for the sentences a shopper reads when a save
+  // fails. English unless a locale pack is mounted above.
+  const checkoutLabels = useCheckoutLabels()
+  // The default sink: the platform's own checkout error log. Browser money
+  // failures (Stripe confirm errors, failed 3DS returns, place-order
+  // rejections) land in checkout_error_logs step `browser` with no merchant
+  // wiring. The two per-click debug snapshots are gated behind `debug` and
+  // never sent by default — the sink is for FAILURES, not telemetry.
+  const logError: CheckoutLogError = useCallback(
+    (errorType, message, context) => {
+      if (logErrorProp) {
+        logErrorProp(errorType, message, context)
+        return
+      }
+      void reportCheckoutError(client, {
+        error_type: errorType,
+        message,
+        cart_id: cart?.id,
+        context,
+      })
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [logErrorProp, client, cart?.id]
+  )
+  // Debug-gated console output — see the `debug` option's doc.
+  const dbg = debug
+    ? // eslint-disable-next-line no-console
+      (...args: unknown[]) => console.log(...args)
+    : () => {}
+  // 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
+  )
+
+  /**
+   * The store's own country list, fetched when the app did not pass one.
+   *
+   * Until 2026-09-13 an app that passed nothing got a ONE-ENTRY list built
+   * from `countryCode`, and the address form renders a read-only box for a
+   * single entry, so every scaffolded store shipped a checkout offering
+   * exactly one country that the shopper could not change. The list is the
+   * platform's to answer (`GET /api/store/countries`: the store's Markets
+   * when it has declared any, the whole catalogue when it has not), so the
+   * hook asks instead of guessing.
+   *
+   * A failure here must never block a checkout: the `countryCode` fallback
+   * below still stands, and the error is reported through `logError`.
+   */
+  const [storeCountries, setStoreCountries] = useState<StoreCountry[] | null>(null)
+  const appSuppliedCountries = !!(countries && countries.length)
+
+  useEffect(() => {
+    if (appSuppliedCountries) return
+    let alive = true
+    listCountries(client)
+      .then((res) => {
+        if (alive) setStoreCountries(res.countries)
+      })
+      .catch((e: unknown) => {
+        logError(
+          "country_list_failed",
+          e instanceof Error ? e.message : "could not load the country list"
+        )
+      })
+    return () => {
+      alive = false
+    }
+  }, [client, appSuppliedCountries, logError])
+
+  // The app's own list wins, then the store's, then the single-country
+  // fallback. This is the authority for both the select options and the
+  // saved-address region filter.
+  const regionCountries = useMemo(
+    () =>
+      countries && countries.length
+        ? countries
+        : storeCountries && storeCountries.length
+          ? storeCountries
+          : countryCode
+            ? // A fallback country still needs a NAME: this used to be an
+              // empty string, and the address form rendered a blank country
+              // field for it (evoo, 2026-09-13).
+              [{ iso_2: countryCode, display_name: countryName(countryCode) }]
+            : [],
+    [countries, storeCountries, 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. Cartbase 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,
+        }
+      )
+      // Into the store's own language. The raw error.message is technical
+      // English or a validation envelope, and neither is acceptable to
+      // show a shopper at the moment of failure. Unknown errors get the
+      // generic sentence rather than half-translated text.
+      setAddressError(translateAddressError(errObj ?? e, checkoutLabels.addressErrors))
+    } 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)
+
+  // Every listed option is offerable: the Medusa-era pickup filter read an
+  // embedded fulfillment_set the Cartbase API never sends (it never fired),
+  // and the concept itself died in the shipping vocabulary trial.
+  const shippingMethods = useMemo(
+    () => availableShippingMethods ?? [],
+    [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. Cartbase 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) => "id" in m && isStripeLike(m.id)
+  )
+  const cardId = (
+    effectiveAvailablePaymentMethods?.find(
+      (m) => "id" in m && isStripeLike(m.id)
+    ) as { id: string } | undefined
+  )?.id
+  // The offline tab = a merchant METHOD (the COD switch, else the first
+  // manual method) — sessions initiate by payment_method_id, provider NULL.
+  const offlineMethod = findOfflineMethod(effectiveAvailablePaymentMethods)
+  const hasCod = !!offlineMethod
+  const codMethodId = offlineMethod?.payment_method_id
+  const offlineIsCodKind = offlineMethod?.kind === "cod"
+
+  // 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 method-fee state. Painted instantly on tab toggle so the
+  // totals row shows the predicted fee BEFORE the server applies it (at
+  // prepare, when the method session is minted). Any method may carry a
+  // fee — the prediction reads the selected entry's own fee_amount.
+  // Three values:
+  //   - null         → no prediction; render whatever the cart says
+  //   - 0            → predict no fee (toggling to a fee-less tender)
+  //   - positive     → predict the fee at this amount
+  const [optimisticMethodFee, setOptimisticMethodFee] = 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 fee prediction so the totals row updates instantly —
+      // the selected METHOD entry carries its own fee; processors charge
+      // none. Mirrors the server exactly (resolveMethodFee reads the same
+      // row the listing serialized).
+      if (offlineMethod) {
+        const fee = Number(offlineMethod.fee_amount ?? 0)
+        setOptimisticMethodFee(tab === "cod" && fee > 0 ? fee : 0)
+      }
+
+      const tender =
+        tab === "card"
+          ? cardId
+            ? { provider_id: cardId }
+            : null
+          : codMethodId
+            ? { payment_method_id: codMethodId }
+            : null
+      if (tender) {
+        void syncPaymentAmountApi(client, cart.id, tender).catch(() => {})
+      }
+    },
+    [cart.id, client, cardId, codMethodId, offlineMethod]
+  )
+
+  // 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", checkoutLabels.paymentErrors)
+        setPaymentError(translated)
+        logError?.(
+          "place_order_error",
+          err instanceof Error ? err.message : String(err),
+          {
+            via: "3ds_return",
+            cartId: cart.id,
+            paymentIntentId,
+          }
+        )
+      })
+    } else {
+      // The store's own words. This was a hardcoded BULGARIAN sentence until
+      // 2026-09-13: the 2026-09-13 morning sweep fixed the three error-copy
+      // modules and missed this one, because it sits in the 3DS-return
+      // effect rather than in a copy module. Same meaning, from the pack.
+      setPaymentError(checkoutLabels.paymentErrors.paymentNotAuthorized)
+      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 optimisticMethodFee set: replace cart.payment_method_fee_total
+  //     with it (the 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 realMethodFeeAmount = cart?.payment_method_fee_total ?? 0
+    let total = cart?.total ?? 0
+    if (optimisticShippingCost !== null) {
+      total = total - (cart?.shipping_total ?? 0) + optimisticShippingCost
+    }
+    if (optimisticMethodFee !== null && optimisticMethodFee !== undefined) {
+      total = total - realMethodFeeAmount + optimisticMethodFee
+    }
+    return total
+  }, [
+    cart?.total,
+    cart?.shipping_total,
+    cart?.payment_method_fee_total,
+    optimisticShippingCost,
+    optimisticMethodFee,
+  ])
+
+  // ── 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")
+      }
+      // The tender: card tab → the processor; offline tab → the merchant
+      // method (provider-less session, pp_* kill).
+      const tender =
+        paymentTab === "card"
+          ? cardId
+            ? { payment_provider: cardId }
+            : null
+          : codMethodId
+            ? { payment_method_id: codMethodId }
+            : null
+      if (!tender) {
+        throw new Error("No payment method 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,
+        ...tender,
+      }
+    }, [
+      formData,
+      selectedShippingMethod,
+      selectedEcontOffice,
+      selectedBoxnowLocker,
+      paymentTab,
+      cardId,
+      codMethodId,
+    ])
+
+  // ── 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,
+        codMethodId,
+        selectedShippingMethod,
+        selectedEcontOffice: selectedEcontOffice
+          ? { code: selectedEcontOffice.code, name: selectedEcontOffice.name }
+          : null,
+        selectedBoxnowLocker: selectedBoxnowLocker
+          ? {
+              id: selectedBoxnowLocker.id,
+              title: selectedBoxnowLocker.title,
+            }
+          : null,
+        hasStripeBundle: !!stripeBundle,
+      }
+      dbg("[buy-click] STATE", stateSnapshot)
+      // Per-click telemetry goes only to a merchant-wired sink, never to the
+      // default platform error log — the sink is for failures.
+      logErrorProp?.("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")
+        }
+        dbg("[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()
+      // debug-only: the full payload carries the customer's name, phone,
+      // email and address — it must never print in a customer's console.
+      dbg("[buy-click] PAYLOAD →", payload)
+      logErrorProp?.("other", "buy_click_payload", {
+        provider_id: payload.payment_provider ?? null,
+        payment_method_id: payload.payment_method_id ?? null,
+        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
+        }
+      )
+      dbg("[buy-click] prepareCheckout response", {
+        has_client_secret: !!prep.client_secret,
+        provider_id: prep.provider_id,
+      })
+
+      // ── Zero-remainder gift path (Cartbase 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,
+          },
+        }
+
+        dbg("[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.
+        dbg("[buy-click] stripe.confirmPayment SUCCESS (no redirect)")
+        logErrorProp?.("stripe_confirm_succeeded", "ok", {
+          cart_id: cart.id,
+          client_secret_prefix: prep.client_secret.slice(0, 8),
+        })
+      } else if (zeroRemainderGiftPath) {
+        dbg(
+          "[buy-click] zero-remainder gift path — skipping Stripe, completing on the gift session"
+        )
+        logErrorProp?.("other", "zero_remainder_gift_path", { cart_id: cart.id })
+      }
+
+      dbg("[buy-click] placeOrder() …")
+      logErrorProp?.("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,
+      codMethodId,
+      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,
+    /** The offline tab's method (the COD switch or a manual method). */
+    codMethodId,
+    offlineMethod,
+    paymentError,
+    setPaymentError,
+    deliveryReady,
+    optimisticMethodFee,
+    setOptimisticMethodFee,
+    handlePaymentTab,
+    handlePaymentElementChange,
+
+    // Amount sync + recovery (SDK-wrapped)
+    syncPaymentAmount,
+    refreshPaymentIfTerminal,
+
+    // Buy click (deferred-intent flow)
+    optimisticTotal,
+    optimisticTotalCents,
+    buildPrepareCheckoutPayload,
+    performBuyClick,
+    placeOrder,
+
+    // Misc
+    summaryCart,
+  }
+}