create-brainerce-store 1.71.0 → 1.72.0

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

@@ -43,6 +43,7 @@ function CheckoutContent() {
   const currency = useCurrency();
   const t = useTranslations('checkout');
   const tc = useTranslations('common');
+  const tr = useTranslations('reservation');
 
   const [step, setStep] = useState<CheckoutStep>('address');
   const [checkout, setCheckout] = useState<Checkout | null>(null);
@@ -70,6 +71,30 @@ function CheckoutContent() {
   const [customFieldValues, setCustomFieldValues] = useState<Record<string, unknown>>({});
   const [customFieldsLoading, setCustomFieldsLoading] = useState(false);
 
+  // ---- Reservation expiry blocks payment ----
+  //
+  // When the reservation window runs out the held stock goes back on sale, so
+  // the amount and the line items on this page may no longer be deliverable.
+  // Payment is blocked until the shopper revisits the cart. Both pieces of
+  // state key on the reservation's `expiresAt` rather than a bare boolean, so
+  // the block survives a remount of the countdown and the ref stops the cart
+  // refresh from looping. This page does not refetch the checkout, so the
+  // block stands for the rest of the session once it closes.
+  const reservationExpiresAt = checkout?.reservation?.expiresAt ?? null;
+  const handledExpiryRef = useRef<string | null>(null);
+  const [expiredWindow, setExpiredWindow] = useState<string | null>(null);
+  const reservationExpired = expiredWindow !== null && expiredWindow === reservationExpiresAt;
+
+  const handleReservationExpired = useCallback(() => {
+    if (!reservationExpiresAt) return;
+    setExpiredWindow(reservationExpiresAt);
+    if (handledExpiryRef.current === reservationExpiresAt) return;
+    handledExpiryRef.current = reservationExpiresAt;
+    // Keep the header badge honest: the server may have dropped lines that
+    // are no longer purchasable.
+    void refreshCart();
+  }, [reservationExpiresAt, refreshCart]);
+
   // `begin_checkout` — fired once the cart is loaded, guarded by a ref so a
   // re-render (or the shopper returning from a canceled payment) doesn't
   // report a second checkout start for the same cart.
@@ -528,9 +553,24 @@ function CheckoutContent() {
         </div>
       )}
 
-      {/* Reservation countdown */}
+      {/* Reservation countdown. onExpire is what blocks payment below. */}
       {checkout?.reservation?.hasReservation && (
-        <ReservationCountdown reservation={checkout.reservation} className="mb-6" />
+        <ReservationCountdown
+          reservation={checkout.reservation}
+          onExpire={handleReservationExpired}
+          className="mb-6"
+        />
+      )}
+
+      {/* Expired reservation: payment is off the table until the cart is
+          reviewed, so say so on every step, not only on the payment step. */}
+      {reservationExpired && (
+        <div className="bg-destructive/10 border-destructive/20 text-destructive mb-6 rounded-lg border px-4 py-3 text-sm">
+          <p>{tr('expiredCheckout')}</p>
+          <Link href="/cart" className="mt-2 inline-flex font-medium underline">
+            {tr('backToCart')}
+          </Link>
+        </div>
       )}
 
       {/* Step indicator */}
@@ -763,7 +803,23 @@ function CheckoutContent() {
                 )}
               </div>
 
-              <PaymentStep checkoutId={checkout.id} />
+              {/* Never mount the payment form on an expired reservation: the
+                  stock behind these lines is back on sale, so a charge here
+                  can take money for something that cannot ship. */}
+              {reservationExpired ? (
+                <div className="border-border rounded-lg border px-4 py-6 text-center">
+                  <p className="text-foreground text-sm font-medium">{tr('expired')}</p>
+                  <p className="text-muted-foreground mt-1 text-sm">{tr('expiredCheckout')}</p>
+                  <Link
+                    href="/cart"
+                    className="bg-primary text-primary-foreground mt-4 inline-flex items-center rounded px-6 py-3 text-sm font-medium transition-opacity hover:opacity-90"
+                  >
+                    {tr('backToCart')}
+                  </Link>
+                </div>
+              ) : (
+                <PaymentStep checkoutId={checkout.id} />
+              )}
             </div>
           )}
         </div>

package/templates/nextjs/base/src/app/order-confirmation/page.tsx

@@ -32,10 +32,29 @@ function OrderConfirmationContent() {
       try {
         const client = getClient();
 
-        // Clear cart state after successful payment
-        client.handlePaymentSuccess(checkoutId!);
+        // Clear cart state after successful payment. handlePaymentSuccess is
+        // SYNCHRONOUS: it returns the outcome rather than a promise, so there
+        // is nothing to await. Read the result, then refresh the cart AFTER
+        // it, or the header badge can be repopulated from the pre-clear cart.
+        //
+        //   mode 'full'    - whole cart cleared
+        //   mode 'partial' - only the purchased items were removed (partial
+        //                    checkout); whatever is left is still for sale
+        //   mode 'none'    - nothing to clear. Usually the SDK's idempotency
+        //                    guard: React Strict Mode runs this effect twice
+        //                    in development, and a refresh of this URL hits it
+        //                    too. On a good order this is expected, so it must
+        //                    never become a warning to the shopper.
+        const clearResult = client.handlePaymentSuccess(checkoutId!);
         await refreshCart();
 
+        if (!clearResult.cleared && clearResult.mode !== 'none') {
+          // A clear that neither succeeded nor was skipped leaves purchased
+          // items in the badge. Nothing the shopper can act on, but a silent
+          // gap here looks exactly like a working cart.
+          console.warn('Cart not cleared after payment:', clearResult);
+        }
+
         // For redirect-based payment providers, the customer returns with
         // provider params in the URL — CardCom: lowprofilecode; PayPal:
         // token + PayerID. Send these to the backend for server-side

package/templates/nextjs/base/src/components/account/order-history.tsx

@@ -9,35 +9,29 @@ import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
 import { cn } from '@/core/lib/utils';
 import { OrderCustomizations } from './order-customizations';
-import { OrderStatusTimeline } from './order-status-timeline';
+import { OrderStatusTimeline, ORDER_STATUS_LABEL_KEYS } from './order-status-timeline';
 import { OrderShippingBlock } from './order-shipping-block';
 import { OrderPaymentBlock } from './order-payment-block';
 
-const STATUS_CONFIG: Record<OrderStatus, { labelKey: string; className: string }> = {
-  pending: {
-    labelKey: 'statusPending',
-    className: 'bg-yellow-100 text-yellow-800 dark:bg-yellow-950/30 dark:text-yellow-400',
-  },
-  processing: {
-    labelKey: 'statusProcessing',
-    className: 'bg-blue-100 text-blue-800 dark:bg-blue-950/30 dark:text-blue-400',
-  },
-  shipped: {
-    labelKey: 'statusShipped',
-    className: 'bg-purple-100 text-purple-800 dark:bg-purple-950/30 dark:text-purple-400',
-  },
-  delivered: {
-    labelKey: 'statusDelivered',
-    className: 'bg-green-100 text-green-800 dark:bg-green-950/30 dark:text-green-400',
-  },
-  cancelled: {
-    labelKey: 'statusCancelled',
-    className: 'bg-red-100 text-red-800 dark:bg-red-950/30 dark:text-red-400',
-  },
-  refunded: {
-    labelKey: 'statusRefunded',
-    className: 'bg-orange-100 text-orange-800 dark:bg-orange-950/30 dark:text-orange-400',
-  },
+/**
+ * Badge colour per order status. The API sends the status UPPERCASE and
+ * verbatim, so these keys are uppercase too. Do NOT lowercase `order.status`
+ * before the lookup: every row would miss and render as "Pending".
+ * Labels come from ORDER_STATUS_LABEL_KEYS so the two stay in step.
+ */
+const STATUS_STYLES: Record<OrderStatus, string> = {
+  DRAFT: 'bg-muted text-muted-foreground',
+  PENDING: 'bg-yellow-100 text-yellow-800 dark:bg-yellow-950/30 dark:text-yellow-400',
+  PROCESSING: 'bg-blue-100 text-blue-800 dark:bg-blue-950/30 dark:text-blue-400',
+  ON_HOLD: 'bg-amber-100 text-amber-800 dark:bg-amber-950/30 dark:text-amber-400',
+  PAID: 'bg-emerald-100 text-emerald-800 dark:bg-emerald-950/30 dark:text-emerald-400',
+  SHIPPED: 'bg-purple-100 text-purple-800 dark:bg-purple-950/30 dark:text-purple-400',
+  DELIVERED: 'bg-green-100 text-green-800 dark:bg-green-950/30 dark:text-green-400',
+  COMPLETED: 'bg-green-100 text-green-800 dark:bg-green-950/30 dark:text-green-400',
+  FULFILLED: 'bg-teal-100 text-teal-800 dark:bg-teal-950/30 dark:text-teal-400',
+  CANCELLED: 'bg-red-100 text-red-800 dark:bg-red-950/30 dark:text-red-400',
+  REFUNDED: 'bg-orange-100 text-orange-800 dark:bg-orange-950/30 dark:text-orange-400',
+  PARTIALLY_REFUNDED: 'bg-orange-100 text-orange-800 dark:bg-orange-950/30 dark:text-orange-400',
 };
 
 interface OrderHistoryProps {
@@ -82,8 +76,8 @@ function OrderCard({ order }: { order: Order }) {
   const t = useTranslations('account');
   const tc = useTranslations('common');
   const [expanded, setExpanded] = useState(false);
-  const statusConfig =
-    STATUS_CONFIG[order.status?.toLowerCase() as OrderStatus] || STATUS_CONFIG.pending;
+  const statusLabelKey = ORDER_STATUS_LABEL_KEYS[order.status] || 'statusPending';
+  const statusClassName = STATUS_STYLES[order.status] || STATUS_STYLES.PENDING;
   const currency = useCurrency(order.currency);
   const totalAmount = order.totalAmount || order.total || '0';
 
@@ -103,18 +97,10 @@ function OrderCard({ order }: { order: Order }) {
             <span
               className={cn(
                 'inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium',
-                statusConfig.className
+                statusClassName
               )}
             >
-              {t(
-                statusConfig.labelKey as
-                  | 'statusPending'
-                  | 'statusProcessing'
-                  | 'statusShipped'
-                  | 'statusDelivered'
-                  | 'statusCancelled'
-                  | 'statusRefunded'
-              )}
+              {t(statusLabelKey)}
             </span>
           </div>
           <div className="text-muted-foreground mt-1 flex items-center gap-4 text-xs">
@@ -125,7 +111,7 @@ function OrderCard({ order }: { order: Order }) {
                     month: 'short',
                     day: 'numeric',
                   })
-                : '—'}
+                : ''}
             </span>
             <span>
               {order.items.length} {order.items.length === 1 ? tc('item') : tc('items')}

package/templates/nextjs/base/src/components/account/order-status-timeline.tsx

@@ -4,21 +4,40 @@ import type { Order, OrderStatus } from 'brainerce';
 import { useTranslations } from '@/core/lib/translations';
 import { cn } from '@/core/lib/utils';
 
-const STATUS_KEYS: Record<
-  OrderStatus,
+/**
+ * Message key for every order status the API can return.
+ *
+ * The API sends these values UPPERCASE and verbatim (`PENDING`, `ON_HOLD`,
+ * ...). Never lowercase them before the lookup: a lowercase key silently
+ * misses and every row falls through to the default label.
+ */
+export type OrderStatusLabelKey =
+  | 'statusDraft'
   | 'statusPending'
   | 'statusProcessing'
+  | 'statusOnHold'
+  | 'statusPaid'
   | 'statusShipped'
   | 'statusDelivered'
+  | 'statusCompleted'
+  | 'statusFulfilled'
   | 'statusCancelled'
   | 'statusRefunded'
-> = {
-  pending: 'statusPending',
-  processing: 'statusProcessing',
-  shipped: 'statusShipped',
-  delivered: 'statusDelivered',
-  cancelled: 'statusCancelled',
-  refunded: 'statusRefunded',
+  | 'statusPartiallyRefunded';
+
+export const ORDER_STATUS_LABEL_KEYS: Record<OrderStatus, OrderStatusLabelKey> = {
+  DRAFT: 'statusDraft',
+  PENDING: 'statusPending',
+  PROCESSING: 'statusProcessing',
+  ON_HOLD: 'statusOnHold',
+  PAID: 'statusPaid',
+  SHIPPED: 'statusShipped',
+  DELIVERED: 'statusDelivered',
+  COMPLETED: 'statusCompleted',
+  FULFILLED: 'statusFulfilled',
+  CANCELLED: 'statusCancelled',
+  REFUNDED: 'statusRefunded',
+  PARTIALLY_REFUNDED: 'statusPartiallyRefunded',
 };
 
 interface OrderStatusTimelineProps {
@@ -35,7 +54,7 @@ export function OrderStatusTimeline({ history, className }: OrderStatusTimelineP
       <p className="text-foreground mb-2 text-sm font-medium">{t('statusTimeline')}</p>
       <ol className="space-y-1.5">
         {history.map((entry, idx) => {
-          const key = STATUS_KEYS[entry.status] || 'statusPending';
+          const key = ORDER_STATUS_LABEL_KEYS[entry.status] || 'statusPending';
           const when = new Date(entry.at);
           const whenStr = isNaN(when.getTime())
             ? entry.at
@@ -56,7 +75,7 @@ export function OrderStatusTimeline({ history, className }: OrderStatusTimelineP
               />
               <span className="text-foreground font-medium">{t(key)}</span>
               <span className="text-muted-foreground">· {whenStr}</span>
-              {entry.note && <span className="text-muted-foreground truncate">— {entry.note}</span>}
+              {entry.note && <span className="text-muted-foreground truncate">({entry.note})</span>}
             </li>
           );
         })}

package/templates/nextjs/base/src/core/hooks/use-cart-page.ts

@@ -1,8 +1,9 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import type {
   Cart,
+  CartItem,
   CartRecommendationsResponse,
   CartUpgradesResponse,
   CartBundlesResponse,
@@ -21,6 +22,26 @@ export interface UseCartPageResult {
   upgrades: CartUpgradesResponse | null;
   /** Bundle offers matching the current cart. */
   bundles: CartBundlesResponse | null;
+  /**
+   * True once the stock reservation on this cart has run out and the refreshed
+   * cart still carries the same expired window. Goes back to false on its own
+   * if the server hands back a fresh reservation.
+   */
+  reservationExpired: boolean;
+  /** Lines the server says cannot be bought right now (`isAvailable === false`). */
+  unavailableItems: CartItem[];
+  /**
+   * False while the reservation is expired or any line is unavailable. The
+   * proceed-to-checkout action must be genuinely disabled on false, not just
+   * styled as disabled.
+   */
+  canProceedToCheckout: boolean;
+  /**
+   * Hand this to `<ReservationCountdown onExpire={...}>`. It refreshes the
+   * cart once per expiry window: the server, not the client timer, decides
+   * what is still purchasable.
+   */
+  onReservationExpired: () => void;
 }
 
 /**
@@ -54,5 +75,53 @@ export function useCartPage(): UseCartPageResult {
       .catch(() => {});
   }, [cart?.id, cart?.items.length]);
 
-  return { cart, cartLoading, refreshCart, itemCount, cartRecs, upgrades, bundles };
+  // ---- Reservation expiry ----
+  //
+  // The countdown component only ticks. Expiry is handled here, once, so all
+  // three design variants share one behaviour and a user redesigning the
+  // countdown cannot delete the gate along with the markup.
+  //
+  // Both pieces of state key on the reservation's `expiresAt`, which is the
+  // only stable identity a reservation window has:
+  //  - `handledExpiryRef` stops the refresh loop (refresh remounts the
+  //    countdown, which would otherwise report the same expiry again).
+  //  - comparing `expiredWindow` to the CURRENT `expiresAt` means a server
+  //    that renews the reservation clears the expired state by itself.
+  const reservationExpiresAt = cart?.reservation?.expiresAt ?? null;
+  const handledExpiryRef = useRef<string | null>(null);
+  const [expiredWindow, setExpiredWindow] = useState<string | null>(null);
+
+  const onReservationExpired = useCallback(() => {
+    if (!reservationExpiresAt) return;
+    setExpiredWindow(reservationExpiresAt);
+    if (handledExpiryRef.current === reservationExpiresAt) return;
+    handledExpiryRef.current = reservationExpiresAt;
+    // Re-read from the server: it is the source of truth for what survived
+    // the released reservation. `isAvailable` on each line comes back updated.
+    void refreshCart();
+  }, [reservationExpiresAt, refreshCart]);
+
+  const reservationExpired =
+    expiredWindow !== null &&
+    expiredWindow === reservationExpiresAt &&
+    cart?.reservation?.hasReservation === true;
+
+  const unavailableItems = cart?.items.filter((item) => item.isAvailable === false) ?? [];
+
+  const canProceedToCheckout =
+    !!cart && cart.items.length > 0 && !reservationExpired && unavailableItems.length === 0;
+
+  return {
+    cart,
+    cartLoading,
+    refreshCart,
+    itemCount,
+    cartRecs,
+    upgrades,
+    bundles,
+    reservationExpired,
+    unavailableItems,
+    canProceedToCheckout,
+    onReservationExpired,
+  };
 }

package/templates/nextjs/base/src/core/lib/auth.ts

@@ -1,15 +1,21 @@
 /**
- * Client-side auth helpers that call the BFF proxy API routes.
- * All mutating requests include the CSRF header.
- * The token is managed server-side via httpOnly cookies — never exposed to JS.
+ * Client-side auth helpers.
+ *
+ * Everything the SDK covers goes through an SDK method. Never hand-build a
+ * REST path: the SDK owns the URL shape, and a string built here silently
+ * rots the day a route moves. `getClient()` is configured with
+ * `baseUrl: '/api/store'` + `proxyMode`, so each call still lands on the
+ * same-origin BFF proxy, which adds the Authorization header from the
+ * httpOnly cookie and strips the token out of the response. The SDK adds the
+ * CSRF header the proxy requires on every non-GET request.
+ *
+ * Only the routes with no SDK equivalent are plain fetches: `/api/auth/me`,
+ * `/api/auth/logout` and `/api/auth/reset-password` are this app's own Next
+ * route handlers, not Brainerce endpoints.
+ *
+ * The token is managed server-side via httpOnly cookies, never exposed to JS.
  */
-
-// Read either env var name. The new one is preferred; the old one is a soft
-// alias kept for backwards compatibility — both are accepted by the SDK.
-const CONNECTION_ID =
-  process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID ||
-  process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID ||
-  '';
+import { getClient } from '@/core/lib/brainerce';
 
 const CSRF_HEADERS: Record<string, string> = {
   'Content-Type': 'application/json',
@@ -67,19 +73,19 @@ async function handleResponse<T>(response: Response): Promise<T> {
 }
 
 /**
- * Login via BFF proxy. The proxy sets the httpOnly cookie on success.
+ * Login via the SDK, routed through the BFF proxy, which sets the httpOnly
+ * cookie on success and strips the token from the response. The narrow
+ * `LoginResult` return type is deliberate: the SDK's own response type
+ * declares a `token`, but the proxy removes it before it reaches the browser,
+ * so nothing here should read one.
  */
 export async function proxyLogin(email: string, password: string): Promise<LoginResult> {
-  const response = await fetch(`/api/store/api/vc/${CONNECTION_ID}/customers/login`, {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-    body: JSON.stringify({ email, password }),
-  });
-  return handleResponse<LoginResult>(response);
+  return getClient().loginCustomer(email, password);
 }
 
 /**
- * Register via BFF proxy. The proxy sets the httpOnly cookie on success.
+ * Register via the SDK, routed through the BFF proxy, which sets the httpOnly
+ * cookie on success.
  */
 export async function proxyRegister(data: {
   firstName: string;
@@ -96,12 +102,7 @@ export async function proxyRegister(data: {
   birthMonth?: number;
   birthDay?: number;
 }): Promise<RegisterResult> {
-  const response = await fetch(`/api/store/api/vc/${CONNECTION_ID}/customers/register`, {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-    body: JSON.stringify(data),
-  });
-  return handleResponse<RegisterResult>(response);
+  return getClient().registerCustomer(data);
 }
 
 /**
@@ -123,28 +124,20 @@ export async function proxyLogout(): Promise<void> {
 }
 
 /**
- * Verify email via BFF proxy. The auth token is in the httpOnly cookie (set during login/register).
- * The proxy adds the Authorization header automatically.
+ * Verify email via the SDK. No token argument is passed: the auth token lives
+ * in the httpOnly cookie (set during login/register) and the proxy attaches
+ * the Authorization header. The SDK skips its own token check in proxy mode.
  */
 export async function proxyVerifyEmail(code: string): Promise<VerifyEmailResult> {
-  const response = await fetch(`/api/store/api/vc/${CONNECTION_ID}/customers/verify-email`, {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-    body: JSON.stringify({ code }),
-  });
-  return handleResponse<VerifyEmailResult>(response);
+  return getClient().verifyEmail(code);
 }
 
 /**
- * Resend verification email via BFF proxy.
- * Uses the auth token from the httpOnly cookie.
+ * Resend the verification email via the SDK. Uses the auth token from the
+ * httpOnly cookie, added by the proxy. Rate limited to 3 requests per hour.
  */
 export async function proxyResendVerification(): Promise<{ message: string }> {
-  const response = await fetch(`/api/store/api/vc/${CONNECTION_ID}/customers/resend-verification`, {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-  });
-  return handleResponse<{ message: string }>(response);
+  return getClient().resendVerificationEmail();
 }
 
 /**

package/templates/nextjs/base/src/core/lib/brainerce.ts.ejs

@@ -37,22 +37,11 @@ export function initClientWithLocale(locale: string): BrainerceClient {
 }
 <% } %>
 
-// Cart ID helpers (not a security token — safe in localStorage)
-const CART_ID_KEY = 'brainerce_cart_id';
-
-export function getStoredCartId(): string | null {
-  if (typeof window === 'undefined') return null;
-  return localStorage.getItem(CART_ID_KEY);
-}
-
-export function setStoredCartId(cartId: string | null): void {
-  if (typeof window === 'undefined') return;
-  if (cartId) {
-    localStorage.setItem(CART_ID_KEY, cartId);
-  } else {
-    localStorage.removeItem(CART_ID_KEY);
-  }
-}
+// Cart identity belongs to the SDK. It owns the guest cart id, the session
+// cart and the logged-in cart cache, and `smartGetCart()` resolves the right
+// one. Do not mirror a cart id into localStorage here: a second copy drifts
+// out of step on login, cart merge and post-payment clear, and the SDK will
+// not read it back.
 
 // Initialize client (no token hydration — auth handled by httpOnly cookie)
 export function initClient(): BrainerceClient {

package/templates/nextjs/base/src/core/providers/store-provider.tsx.ejs

@@ -3,7 +3,7 @@
 import React, { createContext, useContext, useEffect, useState, useCallback } from 'react';
 import type { Cart, CustomerProfile } from 'brainerce';
 import { getCartTotals } from 'brainerce';
-import { getClient, initClient, setStoredCartId } from '@/core/lib/brainerce';
+import { getClient, initClient } from '@/core/lib/brainerce';
 import { pickPublicStoreInfo, type PublicStoreInfo } from '@/core/lib/store-info';
 import { checkAuthStatus, proxyLogout } from '@/core/lib/auth';
 <% if (i18nEnabled) { %>
@@ -170,13 +170,10 @@ export function StoreProvider({
     try {
       setCartLoading(true);
       const client = getClient();
+      // The SDK owns cart identity: smartGetCart() picks the guest, session or
+      // customer cart on its own. Never mirror the id into localStorage.
       const c = await client.smartGetCart();
       setCart(c);
-
-      // Persist server cart ID
-      if (c && c.id) {
-        setStoredCartId(c.id);
-      }
     } catch (err) {
       console.error('Failed to load cart:', err);
     } finally {

package/templates/nextjs/base/src/ui/cart/cart-item.tsx

@@ -30,6 +30,17 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   const unitPrice = parseFloat(item.unitPrice);
   const lineTotal = unitPrice * item.quantity;
 
+  // The server decides purchasability, per line. `isAvailable === false` means
+  // this line blocks checkout until it is removed, whether the stock ran out
+  // (a released reservation is the common cause) or the product/variant was
+  // withdrawn from sale. `unavailableReason` separates the two for the label.
+  const isUnavailable = item.isAvailable === false;
+  const unavailableLabel = isUnavailable
+    ? item.unavailableReason === 'OUT_OF_STOCK'
+      ? td('outOfStock')
+      : td('unavailable')
+    : null;
+
   async function handleQuantityChange(newQuantity: number) {
     if (newQuantity < 1 || updating) return;
 
@@ -83,6 +94,13 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
       <div className="min-w-0 flex-1">
         <h3 className="text-foreground truncate text-sm font-medium">{productName}</h3>
 
+        {/* Availability badge. This line blocks checkout while it shows. */}
+        {unavailableLabel && (
+          <span className="bg-destructive/10 text-destructive mt-1 inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium">
+            {unavailableLabel}
+          </span>
+        )}
+
         {/* Variant name */}
         {variantName && <p className="text-muted-foreground mt-1 text-xs">{variantName}</p>}
 
@@ -116,7 +134,7 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
             <button
               type="button"
               onClick={() => handleQuantityChange(item.quantity + 1)}
-              disabled={updating}
+              disabled={updating || isUnavailable}
               className="text-foreground hover:bg-muted px-2 py-1 text-sm transition-colors disabled:cursor-not-allowed disabled:opacity-40"
               aria-label={td('increaseQuantity')}
             >

package/templates/nextjs/base/src/ui/cart/cart-view.tsx

@@ -21,7 +21,20 @@ import { useTranslations } from '@/core/lib/translations';
 export function CartView() {
   const t = useTranslations('cart');
   const tc = useTranslations('common');
-  const { cart, cartLoading, refreshCart, itemCount, cartRecs, upgrades, bundles } = useCartPage();
+  const tr = useTranslations('reservation');
+  const {
+    cart,
+    cartLoading,
+    refreshCart,
+    itemCount,
+    cartRecs,
+    upgrades,
+    bundles,
+    reservationExpired,
+    unavailableItems,
+    canProceedToCheckout,
+    onReservationExpired,
+  } = useCartPage();
 
   if (cartLoading) {
     return (
@@ -55,9 +68,14 @@ export function CartView() {
         {t('title')} ({itemCount} {itemCount === 1 ? tc('item') : tc('items')})
       </h1>
 
-      {/* Reservation countdown */}
+      {/* Reservation countdown. onExpire refreshes the cart and closes the
+          checkout gate below. Passing it is what makes expiry mean anything. */}
       {cart.reservation?.hasReservation && (
-        <ReservationCountdown reservation={cart.reservation} className="mb-6" />
+        <ReservationCountdown
+          reservation={cart.reservation}
+          onExpire={onReservationExpired}
+          className="mb-6"
+        />
       )}
 
       <div className="grid grid-cols-1 gap-8 lg:grid-cols-3">
@@ -113,9 +131,27 @@ export function CartView() {
             <FreeShippingBar className="mb-4" />
             <CartSummary />
 
-            <Button asChild size="lg" className="mt-6 w-full rounded px-6 text-sm">
-              <Link href="/checkout">{t('proceedToCheckout')}</Link>
-            </Button>
+            {/* Proceed to checkout. When the gate is closed this must be a
+                real disabled control, never a styled-down link: an anchor
+                ignores `disabled` and would still navigate. */}
+            {canProceedToCheckout ? (
+              <Button asChild size="lg" className="mt-6 w-full rounded px-6 text-sm">
+                <Link href="/checkout">{t('proceedToCheckout')}</Link>
+              </Button>
+            ) : (
+              <>
+                <Button disabled size="lg" className="mt-6 w-full rounded px-6 text-sm">
+                  {t('proceedToCheckout')}
+                </Button>
+                <p className="text-destructive mt-2 text-xs">
+                  {unavailableItems.length > 0
+                    ? t('unavailableItemsHint')
+                    : reservationExpired
+                      ? tr('expiredHint')
+                      : null}
+                </p>
+              </>
+            )}
 
             <Link
               href="/products"