@cartbase/storefront 0.23.0 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Storefront SDK + UI component library for Cartbase stores: typed API client, checkout orchestration, cart drawer, product/catalog components, tracking. Source-shipped TypeScript — add it to transpilePackages.",
   "license": "MIT",
   "repository": {

package/src/api/checkout.ts

@@ -146,6 +146,12 @@ export interface ListPaymentProvidersQuery {
    * checkout; without it cart-dependent hide rules cannot match here.
    */
   cart_id?: string
+  /**
+   * Evaluate payment rules for the delivery option the shopper just chose.
+   * This avoids waiting for the cart preference write before refreshing the
+   * server-authoritative payment list.
+   */
+  shipping_option_id?: string
 }
 
 /** A connected PROCESSOR entry of GET /api/store/payment-providers. */
@@ -197,6 +203,12 @@ export const isMethodEntry = (
 
 export interface PaymentProviderListResponse extends ListEnvelope {
   payment_providers: StorePaymentEntry[]
+  /**
+   * Server-evaluated payment choices keyed by delivery option. CheckoutClient
+   * uses this to react synchronously during rapid shipping switches without
+   * reproducing the rules engine in the browser.
+   */
+  payment_providers_by_shipping_option?: Record<string, StorePaymentEntry[]>
 }
 
 /**

package/src/api/integrations.ts

@@ -177,9 +177,11 @@ export interface StorePickupPoint {
   provider: string
   mode: "office" | "locker"
   /** THEIR id, exactly as the order will carry it. */
-  id: string
-  name: string
-  city: string
+  id: string
+  name: string
+  /** Alternate script/transliteration supplied by the carrier. */
+  secondary_name?: string
+  city: string
   address: string
   postal_code: string
   phone: string

package/src/checkout/checkout-client.tsx

@@ -5,7 +5,8 @@ import type { Appearance, StripeElementsOptions } from "@stripe/stripe-js"
 import type { StorefrontClient } from "../api/http"
 import type { Cart } from "../api/carts"
 import type { StoreShippingOption } from "../api/checkout"
-import type { StoreCustomer } from "../api/customers"
+import type { StoreCustomer } from "../api/customers"
+import type { PaymentMethod } from "../common/payment-icons"
 import { CheckoutAddressForm } from "./address-form"
 import { DiscountSection } from "./discount-section"
 import { MobileCheckoutBottomBar } from "./mobile-checkout-bottom-bar"
@@ -58,8 +59,14 @@ type CheckoutClientProps = {
   client: StorefrontClient
   cart: Cart
   customer: StoreCustomer | null
-  availableShippingMethods: StoreShippingOption[] | null
-  availablePaymentMethods: PaymentProviderLike[] | null
+  availableShippingMethods: StoreShippingOption[] | null
+  availablePaymentMethods: PaymentProviderLike[] | null
+  /** Server-evaluated tender lists keyed by delivery option id. */
+  paymentMethodsByShippingOption?: Record<string, PaymentProviderLike[]>
+  /** Card and wallet marks returned by `GET /api/store/payment-marks`. */
+  paymentMarks?: readonly PaymentMethod[]
+  /** Store-owned terms notice, including links to its content pages. */
+  termsContent?: React.ReactNode
   /**
    * The country to PRESELECT when the cart has no shipping address yet.
    * Optional, like the hook's own: the offer comes from the store
@@ -76,8 +83,10 @@ type CheckoutClientProps = {
     methods: PaymentProviderLike[] | null,
     selectedShippingOption: StoreShippingOption | null
   ) => PaymentProviderLike[] | null
-  /** Show the gift-card widget in the summary (default true). */
-  showGiftCards?: boolean
+  /** Show the gift-card widget in the summary (default true). */
+  showGiftCards?: boolean
+  /** Show the security reassurance below the desktop total (default true). */
+  showSecureCheckout?: boolean
   logoByFulfillmentOptionId?: Record<string, { src: string; alt: string }>
   /** Stripe Elements appearance + fonts forwarded to PaymentWrapper. */
   appearance?: Appearance
@@ -106,12 +115,16 @@ export function CheckoutClient({
   client,
   cart,
   customer,
-  availableShippingMethods,
-  availablePaymentMethods,
+  availableShippingMethods,
+  availablePaymentMethods,
+  paymentMethodsByShippingOption,
+  paymentMarks,
+  termsContent,
   countryCode,
   countries,
   paymentMethodFilter,
-  showGiftCards = true,
+  showGiftCards = true,
+  showSecureCheckout = true,
   logoByFulfillmentOptionId,
   appearance,
   fonts,
@@ -126,8 +139,9 @@ export function CheckoutClient({
     client,
     cart,
     customer,
-    availableShippingMethods,
-    availablePaymentMethods,
+    availableShippingMethods,
+    availablePaymentMethods,
+    paymentMethodsByShippingOption,
     countryCode,
     countries,
     paymentMethodFilter,
@@ -165,9 +179,10 @@ export function CheckoutClient({
       <MobileCheckoutTopBar
         client={client}
         cart={o.summaryCart}
-        optimisticShippingCost={o.optimisticShippingCost}
-        optimisticMethodFee={o.optimisticMethodFee}
-        showGiftCards={showGiftCards}
+        optimisticShippingCost={o.optimisticShippingCost}
+        optimisticMethodFee={o.optimisticMethodFee}
+        methodFeeLabel={o.paymentTab === "cod" ? o.offlineMethod?.fee_label ?? undefined : undefined}
+        showGiftCards={showGiftCards}
         onCartChange={handleCartChange}
       />
 
@@ -218,9 +233,13 @@ export function CheckoutClient({
 
             <CheckoutPaymentMethodList
               cart={cart}
-              hasCard={o.hasCard}
-              hasCod={o.hasCod}
-              paymentTab={o.paymentTab}
+              hasCard={o.hasCard}
+              hasCod={o.hasCod}
+              offlineMethod={o.offlineMethod}
+              paymentMethodOrder={o.paymentMethodOrder}
+              paymentMarks={paymentMarks}
+              termsContent={termsContent}
+              paymentTab={o.paymentTab}
               onPaymentTab={o.handlePaymentTab}
               deliveryReady={o.deliveryReady}
               nothingToPay={o.nothingToPay}
@@ -252,9 +271,10 @@ export function CheckoutClient({
                   <MobileCheckoutBottomBar
                     client={client}
                     cart={o.summaryCart}
-                    optimisticShippingCost={o.optimisticShippingCost}
-                    optimisticMethodFee={o.optimisticMethodFee}
-                    showGiftCards={showGiftCards}
+                    optimisticShippingCost={o.optimisticShippingCost}
+                    optimisticMethodFee={o.optimisticMethodFee}
+                    methodFeeLabel={o.paymentTab === "cod" ? o.offlineMethod?.fee_label ?? undefined : undefined}
+                    showGiftCards={showGiftCards}
                     hideDiscount
                     onCartChange={handleCartChange}
                   />
@@ -273,10 +293,12 @@ export function CheckoutClient({
                 onOptimisticShippingClear={() =>
                   o.setOptimisticShippingCost(null)
                 }
-                optimisticMethodFee={o.optimisticMethodFee}
-                onOptimisticMethodFeeClear={() => o.setOptimisticMethodFee(null)}
-                showGiftCards={showGiftCards}
-                onCartChange={handleCartChange}
+                optimisticMethodFee={o.optimisticMethodFee}
+                onOptimisticMethodFeeClear={() => o.setOptimisticMethodFee(null)}
+                methodFeeLabel={o.paymentTab === "cod" ? o.offlineMethod?.fee_label ?? undefined : undefined}
+                showGiftCards={showGiftCards}
+                showSecureCheckout={showSecureCheckout}
+                onCartChange={handleCartChange}
               />
             </div>
           </div>

package/src/checkout/discount-section.tsx

@@ -107,7 +107,7 @@ export function DiscountSection({
   }
 
   const field = (
-    <div className={cn("flex gap-2", !alwaysOpen && "mt-3")}>
+    <div className={cn("grid grid-cols-[minmax(0,1fr)_auto] gap-2", !alwaysOpen && "mt-3")}>
       <input
         type="text"
         value={code}
@@ -119,13 +119,13 @@ export function DiscountSection({
           }
         }}
         placeholder="PROMO2024"
-        className="flex-1 h-11 px-4 text-sm bg-card border border-border rounded-xl focus:outline-none focus:border-primary focus:ring-2 focus:ring-primary/20 transition-all"
+        className="w-full min-w-0 h-11 px-4 text-sm bg-card border border-border rounded-xl focus:outline-none focus:border-primary focus:ring-2 focus:ring-primary/20 transition-all"
       />
       <button
         type="button"
         onClick={handleApply}
         disabled={loading || !code.trim()}
-        className="px-5 h-11 text-sm font-semibold bg-foreground text-card rounded-xl hover:bg-foreground/90 transition-all disabled:opacity-40"
+        className="px-4 h-11 text-sm font-semibold bg-foreground text-card rounded-xl hover:bg-foreground/90 transition-all disabled:opacity-40"
       >
         {labels.addCode}
       </button>
@@ -150,7 +150,7 @@ export function DiscountSection({
       <button
         type="button"
         onClick={() => setOpen(!open)}
-        className="flex items-center gap-3 w-full p-4 rounded-xl border border-border bg-muted/50 hover:bg-muted transition-colors"
+        className="grid grid-cols-[2.5rem_minmax(0,1fr)_auto] items-center gap-3 w-full p-4 rounded-xl border border-border bg-card hover:border-primary transition-colors"
       >
         <div className="w-10 h-10 rounded-full bg-gradient-to-br from-warning to-warning/70 flex items-center justify-center flex-shrink-0">
           <svg
@@ -172,13 +172,15 @@ export function DiscountSection({
             />
           </svg>
         </div>
-        <div className="flex-1 text-left">
-          <p className="text-sm font-semibold text-foreground">
+        <div className="min-w-0 text-left">
+          <p className="text-sm font-semibold leading-tight text-foreground truncate">
             {labels.discountCode}
           </p>
-          <p className="text-xs text-muted-foreground">{labels.discountSub}</p>
+          <p className="hidden min-[380px]:block text-xs text-muted-foreground truncate">
+            {labels.discountSub}
+          </p>
         </div>
-        <span className="text-sm font-medium text-foreground flex items-center gap-1.5">
+        <span className="shrink-0 whitespace-nowrap text-sm font-medium text-foreground flex items-center gap-1.5">
           {labels.addCode}
           <svg
             className={cn(

package/src/checkout/gift-card-section.tsx

@@ -100,7 +100,7 @@ export function GiftCardSection({
       <button
         type="button"
         onClick={() => setOpen(!open)}
-        className="flex items-center gap-3 w-full p-4 rounded-xl border border-border bg-muted/50 hover:bg-muted transition-colors"
+        className="grid grid-cols-[2.5rem_minmax(0,1fr)_auto] items-center gap-3 w-full p-4 rounded-xl border border-border bg-card hover:border-primary transition-colors"
       >
         <div className="w-10 h-10 rounded-full bg-gradient-to-br from-primary to-primary/70 flex items-center justify-center flex-shrink-0">
           {/* Gift icon */}
@@ -118,13 +118,15 @@ export function GiftCardSection({
             />
           </svg>
         </div>
-        <div className="flex-1 text-left">
-          <p className="text-sm font-semibold text-foreground">
+        <div className="min-w-0 text-left">
+          <p className="text-sm font-semibold leading-tight text-foreground truncate">
             {labels.giftCard}
           </p>
-          <p className="text-xs text-muted-foreground">{labels.giftCardSub}</p>
+          <p className="hidden min-[380px]:block text-xs text-muted-foreground truncate">
+            {labels.giftCardSub}
+          </p>
         </div>
-        <span className="text-sm font-medium text-foreground flex items-center gap-1.5">
+        <span className="shrink-0 whitespace-nowrap text-sm font-medium text-foreground flex items-center gap-1.5">
           {labels.addCode}
           <svg
             className={cn(
@@ -146,19 +148,19 @@ export function GiftCardSection({
       </button>
 
       {open && (
-        <div className="mt-3 flex gap-2">
+        <div className="mt-3 grid grid-cols-[minmax(0,1fr)_auto] gap-2">
           <input
             type="text"
             value={code}
             onChange={(e) => setCode(e.target.value.toUpperCase())}
             placeholder={labels.giftCardPlaceholder}
-            className="flex-1 h-11 px-4 text-sm bg-card border border-border rounded-xl focus:outline-none focus:border-primary focus:ring-2 focus:ring-primary/20 transition-all"
+            className="w-full min-w-0 h-11 px-4 text-sm bg-card border border-border rounded-xl focus:outline-none focus:border-primary focus:ring-2 focus:ring-primary/20 transition-all"
           />
           <button
             type="button"
             onClick={handleApply}
             disabled={loading || !code.trim()}
-            className="px-5 h-11 text-sm font-semibold bg-foreground text-card rounded-xl hover:bg-foreground/90 transition-all disabled:opacity-40"
+            className="px-4 h-11 text-sm font-semibold bg-foreground text-card rounded-xl hover:bg-foreground/90 transition-all disabled:opacity-40"
           >
             {labels.addCode}
           </button>

package/src/checkout/latest-write-queue.ts

@@ -0,0 +1,39 @@
+/**
+ * Serialize a rapidly changing preference while coalescing clicks that have
+ * not started yet. The write in flight finishes; then only the newest queued
+ * value is written. This guarantees that the final durable value is the last
+ * user intent even when network responses complete unpredictably.
+ */
+export function createLatestWriteQueue<T>() {
+  let queued: { value: T; write: (value: T) => Promise<unknown> } | null = null
+  let running = false
+
+  const drain = async () => {
+    if (running) return
+    running = true
+    try {
+      while (queued) {
+        const next = queued
+        queued = null
+        try {
+          await next.write(next.value)
+        } catch {
+          // Persistence is best effort. A newer queued value must still run,
+          // and checkout completion independently validates the final choice.
+        }
+      }
+    } finally {
+      running = false
+      // A push cannot interleave with synchronous code above, but keeping the
+      // final check makes the queue safe if its implementation later changes.
+      if (queued) void drain()
+    }
+  }
+
+  return {
+    push(value: T, write: (value: T) => Promise<unknown>) {
+      queued = { value, write }
+      void drain()
+    },
+  }
+}

package/src/checkout/mobile-checkout-top-bar.tsx

@@ -50,7 +50,7 @@ export function MobileCheckoutTopBar({
   })
 
   return (
-    <div className="sm:hidden bg-muted border-y border-border">
+    <div className="sm:hidden bg-card border-y border-border">
       <button
         type="button"
         onClick={() => setOpen((v) => !v)}

package/src/checkout/order-summary.tsx

@@ -168,7 +168,9 @@ type OrderSummaryProps = {
   /** Show the gift-card widget. Default true; pass false for stores that
    * haven't enabled gift cards (the widget itself is harmless either way —
    * an unknown code gets the generic refusal). */
-  showGiftCards?: boolean
+  showGiftCards?: boolean
+  /** Show the security reassurance below the total. Default true. */
+  showSecureCheckout?: boolean
   /**
    * Receives every decorated cart returned by a summary mutation
    * (quantity change, promo apply, gift-card apply/remove). Hosts update
@@ -186,9 +188,10 @@ export function OrderSummary({
   onOptimisticShippingClear,
   optimisticMethodFee,
   onOptimisticMethodFeeClear,
-  methodFeeLabel,
-  showGiftCards = true,
-  onCartChange,
+  methodFeeLabel,
+  showGiftCards = true,
+  showSecureCheckout = true,
+  onCartChange,
 }: OrderSummaryProps) {
   const labels = useCheckoutLabels()
 
@@ -377,7 +380,11 @@ export function OrderSummary({
           )}
         </div>
 
-        <div className="mx-5 sm:mx-6 mt-4 pt-4 border-t border-border">
+        <div
+          className={`mx-5 sm:mx-6 mt-4 pt-4 border-t border-border ${
+            showSecureCheckout ? "" : "pb-5"
+          }`}
+        >
           <div className="flex justify-between items-center">
             <span className="text-lg font-bold text-foreground">
               {labels.total}
@@ -420,22 +427,24 @@ export function OrderSummary({
           )}
         </div>
 
-        <div className="px-5 sm:px-6 pb-5 pt-4 flex items-center justify-center gap-2 text-xs text-muted-foreground">
-          <svg
-            className="w-3.5 h-3.5"
-            fill="none"
-            viewBox="0 0 24 24"
-            stroke="currentColor"
-            strokeWidth={2}
-          >
-            <path
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
-            />
-          </svg>
-          <span>{labels.secureCheckout}</span>
-        </div>
+        {showSecureCheckout && (
+          <div className="px-5 sm:px-6 pb-5 pt-4 flex items-center justify-center gap-2 text-xs text-muted-foreground">
+            <svg
+              className="w-3.5 h-3.5"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              strokeWidth={2}
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
+              />
+            </svg>
+            <span>{labels.secureCheckout}</span>
+          </div>
+        )}
       </div>
     </div>
   )

package/src/checkout/payment-method-list.tsx

@@ -2,9 +2,11 @@
 
 import { PaymentElement } from "@stripe/react-stripe-js"
 import type { StripePaymentElementChangeEvent } from "@stripe/stripe-js"
-import { useContext, useEffect, useState } from "react"
-
-import { cn } from "../lib/utils"
+import { useContext, useEffect, useState } from "react"
+
+import type { StorePaymentMethodEntry } from "../api/checkout"
+import { PaymentIcon, type PaymentMethod } from "../common/payment-icons"
+import { cn } from "../lib/utils"
 import { useCheckoutLabels } from "./context"
 import { ErrorMessage } from "./error-message"
 import { PaymentButton } from "./payment-button"
@@ -34,9 +36,17 @@ import type { CheckoutLogError } from "./use-checkout-orchestration"
 type CheckoutPaymentMethodListProps = {
   /** Structural cart — forwarded to PaymentButton (`id`/`total`/`currency_code`). */
   cart: { id: string; total?: number | null; currency_code: string }
-  hasCard: boolean
-  hasCod: boolean
-  paymentTab: "card" | "cod"
+  hasCard: boolean
+  hasCod: boolean
+  /** The merchant-configured method shown by the offline/COD tab. */
+  offlineMethod: StorePaymentMethodEntry | null
+  /** Platform-defined order after checkout rules have been applied. */
+  paymentMethodOrder: Array<"card" | "cod">
+  /** Card and wallet marks enabled for the connected payment provider. */
+  paymentMarks?: readonly PaymentMethod[]
+  /** Store-owned terms notice. Falls back to the locale's plain text. */
+  termsContent?: React.ReactNode
+  paymentTab: "card" | "cod"
   onPaymentTab: (tab: "card" | "cod") => void
   deliveryReady: boolean
   paymentError: string | null
@@ -117,9 +127,13 @@ type CheckoutPaymentMethodListProps = {
 
 export function CheckoutPaymentMethodList({
   cart,
-  hasCard,
-  hasCod,
-  paymentTab,
+  hasCard,
+  hasCod,
+  offlineMethod,
+  paymentMethodOrder,
+  paymentMarks = [],
+  termsContent,
+  paymentTab,
   onPaymentTab,
   deliveryReady,
   paymentError,
@@ -138,7 +152,13 @@ export function CheckoutPaymentMethodList({
 
   // Which extra tab is active, if any. Selecting card/cod clears it; the
   // radio group stays single-select across built-in and extra tabs.
-  const [extraTab, setExtraTab] = useState<string | null>(null)
+  const [extraTab, setExtraTab] = useState<string | null>(null)
+  const methodPosition = (method: "card" | "cod") => {
+    const position = paymentMethodOrder.indexOf(method)
+    return position === -1 ? paymentMethodOrder.length : position
+  }
+  const visiblePaymentMarks = paymentMarks.slice(0, 3)
+  const hiddenPaymentMarkCount = Math.max(0, paymentMarks.length - visiblePaymentMarks.length)
 
   // When the store opts out of gating (gatePaymentUntilDelivery=false),
   // the payment section is always shown + interactive regardless of
@@ -212,7 +232,9 @@ export function CheckoutPaymentMethodList({
       <h2 className="text-lg font-semibold text-foreground mb-1 tracking-tight">
         {labels.paymentMethod}
       </h2>
-      <p className="text-xs text-muted-foreground mb-4">{labels.termsText}</p>
+      <p className="text-xs text-muted-foreground mb-4">
+        {termsContent ?? labels.termsText}
+      </p>
 
       {paymentGated ? (
         <div className="p-4 bg-muted rounded-lg border border-border">
@@ -239,7 +261,7 @@ export function CheckoutPaymentMethodList({
         // and tracking refs upstream are NOT torn down. That's the
         // whole point of moving away from PaymentWrapper-wraps-all.
         <StripeElementsScope passthrough>
-          <div className="space-y-2">
+          <div className="flex flex-col gap-2">
             {nothingToPay && (
               // One line instead of a tender list. The shopper owes
               // nothing, so every radio here would be a question with no
@@ -250,8 +272,9 @@ export function CheckoutPaymentMethodList({
               </div>
             )}
             {!nothingToPay && hasCard && (
-              <div
-                className={cn(
+              <div
+                style={{ order: methodPosition("card") }}
+                className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
                   paymentTab === "card" && !extraTab
                     ? "border-primary bg-primary/5"
@@ -276,10 +299,22 @@ export function CheckoutPaymentMethodList({
                       <div className="w-2 h-2 rounded-full bg-primary" />
                     )}
                   </div>
-                  <span className="text-sm font-medium text-foreground">
-                    {labels.payOnline}
-                  </span>
-                </button>
+                  <span className="text-sm font-medium text-foreground">
+                    {labels.payOnline}
+                  </span>
+                  {visiblePaymentMarks.length > 0 && (
+                    <span className="ml-auto flex items-center gap-1.5 pl-3">
+                      {visiblePaymentMarks.map((method) => (
+                        <PaymentIcon key={method} method={method} className="h-6" />
+                      ))}
+                      {hiddenPaymentMarkCount > 0 && (
+                        <span className="flex h-6 min-w-8 items-center justify-center rounded border border-border bg-card px-1.5 text-xs font-medium text-foreground">
+                          +{hiddenPaymentMarkCount}
+                        </span>
+                      )}
+                    </span>
+                  )}
+                </button>
 
                 {paymentTab === "card" && !extraTab && (
                   <div className="px-4 pb-4 pt-2">
@@ -329,8 +364,9 @@ export function CheckoutPaymentMethodList({
             )}
 
             {!nothingToPay && hasCod && (
-              <div
-                className={cn(
+              <div
+                style={{ order: methodPosition("cod") }}
+                className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
                   paymentTab === "cod" && !extraTab
                     ? "border-primary bg-primary/5"
@@ -355,23 +391,24 @@ export function CheckoutPaymentMethodList({
                       <div className="w-2 h-2 rounded-full bg-primary" />
                     )}
                   </div>
-                  <span className="text-sm font-medium text-foreground">
-                    {labels.cashOnDelivery}
-                  </span>
+                  <span className="text-sm font-medium text-foreground">
+                    {offlineMethod?.name ?? labels.cashOnDelivery}
+                  </span>
                 </button>
                 {paymentTab === "cod" && !extraTab && (
                   <div className="px-4 pb-3 pt-0">
-                    <p className="text-xs text-muted-foreground ml-[30px]">
-                      {labels.codNote}
-                    </p>
+                    <p className="text-xs text-muted-foreground ml-[30px]">
+                      {offlineMethod?.instructions ?? labels.codNote}
+                    </p>
                   </div>
                 )}
               </div>
             )}
 
-            {!nothingToPay && extraTabs?.map((tab) => (
-              <div
-                key={tab.id}
+            {!nothingToPay && extraTabs?.map((tab, index) => (
+              <div
+                key={tab.id}
+                style={{ order: paymentMethodOrder.length + index }}
                 className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
                   extraTab === tab.id

package/src/checkout/pickup-point-selector.tsx

@@ -146,11 +146,11 @@ export function PickupPointSelector({
       <button
         key={`${point.provider}-${point.id}`}
         type="button"
-        onClick={() => choose(point)}
-        className={cn(
-          "flex items-start gap-3 w-full px-3.5 py-3 text-left transition-all duration-150 rounded-lg",
-          "bg-card hover:bg-muted"
-        )}
+        onClick={() => choose(point)}
+        className={cn(
+          "flex items-start gap-3 w-full px-3.5 py-3 text-left transition-colors duration-150 rounded-lg border border-transparent",
+          "bg-card hover:border-primary"
+        )}
       >
         <div className="w-8 h-8 rounded-full bg-muted flex items-center justify-center flex-shrink-0 mt-0.5">
           <svg
@@ -175,12 +175,13 @@ export function PickupPointSelector({
         </div>
 
         <div className="flex-1 min-w-0">
-          <p className="text-sm font-medium text-foreground leading-tight">
-            {point.name}
-          </p>
-          <p className="text-xs text-muted-foreground mt-0.5">
-            {[point.address, point.city].filter(Boolean).join(", ")}
-          </p>
+          <p className="text-sm font-medium text-foreground leading-tight uppercase">
+            {point.name}
+          </p>
+          <p className="text-xs text-muted-foreground mt-0.5">
+            {point.secondary_name ||
+              [point.address, point.city].filter(Boolean).join(", ")}
+          </p>
         </div>
 
         {distance !== null && distance > 0 && (
@@ -222,7 +223,7 @@ export function PickupPointSelector({
               d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
             />
           </svg>
-          <p className="text-sm font-medium text-primary">{selectedPoint.name}</p>
+          <p className="text-sm font-medium text-primary uppercase">{selectedPoint.name}</p>
           <button
             type="button"
             onClick={() => choose(null)}

package/src/checkout/shipping-method-list.tsx

@@ -195,10 +195,10 @@ export function CheckoutShippingMethodList({
               <div
                 key={option.id}
                 className={cn(
-                  "rounded-lg border overflow-hidden transition-colors duration-150",
-                  selected
-                    ? "border-primary bg-primary/5"
-                    : "border-border bg-card hover:border-muted-foreground"
+                  "rounded-lg border overflow-hidden transition-colors duration-150",
+                  selected
+                    ? "border-primary bg-primary/5"
+                    : "border-border bg-card hover:border-primary"
                 )}
               >
                 <button
@@ -235,13 +235,13 @@ export function CheckoutShippingMethodList({
                     </span>
                   )}
                   <div className="flex-1 min-w-0">
-                    <span className="text-sm font-medium text-foreground">
-                      {option.name}
-                    </span>
+                    <span className="text-sm font-medium text-foreground uppercase">
+                      {option.name}
+                    </span>
                     {selected && isPickup && pickup?.selectedPoint && (
-                      <p className="text-xs text-muted-foreground mt-0.5">
-                        {pickup.selectedPoint.name}
-                      </p>
+                      <p className="text-xs text-muted-foreground mt-0.5 uppercase">
+                        {pickup.selectedPoint.name}
+                      </p>
                     )}
                   </div>
                   <span

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

@@ -25,8 +25,9 @@ import {
   prepareCheckout,
   refreshPaymentIfTerminal as refreshPaymentIfTerminalApi,
   reportCheckoutError,
-  syncPaymentAmount as syncPaymentAmountApi,
-  isMethodEntry,
+  syncPaymentAmount as syncPaymentAmountApi,
+  isMethodEntry,
+  listPaymentProviders,
   type PrepareCheckoutInput,
   type RefreshPaymentResult,
   type StorePaymentEntry,
@@ -54,7 +55,8 @@ import { useCheckoutLabels, useOrderConfirmedPath } from "./context"
 import { fulfillmentOptionId } from "./fulfillment-option"
 import { useCheckoutFunnel } from "./use-checkout-funnel"
 import { amountDueAfterTender, isNothingToPay } from "./summary-math"
-import { forgetFiredEvents } from "../tracking/once"
+import { forgetFiredEvents } from "../tracking/once"
+import { createLatestWriteQueue } from "./latest-write-queue"
 
 /**
  * useCheckoutOrchestration — single source of truth for checkout-page
@@ -122,8 +124,13 @@ export type UseCheckoutOrchestrationOptions = {
   client: StorefrontClient
   cart: Cart
   customer: StoreCustomer | null
-  availableShippingMethods: StoreShippingOption[] | null
-  availablePaymentMethods: PaymentProviderLike[] | null
+  availableShippingMethods: StoreShippingOption[] | null
+  availablePaymentMethods: PaymentProviderLike[] | null
+  /**
+   * Server-evaluated payment availability keyed by delivery option. When
+   * supplied, a shipping click changes the tender list synchronously.
+   */
+  paymentMethodsByShippingOption?: Record<string, PaymentProviderLike[]>
   /** Default country code when the cart has no shipping address yet. */
   countryCode?: string
   /**
@@ -287,8 +294,9 @@ export function useCheckoutOrchestration({
   client,
   cart,
   customer,
-  availableShippingMethods,
-  availablePaymentMethods,
+  availableShippingMethods,
+  availablePaymentMethods,
+  paymentMethodsByShippingOption,
   countryCode = "",
   countries,
   paymentMethodFilter,
@@ -868,18 +876,49 @@ export function useCheckoutOrchestration({
     [availableShippingMethods]
   )
 
-  const selectedShippingOption = useMemo(
+  const selectedShippingOption = useMemo(
     () =>
       shippingMethods.find((sm) => sm.id === selectedShippingMethod) ?? null,
     [shippingMethods, selectedShippingMethod]
-  )
-
-  const effectiveAvailablePaymentMethods = useMemo(
-    () =>
-      paymentMethodFilter
-        ? paymentMethodFilter(availablePaymentMethods, selectedShippingOption)
-        : availablePaymentMethods,
-    [paymentMethodFilter, availablePaymentMethods, selectedShippingOption]
+  )
+
+  // Payment rules can depend on the selected delivery option. The host's
+  // initial list is server-rendered; after a delivery choice is remembered
+  // on the cart, ask the same server-side rules door for the new list. A
+  // sequence guard prevents a slower earlier choice from winning a rapid
+  // switch between carriers.
+  const [serverAvailablePaymentMethods, setServerAvailablePaymentMethods] =
+    useState<PaymentProviderLike[] | null>(availablePaymentMethods)
+  const paymentListingRequest = useRef(0)
+  useEffect(() => {
+    const mapped = selectedShippingMethod
+      ? paymentMethodsByShippingOption?.[selectedShippingMethod]
+      : undefined
+    setServerAvailablePaymentMethods(mapped ?? availablePaymentMethods)
+  }, [availablePaymentMethods, paymentMethodsByShippingOption, selectedShippingMethod])
+  const refreshPaymentMethods = useCallback(async (shippingOptionId: string) => {
+    const request = ++paymentListingRequest.current
+    try {
+      const result = await listPaymentProviders(client, {
+        cart_id: cart.id,
+        region_id: cart.region_id ?? undefined,
+        shipping_option_id: shippingOptionId,
+      })
+      if (request === paymentListingRequest.current) {
+        setServerAvailablePaymentMethods(result.payment_providers)
+      }
+    } catch {
+      // Keep the last good listing. Completion re-checks the same rule on
+      // the server, so a transient refresh failure cannot bypass it.
+    }
+  }, [client, cart.id, cart.region_id])
+
+  const effectiveAvailablePaymentMethods = useMemo(
+    () =>
+      paymentMethodFilter
+        ? paymentMethodFilter(serverAvailablePaymentMethods, selectedShippingOption)
+        : serverAvailablePaymentMethods,
+    [paymentMethodFilter, serverAvailablePaymentMethods, selectedShippingOption]
   )
 
   // Calculated-rate price resolution. Cartbase serves flat prices today
@@ -977,9 +1016,37 @@ export function useCheckoutOrchestration({
   // 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"
+  const hasCod = !!offlineMethod
+  const codMethodId = offlineMethod?.payment_method_id
+  const offlineIsCodKind = offlineMethod?.kind === "cod"
+
+  // Preserve the platform listing order all the way into the checkout UI.
+  // The API has already applied checkout_method_order; collapsing the rows
+  // into card/COD booleans used to throw that order away.
+  const paymentMethodOrder = useMemo(() => {
+    const order: Array<"card" | "cod"> = []
+    for (const entry of effectiveAvailablePaymentMethods ?? []) {
+      if (
+        hasCard &&
+        "id" in entry &&
+        entry.id === cardEntry?.id &&
+        !order.includes("card")
+      ) {
+        order.push("card")
+      }
+      if (
+        hasCod &&
+        "payment_method_id" in entry &&
+        entry.payment_method_id === codMethodId &&
+        !order.includes("cod")
+      ) {
+        order.push("cod")
+      }
+    }
+    if (hasCard && !order.includes("card")) order.push("card")
+    if (hasCod && !order.includes("cod")) order.push("cod")
+    return order
+  }, [effectiveAvailablePaymentMethods, hasCard, cardEntry?.id, hasCod, codMethodId])
 
   // The store offers a card it cannot mount: reported once, to the merchant,
   // because the shopper must never be the one who discovers it. Pre-2026-09-18
@@ -996,12 +1063,12 @@ export function useCheckoutOrchestration({
     )
   }, [cardEntry, cardOffer.mountable, logError])
 
-  // 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"
-  )
+  // Default tab: the first method in the merchant's checkout order. 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">(
+    paymentMethodOrder[0] ?? (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
@@ -1011,10 +1078,10 @@ export function useCheckoutOrchestration({
   //   - 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
-  )
-
+  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
@@ -1068,15 +1135,28 @@ export function useCheckoutOrchestration({
    * are the checkout's own notes to itself, and prepare-checkout overwrites
    * the real ones from them.
    */
-  const rememberChoice = useCallback(
-    (patch: Record<string, unknown>) => {
-      void updateCart(client, cart.id, { metadata: patch }).catch(() => {
-        // Best effort: forgetting a choice on reload is a worse checkout,
-        // never a broken one, so a failure here must not reach the shopper.
-      })
+  const rememberChoice = useCallback(
+    (patch: Record<string, unknown>) => {
+      return updateCart(client, cart.id, { metadata: patch })
+        .then(() => true)
+        .catch(() => {
+          // Best effort: forgetting a choice on reload is a worse checkout,
+          // never a broken one, so a failure here must not reach the shopper.
+          return false
+        })
     },
-    [client, cart.id]
-  )
+    [client, cart.id]
+  )
+  const choiceWrites = useMemo(
+    () => createLatestWriteQueue<Record<string, unknown>>(),
+    []
+  )
+  const enqueueChoiceWrite = useCallback(
+    (patch: Record<string, unknown>) => {
+      choiceWrites.push(patch, rememberChoice)
+    },
+    [choiceWrites, rememberChoice]
+  )
 
   // Shipping selection stays client state for the ORDER (no
   // addShippingMethod call, no metadata-clear updateCart: those wrote to the
@@ -1085,9 +1165,23 @@ export function useCheckoutOrchestration({
   // CHOICE, under our own key, so a reload restores it.
   const handleSelectShipping = useCallback(
     (id: string) => {
-      setShippingError(null)
-      setSelectedShippingMethod(id)
-      rememberChoice({ _checkout_shipping_option: id })
+      setShippingError(null)
+      setSelectedShippingMethod(id)
+
+      // The availability map came from the server with the checkout's first
+      // read. Selecting one of its answers is immediate and deterministic;
+      // no browser-side rule is being guessed. Older refreshes are invalidated
+      // before they can repaint a newer click.
+      const mappedPaymentMethods = paymentMethodsByShippingOption?.[id]
+      if (mappedPaymentMethods) {
+        paymentListingRequest.current += 1
+        setServerAvailablePaymentMethods(mappedPaymentMethods)
+      } else {
+        // Backward compatibility for hosts/platforms without the map: ask the
+        // rules endpoint about this prospective option immediately, without
+        // waiting for the preference write to make a round trip first.
+        void refreshPaymentMethods(id)
+      }
 
       // Optimistic shipping cost — paint the totals row immediately so
       // the customer sees the right number before any network call.
@@ -1107,14 +1201,20 @@ export function useCheckoutOrchestration({
       // our own note is cleared beside the state.
       setSelectedPickupPoint(null)
       setPickupKeys(null)
-      rememberChoice({
-        _checkout_shipping_option: id,
-        _checkout_pickup_point: null,
-        _checkout_pickup_keys: null,
-      })
-    },
-    [shippingMethods, calculatedPricesMap, rememberChoice]
-  )
+      enqueueChoiceWrite({
+        _checkout_shipping_option: id,
+        _checkout_pickup_point: null,
+        _checkout_pickup_keys: null,
+      })
+    },
+    [
+      shippingMethods,
+      calculatedPricesMap,
+      paymentMethodsByShippingOption,
+      refreshPaymentMethods,
+      enqueueChoiceWrite,
+    ]
+  )
 
   /**
    * The chosen pickup point, remembered the moment it is chosen. The keys
@@ -1126,13 +1226,13 @@ export function useCheckoutOrchestration({
     (point: PickupPoint | null, keys: PickupPointKeys | null) => {
       setSelectedPickupPoint(point)
       setPickupKeys(keys)
-      rememberChoice({
-        _checkout_pickup_point: point,
-        _checkout_pickup_keys: keys,
-      })
-    },
-    [rememberChoice]
-  )
+      enqueueChoiceWrite({
+        _checkout_pickup_point: point,
+        _checkout_pickup_keys: keys,
+      })
+    },
+    [enqueueChoiceWrite]
+  )
 
   // ── Delivery readiness ──────────────────────────────────────────────
   const selectedFulfillmentOptionId = useMemo(() => {
@@ -1169,19 +1269,18 @@ export function useCheckoutOrchestration({
       (cart?.shipping_methods?.length ?? 0) > 0) &&
     pickupSatisfied
 
-  // 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) {
+  // Reconcile paymentTab with currently-available methods. The server map
+  // changes the rendered list synchronously on a shipping click; this effect
+  // then moves selection and fee state onto the first valid tender. It does
+  // not wait for delivery readiness: a locker may still need its point, but
+  // its payment rule is already true.
+  useEffect(() => {
+    if (paymentTab === "cod" && !hasCod && hasCard) {
       handlePaymentTab("card")
     } else if (paymentTab === "card" && !hasCard && hasCod) {
       handlePaymentTab("cod")
     }
-  }, [deliveryReady, paymentTab, hasCard, hasCod, handlePaymentTab])
+  }, [paymentTab, hasCard, hasCod, handlePaymentTab])
 
   const handlePaymentElementChange = useCallback(
     (_e: { complete: boolean; selectedMethod: string | null }) => {
@@ -1789,8 +1888,9 @@ export function useCheckoutOrchestration({
     selectedPickup,
 
     // Payment
-    paymentTab,
-    hasCard,
+    paymentTab,
+    paymentMethodOrder,
+    hasCard,
     hasCod,
     cardId,
     /** The store's own Stripe, off the card entry — what `PaymentWrapper`

package/src/locales/bg.ts

@@ -182,12 +182,12 @@ export const bg: StorefrontLocale = {
     remove: "Премахни",
     secureCheckout: "Защитено плащане",
 
-    giftCard: "Карта за подарък",
-    giftCardSub: "Използвайте карта за подарък",
+    giftCard: "Подаръчен ваучер",
+    giftCardSub: "Въведете код за ваучер",
     giftCardPlaceholder: "GIFT-XXXX-XXXX",
-    giftCardApplied: "Карти за подарък",
+    giftCardApplied: "Подаръчни ваучери",
     giftCardRemaining: "Остава за плащане",
-    giftCardEnding: "Карта, завършваща на",
+    giftCardEnding: "Ваучер, завършващ на",
 
     companyInvoice: "Фактура за фирма",
     companyName: "Име на фирма",