@cartbase/storefront 0.20.0 → 0.20.1

package/src/cart-drawer/context.tsx

@@ -1,778 +1,778 @@
-"use client"
-
-import {
-  createContext,
-  startTransition,
-  useCallback,
-  useContext,
-  useEffect,
-  useOptimistic,
-  useRef,
-  useState,
-  type ReactNode,
-} from "react"
-
-import {
-  addLineItem as sdkAddLineItem,
-  createCart as sdkCreateCart,
-  deleteLineItem as sdkDeleteLineItem,
-  retrieveCart as sdkRetrieveCart,
-  updateLineItem as sdkUpdateLineItem,
-  type Cart,
-  type CartLineItem,
-} from "../api/carts"
-import type { StorefrontClient } from "../api/http"
-import { productItemCount } from "../lib/cart-helpers"
-import { defaultCartDrawerLabels, type CartDrawerLabels } from "./labels"
-import { useLocaleArea } from "../locales/context"
-import { createCartMutationQueue, type CartMutationQueue } from "./mutation-queue"
-
-/**
- * Cart drawer context — open state + cart snapshot + labels + link hrefs.
- *
- * Stores wrap their root layout with `<CartDrawerProvider client={…}>`,
- * handing either the server-read cart (`cart`) or the cart id (`cartId`,
- * read in the browser on mount). The provider manages open/close state,
- * auto-opens when the item count rises, locks body scroll while open, and
- * closes on escape.
- *
- * THE INSTANT CART. The cart exposed via `useCartDrawer().cart` is wrapped
- * in React 19's `useOptimistic`: every change (`addItem`, `addLine`,
- * `updateQuantity`, `removeItem`) shows at React update speed and the
- * platform confirms behind it; a failure reverts on its own, because the
- * confirmed snapshot never moved. Every mutation answers with the FULL
- * decorated cart (totals, gift cards: SERVER truth), which becomes the new
- * confirmed snapshot, so no page refresh is needed for the drawer to
- * settle.
- *
- * The changes reach the platform through ONE queue (`mutation-queue.ts`),
- * one call at a time, each reading the cart as the answer before it left
- * it: two answers can never cross and overwrite each other, a second add
- * never creates a second cart, and fast quantity clicks on one line are
- * combined into the number the shopper stopped at. A line added a moment
- * ago carries `pending: true` (`isPendingLine`) and a placeholder id until
- * the platform confirms it; a change made to it before then is held in the
- * queue and sent to the real line.
- *
- * Ported from `@1click/ui/src/cart-drawer/context.tsx` (v2.3.1). Cartbase
- * data seam: the Medusa server actions are replaced by
- * `@cartbase/storefront/api/carts` calls made through a `StorefrontClient`
- * passed to the provider. Amounts are EUR decimal major units.
- *
- * Every failed change flows through `onOptimisticError` with per-action
- * context. Wire it to the store's ops logging; the console.error stays
- * regardless.
- */
-
-type CartDrawerHrefs = {
-  /** Href for the checkout button in the sticky footer */
-  checkout: string
-  /** Href for the "browse products" CTA on the empty state */
-  browse: string
-  /** Prefix for product links — full href is `${productPrefix}/${handle}` */
-  productPrefix: string
-}
-
-const defaultHrefs: CartDrawerHrefs = {
-  checkout: "/checkout",
-  browse: "/store",
-  productPrefix: "/products",
-}
-
-/** Context payload passed to `onOptimisticError` for every failed mutation. */
-export type OptimisticCartError = {
-  actionType: OptimisticCartAction["type"]
-  error: unknown
-  /** Structured per-action fields (quantity, line_id, variant/product ids). */
-  context: Record<string, unknown>
-}
-
-/**
- * Display fields an "add" action carries so the drawer can render the row
- * immediately, before the server confirms.
- */
-export type OptimisticAddDisplay = {
-  product_id?: string
-  product_title?: string
-  product_handle?: string
-  thumbnail?: string | null
-  variant_title?: string | null
-  /** Per-unit price in EUR major units. total = price × qty. */
-  unit_price?: number
-}
-
-/**
- * Optimistic action shapes — what callers can dispatch to update the
- * cart UI ahead of the server confirmation.
- */
-export type OptimisticCartAction =
-  | ({
-      type: "add"
-      /** Variant being added. We use this to merge with existing lines. */
-      variant_id: string
-      quantity: number
-    } & OptimisticAddDisplay)
-  | {
-      type: "remove"
-      lineId: string
-    }
-  | {
-      type: "update_quantity"
-      lineId: string
-      quantity: number
-    }
-
-/** What an add answers: the confirmed cart, or why it was refused. */
-export type CartMutationResult =
-  | { ok: true; cart: Cart }
-  | {
-      ok: false
-      /** The platform's refusal (a `StoreApiError`: `code` names it, e.g. `insufficient_inventory`). */
-      error: unknown
-    }
-
-/** The id prefix of a line the platform has not confirmed yet. */
-const PENDING_PREFIX = "optimistic-"
-
-/**
- * A cart that can still be shopped. A completed cart is an order now: the
- * platform still answers it, lines and all, but refuses every change to it.
- */
-export function isLiveCart(cart: Cart | null | undefined): cart is Cart {
-  return Boolean(cart && !cart.completed_at)
-}
-
-/** The platform's answer that the cart a change was aimed at is over (ordered, or gone). */
-export function isEndedCartError(err: unknown): boolean {
-  const code = (err as { code?: unknown } | null)?.code
-  return code === "cart_completed" || code === "cart_not_found"
-}
-
-/**
- * A line the platform has not confirmed yet: it was added a moment ago and
- * carries a placeholder id. Its quantity and removal work already (the
- * provider holds them until the line exists); anything that needs the real
- * line (a server read keyed by the line id) should wait until this is false.
- */
-export function isPendingLine(line: Pick<CartLineItem, "id">): boolean {
-  return (line as { pending?: unknown }).pending === true || line.id.startsWith(PENDING_PREFIX)
-}
-
-/** The variant a placeholder line id stands for; null for a real line id. */
-function pendingVariant(lineId: string): string | null {
-  return lineId.startsWith(PENDING_PREFIX) ? lineId.slice(PENDING_PREFIX.length) : null
-}
-
-type CartDrawerContextValue = {
-  isOpen: boolean
-  open: () => void
-  close: () => void
-  toggle: () => void
-  /** Cart snapshot AFTER any pending optimistic updates. */
-  cart: Cart | null
-  /**
-   * Dispatch an optimistic update. MUST be called inside a
-   * `startTransition` (React requirement for useOptimistic setters
-   * outside Action props). Prefer `applyOptimistic`.
-   */
-  dispatchOptimistic: (action: OptimisticCartAction) => void
-  /**
-   * Dispatches the optimistic action AND awaits the provided server
-   * mutation inside a single transition. For a store that owns the server
-   * call itself (a Next.js server action); the built-in methods below cover
-   * the SDK-wired path and are the fast one.
-   */
-  applyOptimistic: (
-    action: OptimisticCartAction,
-    serverAction: () => Promise<unknown>
-  ) => void
-  /**
-   * Add a variant: the line shows at once, the platform confirms behind it.
-   * Answers with the confirmed cart or the refusal (require the provider's
-   * `client` prop).
-   */
-  addLine: (
-    variantId: string,
-    quantity?: number,
-    display?: OptimisticAddDisplay
-  ) => Promise<CartMutationResult>
-  /** `addLine`, answering only whether it was confirmed. */
-  addItem: (
-    variantId: string,
-    quantity?: number,
-    display?: OptimisticAddDisplay
-  ) => Promise<boolean>
-  /**
-   * Set a line's quantity (0 deletes, the Cartbase contract). Every click
-   * shows at once; fast clicks on one line send the last number.
-   */
-  updateQuantity: (lineId: string, quantity: number) => Promise<boolean>
-  removeItem: (lineId: string) => Promise<boolean>
-  /** Re-read the decorated cart (totals/gift-card tender are live per read). */
-  refresh: () => Promise<void>
-  /**
-   * The cart is over (the order was placed): the drawer empties and the
-   * store's `onCartEnd` clears its cookie. The checkout calls it; the next
-   * add starts a new cart.
-   */
-  forget: () => Promise<void>
-  /** True when the provider was given a client, so the methods above reach the platform. */
-  canMutate: boolean
-  labels: CartDrawerLabels
-  hrefs: CartDrawerHrefs
-}
-
-const CartDrawerContext = createContext<CartDrawerContextValue>({
-  isOpen: false,
-  open: () => {},
-  close: () => {},
-  toggle: () => {},
-  cart: null,
-  dispatchOptimistic: () => {},
-  applyOptimistic: () => {},
-  addLine: async () => ({ ok: false, error: new Error("No CartDrawerProvider with a client is mounted") }),
-  addItem: async () => false,
-  updateQuantity: async () => false,
-  removeItem: async () => false,
-  refresh: async () => {},
-  forget: async () => {},
-  canMutate: false,
-  labels: defaultCartDrawerLabels,
-  hrefs: defaultHrefs,
-})
-
-export function useCartDrawer(): CartDrawerContextValue {
-  return useContext(CartDrawerContext)
-}
-
-/**
- * Reducer for the useOptimistic cart. Pure function. Returns the next
- * cart shape after applying the action. Falls back to a synthetic empty
- * cart when there's no current cart yet so optimistic adds work even on
- * first-add (the confirmed cart replaces it).
- *
- * A change aimed at a placeholder line also finds the real line of the
- * same variant: the confirmed cart can arrive while the change is still
- * pending, and the line must not come back or lose its new number.
- *
- * Exported for unit tests (pure logic, no React).
- */
-export function reduceCart(
-  current: Cart | null,
-  action: OptimisticCartAction
-): Cart | null {
-  if (!current) {
-    if (action.type !== "add") return current
-    return {
-      id: "optimistic-cart",
-      items: [makeOptimisticLine(action)],
-    } as unknown as Cart
-  }
-
-  switch (action.type) {
-    case "add": {
-      const items = current.items ?? []
-      const existing = items.find((i) => i.variant_id === action.variant_id)
-      if (existing) {
-        return {
-          ...current,
-          items: items.map((i) =>
-            i.variant_id === action.variant_id
-              ? {
-                  ...i,
-                  quantity: i.quantity + action.quantity,
-                  total:
-                    (i.unit_price ?? 0) * (i.quantity + action.quantity),
-                }
-              : i
-          ),
-        }
-      }
-      return {
-        ...current,
-        items: [...items, makeOptimisticLine(action)],
-      }
-    }
-    case "remove": {
-      const variant = pendingVariant(action.lineId)
-      return {
-        ...current,
-        items: (current.items ?? []).filter(
-          (i) => i.id !== action.lineId && !(variant && i.variant_id === variant)
-        ),
-      }
-    }
-    case "update_quantity": {
-      const variant = pendingVariant(action.lineId)
-      return {
-        ...current,
-        items: (current.items ?? []).map((i) =>
-          i.id === action.lineId || (variant && i.variant_id === variant)
-            ? {
-                ...i,
-                quantity: action.quantity,
-                total: (i.unit_price ?? 0) * action.quantity,
-              }
-            : i
-        ),
-      }
-    }
-  }
-}
-
-/**
- * Build a synthetic line item from an "add" action: a placeholder id and
- * `pending: true` (see `isPendingLine`). The confirmed cart replaces it.
- * Cast through `unknown` because `CartLineItem` has many fields we don't
- * have at click time (created_at, tax_lines, adjustments…) — the renderer
- * is lenient about missing optional fields.
- */
-export function makeOptimisticLine(
-  action: Extract<OptimisticCartAction, { type: "add" }>
-): CartLineItem {
-  const unitPrice = action.unit_price ?? 0
-  return {
-    id: `${PENDING_PREFIX}${action.variant_id}`,
-    pending: true,
-    variant_id: action.variant_id,
-    product_id: action.product_id,
-    product_title: action.product_title,
-    product_handle: action.product_handle,
-    thumbnail: action.thumbnail,
-    variant_title: action.variant_title,
-    quantity: action.quantity,
-    unit_price: unitPrice,
-    total: unitPrice * action.quantity,
-    original_total: unitPrice * action.quantity,
-  } as unknown as CartLineItem
-}
-
-/** The per-action fields every failure report carries. */
-function failureContext(action: OptimisticCartAction, err: unknown): Record<string, unknown> {
-  const err_ = err as { message?: string; name?: string; code?: string } | null
-  const ctx: Record<string, unknown> = { action_type: action.type }
-  if (action.type === "add") {
-    ctx.quantity = action.quantity
-    ctx.product_id = action.product_id
-    ctx.variant_id = action.variant_id
-  } else if (action.type === "remove") {
-    ctx.line_id = action.lineId
-  } else {
-    ctx.line_id = action.lineId
-    ctx.quantity = action.quantity
-  }
-  ctx.err_name = err_?.name
-  ctx.err_code = err_?.code
-  ctx.err_message = err_?.message ?? String(err)
-  return ctx
-}
-
-export function CartDrawerProvider({
-  cart,
-  client,
-  cartId,
-  onCartChange,
-  onCartEnd,
-  onOptimisticError,
-  labels: labelOverrides,
-  hrefs: hrefOverrides,
-  children,
-}: {
-  /**
-   * Server-fetched cart snapshot (RSC/server-action pattern). When the
-   * prop changes (e.g. after a router refresh) it becomes the confirmed
-   * snapshot, unless a change of the provider's own is still on its way.
-   * Leave it out and pass `client` + `cartId` to read the cart in the
-   * browser instead, so the page never waits for it.
-   */
-  cart?: Cart | null
-  /** StorefrontClient for the SDK-wired mutations (addLine/addItem/updateQuantity/removeItem/refresh). */
-  client?: StorefrontClient
-  /** Known cart id to retrieve when no `cart` snapshot is passed. */
-  cartId?: string | null
-  /**
-   * Fires with the decorated cart after every server-confirmed change,
-   * including first-add cart creation — persist `cart.id` (cookie/storage)
-   * here so the cart survives reloads.
-   */
-  onCartChange?: (cart: Cart) => void
-  /**
-   * Fires when the cart is over: the order was placed, or the platform
-   * answered that the stored cart is completed or gone. Clear the stored
-   * cart id (the cookie) here; the next add creates a new cart and
-   * `onCartChange` stores its id.
-   */
-  onCartEnd?: () => void
-  /** Ops funnel for every failed optimistic mutation (see module JSDoc). */
-  onOptimisticError?: (failure: OptimisticCartError) => void
-  /**
-   * Overrides. The default is the language mounted by
-   * `StorefrontLocaleProvider`, English when none is mounted, so a store
-   * that mounts its pack has nothing to hand over here (2026-09-14).
-   */
-  labels?: Partial<CartDrawerLabels>
-  hrefs?: Partial<CartDrawerHrefs>
-  children: ReactNode
-}) {
-  const [isOpen, setIsOpen] = useState(false)
-  const prevItemCount = useRef(0)
-
-  // The queue every SDK change goes through, and the latest confirmed cart
-  // it reads when a change's turn comes (state lags a render behind).
-  const queue = useRef<CartMutationQueue | null>(null)
-  if (!queue.current) queue.current = createCartMutationQueue()
-  // A completed cart is an order: the drawer never holds one.
-  const latest = useRef<Cart | null>(isLiveCart(cart) ? cart : null)
-
-  // The store's hooks, read through refs so an inline handler never re-runs an effect.
-  const cartEnded = useRef(onCartEnd)
-  cartEnded.current = onCartEnd
-
-  // Confirmed snapshot: seeded from the prop, replaced by every SDK
-  // mutation response and by prop updates from server refreshes.
-  const [serverCart, setServerCart] = useState<Cart | null>(latest.current)
-
-  /** The cart is over: the drawer empties and the store forgets the id. */
-  const end = useCallback(() => {
-    latest.current = null
-    startTransition(() => setServerCart(null))
-    try {
-      cartEnded.current?.()
-    } catch {
-      // A store's handler must never break the drawer.
-    }
-  }, [])
-
-  useEffect(() => {
-    if (cart === undefined) return
-    // A refresh carrying the cart as it was must not overwrite an answer
-    // still on its way; the queue's own answers are newer.
-    if (queue.current?.busy()) return
-    if (cart && !isLiveCart(cart)) {
-      end()
-      return
-    }
-    latest.current = cart
-    setServerCart(cart)
-  }, [cart, end])
-
-  // A confirmed cart becomes the snapshot inside a transition, so it lands
-  // together with the end of the change that asked for it and a pending
-  // line is never shown twice. A completed one ends the cart instead.
-  const adopt = useCallback(
-    (next: Cart) => {
-      if (!isLiveCart(next)) {
-        end()
-        return
-      }
-      latest.current = next
-      startTransition(() => setServerCart(next))
-    },
-    [end]
-  )
-
-  // Client+cartId mode: read the cart on mount, through the queue, so an
-  // add made before the read answers goes to this cart, not a new one.
-  useEffect(() => {
-    if (cart !== undefined || !client || !cartId) return
-    let cancelled = false
-    void queue.current!.run(async () => {
-      try {
-        const res = await sdkRetrieveCart(client, cartId)
-        if (!cancelled) adopt(res.cart)
-      } catch (err) {
-        // A stored id the platform no longer knows: forget it. Any other
-        // failure (a network blip) keeps the id for the next visit.
-        if (!cancelled && isEndedCartError(err)) end()
-      }
-    })
-    return () => {
-      cancelled = true
-    }
-  }, [cart, client, cartId, adopt, end])
-
-  const [optimisticCart, dispatchOptimistic] = useOptimistic(
-    serverCart,
-    reduceCart
-  )
-
-  // totalItems counts PRODUCT lines only. Backend-injected fee lines
-  // (e.g. the COD fee added by the payment-session flow) are excluded
-  // — otherwise the auto-open useEffect below treats a fee insertion
-  // as "a new item was added," opens the drawer mid-checkout, and
-  // locks body scroll. See @cartbase/storefront/lib/cart-helpers for the
-  // shared predicate.
-  const totalItems = productItemCount(optimisticCart?.items)
-
-  // Auto-open when items are added (count increases AFTER initial load)
-  useEffect(() => {
-    if (totalItems > prevItemCount.current && prevItemCount.current > 0) {
-      setIsOpen(true)
-    }
-    prevItemCount.current = totalItems
-  }, [totalItems])
-
-  // Lock body scroll while open
-  useEffect(() => {
-    if (isOpen) {
-      document.body.style.overflow = "hidden"
-    } else {
-      document.body.style.overflow = ""
-    }
-    return () => {
-      document.body.style.overflow = ""
-    }
-  }, [isOpen])
-
-  // Escape closes
-  useEffect(() => {
-    const handleEscape = (e: KeyboardEvent) => {
-      if (e.key === "Escape" && isOpen) setIsOpen(false)
-    }
-    document.addEventListener("keydown", handleEscape)
-    return () => document.removeEventListener("keydown", handleEscape)
-  }, [isOpen])
-
-  const open = useCallback(() => setIsOpen(true), [])
-  const close = useCallback(() => setIsOpen(false), [])
-  const toggle = useCallback(() => setIsOpen((prev) => !prev), [])
-
-  /** The single funnel for every failed change: console + `onOptimisticError`. */
-  const report = useCallback(
-    (action: OptimisticCartAction, err: unknown) => {
-      // eslint-disable-next-line no-console
-      console.error("[cart-optimistic]", action.type, err)
-      try {
-        onOptimisticError?.({ actionType: action.type, error: err, context: failureContext(action, err) })
-      } catch {
-        // The ops funnel itself must never break the UI.
-      }
-    },
-    [onOptimisticError]
-  )
-
-  /**
-   * Show an action for as long as its work runs. useOptimistic setters
-   * MUST be called inside a transition; the transition stays pending for
-   * the whole round-trip and the action falls away when it ends, by which
-   * time the confirmed cart carries it (or, on failure, it simply reverts).
-   * `work` settles without throwing; its answer is passed through.
-   */
-  const showWhile = useCallback(
-    <T,>(action: OptimisticCartAction, work: Promise<T>): Promise<T> =>
-      new Promise<T>((resolve) => {
-        startTransition(async () => {
-          dispatchOptimistic(action)
-          resolve(await work)
-        })
-      }),
-    [dispatchOptimistic]
-  )
-
-  /** The store-owned path: its own server call, reverted on throw. */
-  const applyOptimistic = useCallback(
-    (action: OptimisticCartAction, serverAction: () => Promise<unknown>) => {
-      void showWhile(
-        action,
-        serverAction().then(
-          () => true,
-          (err) => {
-            report(action, err)
-            return false
-          }
-        )
-      )
-    },
-    [showWhile, report]
-  )
-
-  /** Adopt a server-confirmed decorated cart and tell the store. */
-  const confirm = useCallback(
-    (next: Cart) => {
-      adopt(next)
-      // A completed cart has ended the cart; its id is never stored again.
-      if (isLiveCart(next)) onCartChange?.(next)
-    },
-    [adopt, onCartChange]
-  )
-
-  /** The line a change is for, as the latest confirmed cart knows it; null when it is gone. */
-  const lineNow = useCallback((lineId: string): string | null => {
-    const items = latest.current?.items ?? []
-    const variant = pendingVariant(lineId)
-    if (variant) return items.find((i) => i.variant_id === variant)?.id ?? null
-    return items.some((i) => i.id === lineId) ? lineId : null
-  }, [])
-
-  const addLine = useCallback(
-    (
-      variantId: string,
-      quantity = 1,
-      display: OptimisticAddDisplay = {}
-    ): Promise<CartMutationResult> => {
-      if (!client) {
-        return Promise.resolve({ ok: false, error: new Error("CartDrawerProvider has no client") })
-      }
-      const action: OptimisticCartAction = {
-        type: "add",
-        variant_id: variantId,
-        quantity,
-        ...display,
-      }
-      const work = queue.current!.run(async (): Promise<CartMutationResult> => {
-        // First add with no cart: create one with the item in a single
-        // call. region_id falls back to the store default server-side.
-        const create = () => sdkCreateCart(client, { items: [{ variant_id: variantId, quantity }] })
-        try {
-          const cartId = latest.current?.id
-          let res
-          if (!cartId) {
-            res = await create()
-          } else {
-            try {
-              res = await sdkAddLineItem(client, cartId, { variant_id: variantId, quantity })
-            } catch (error) {
-              // The stored cart is over (ordered in another tab, or gone):
-              // Medusa's starter treats it as no cart, so a new one starts
-              // with this item.
-              if (!isEndedCartError(error)) throw error
-              end()
-              res = await create()
-            }
-          }
-          confirm(res.cart)
-          return { ok: true, cart: res.cart }
-        } catch (error) {
-          report(action, error)
-          return { ok: false, error }
-        }
-      })
-      return showWhile(action, work)
-    },
-    [client, confirm, report, showWhile, end]
-  )
-
-  const addItem = useCallback(
-    (variantId: string, quantity = 1, display: OptimisticAddDisplay = {}): Promise<boolean> =>
-      addLine(variantId, quantity, display).then((result) => result.ok),
-    [addLine]
-  )
-
-  const updateQuantity = useCallback(
-    (lineId: string, quantity: number): Promise<boolean> => {
-      if (!client) return Promise.resolve(false)
-      const work = queue.current!.quantity(lineId, quantity, async (latestQuantity) => {
-        const id = lineNow(lineId)
-        const cartId = latest.current?.id
-        if (!id || !cartId) return false
-        try {
-          // Cartbase contract: body is `{quantity}` only; 0 deletes the line.
-          const res = await sdkUpdateLineItem(client, cartId, id, { quantity: latestQuantity })
-          confirm(res.cart)
-          return true
-        } catch (err) {
-          if (isEndedCartError(err)) end()
-          else report({ type: "update_quantity", lineId, quantity: latestQuantity }, err)
-          return false
-        }
-      })
-      return showWhile(
-        { type: "update_quantity", lineId, quantity },
-        work.then((sent) => sent === true)
-      )
-    },
-    [client, lineNow, confirm, report, showWhile, end]
-  )
-
-  const removeItem = useCallback(
-    (lineId: string): Promise<boolean> => {
-      if (!client) return Promise.resolve(false)
-      const action: OptimisticCartAction = { type: "remove", lineId }
-      // A quantity change still waiting for this line has nothing to change.
-      queue.current!.forget(lineId)
-      const work = queue.current!.run(async () => {
-        const id = lineNow(lineId)
-        const cartId = latest.current?.id
-        // Already gone (or never confirmed): nothing to delete.
-        if (!id || !cartId) return true
-        try {
-          const res = await sdkDeleteLineItem(client, cartId, id)
-          confirm(res.cart)
-          return true
-        } catch (err) {
-          if (isEndedCartError(err)) {
-            end()
-            return true
-          }
-          report(action, err)
-          return false
-        }
-      })
-      return showWhile(action, work)
-    },
-    [client, lineNow, confirm, report, showWhile, end]
-  )
-
-  const refresh = useCallback(
-    (): Promise<void> => {
-      if (!client) return Promise.resolve()
-      return queue.current!.run(async () => {
-        const id = latest.current?.id
-        if (!id) return
-        try {
-          const res = await sdkRetrieveCart(client, id)
-          confirm(res.cart)
-        } catch (err) {
-          // A cart the platform no longer knows ends; a transient failure
-          // keeps the last snapshot.
-          if (isEndedCartError(err)) end()
-        }
-      })
-    },
-    [client, confirm, end]
-  )
-
-  /** The order was placed: empty the drawer and let the store forget the id. */
-  const forget = useCallback(
-    (): Promise<void> => queue.current!.run(async () => end()),
-    [end]
-  )
-
-  // The mounted language is the default (2026-09-14): a store that mounts
-  // StorefrontLocaleProvider has nothing to hand over here, and a `labels`
-  // prop overrides only the keys it names.
-  const inherited = useLocaleArea("cartDrawer", defaultCartDrawerLabels)
-  const labels: CartDrawerLabels = {
-    ...inherited,
-    ...labelOverrides,
-  }
-  const hrefs: CartDrawerHrefs = {
-    ...defaultHrefs,
-    ...hrefOverrides,
-  }
-
-  return (
-    <CartDrawerContext.Provider
-      value={{
-        isOpen,
-        open,
-        close,
-        toggle,
-        cart: optimisticCart,
-        dispatchOptimistic,
-        applyOptimistic,
-        addLine,
-        addItem,
-        updateQuantity,
-        removeItem,
-        refresh,
-        forget,
-        canMutate: Boolean(client),
-        labels,
-        hrefs,
-      }}
-    >
-      {children}
-    </CartDrawerContext.Provider>
-  )
-}
+"use client"
+
+import {
+  createContext,
+  startTransition,
+  useCallback,
+  useContext,
+  useEffect,
+  useOptimistic,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react"
+
+import {
+  addLineItem as sdkAddLineItem,
+  createCart as sdkCreateCart,
+  deleteLineItem as sdkDeleteLineItem,
+  retrieveCart as sdkRetrieveCart,
+  updateLineItem as sdkUpdateLineItem,
+  type Cart,
+  type CartLineItem,
+} from "../api/carts"
+import type { StorefrontClient } from "../api/http"
+import { productItemCount } from "../lib/cart-helpers"
+import { defaultCartDrawerLabels, type CartDrawerLabels } from "./labels"
+import { useLocaleArea } from "../locales/context"
+import { createCartMutationQueue, type CartMutationQueue } from "./mutation-queue"
+
+/**
+ * Cart drawer context — open state + cart snapshot + labels + link hrefs.
+ *
+ * Stores wrap their root layout with `<CartDrawerProvider client={…}>`,
+ * handing either the server-read cart (`cart`) or the cart id (`cartId`,
+ * read in the browser on mount). The provider manages open/close state,
+ * auto-opens when the item count rises, locks body scroll while open, and
+ * closes on escape.
+ *
+ * THE INSTANT CART. The cart exposed via `useCartDrawer().cart` is wrapped
+ * in React 19's `useOptimistic`: every change (`addItem`, `addLine`,
+ * `updateQuantity`, `removeItem`) shows at React update speed and the
+ * platform confirms behind it; a failure reverts on its own, because the
+ * confirmed snapshot never moved. Every mutation answers with the FULL
+ * decorated cart (totals, gift cards: SERVER truth), which becomes the new
+ * confirmed snapshot, so no page refresh is needed for the drawer to
+ * settle.
+ *
+ * The changes reach the platform through ONE queue (`mutation-queue.ts`),
+ * one call at a time, each reading the cart as the answer before it left
+ * it: two answers can never cross and overwrite each other, a second add
+ * never creates a second cart, and fast quantity clicks on one line are
+ * combined into the number the shopper stopped at. A line added a moment
+ * ago carries `pending: true` (`isPendingLine`) and a placeholder id until
+ * the platform confirms it; a change made to it before then is held in the
+ * queue and sent to the real line.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/context.tsx` (v2.3.1). Cartbase
+ * data seam: the Medusa server actions are replaced by
+ * `@cartbase/storefront/api/carts` calls made through a `StorefrontClient`
+ * passed to the provider. Amounts are EUR decimal major units.
+ *
+ * Every failed change flows through `onOptimisticError` with per-action
+ * context. Wire it to the store's ops logging; the console.error stays
+ * regardless.
+ */
+
+type CartDrawerHrefs = {
+  /** Href for the checkout button in the sticky footer */
+  checkout: string
+  /** Href for the "browse products" CTA on the empty state */
+  browse: string
+  /** Prefix for product links — full href is `${productPrefix}/${handle}` */
+  productPrefix: string
+}
+
+const defaultHrefs: CartDrawerHrefs = {
+  checkout: "/checkout",
+  browse: "/store",
+  productPrefix: "/products",
+}
+
+/** Context payload passed to `onOptimisticError` for every failed mutation. */
+export type OptimisticCartError = {
+  actionType: OptimisticCartAction["type"]
+  error: unknown
+  /** Structured per-action fields (quantity, line_id, variant/product ids). */
+  context: Record<string, unknown>
+}
+
+/**
+ * Display fields an "add" action carries so the drawer can render the row
+ * immediately, before the server confirms.
+ */
+export type OptimisticAddDisplay = {
+  product_id?: string
+  product_title?: string
+  product_handle?: string
+  thumbnail?: string | null
+  variant_title?: string | null
+  /** Per-unit price in EUR major units. total = price × qty. */
+  unit_price?: number
+}
+
+/**
+ * Optimistic action shapes — what callers can dispatch to update the
+ * cart UI ahead of the server confirmation.
+ */
+export type OptimisticCartAction =
+  | ({
+      type: "add"
+      /** Variant being added. We use this to merge with existing lines. */
+      variant_id: string
+      quantity: number
+    } & OptimisticAddDisplay)
+  | {
+      type: "remove"
+      lineId: string
+    }
+  | {
+      type: "update_quantity"
+      lineId: string
+      quantity: number
+    }
+
+/** What an add answers: the confirmed cart, or why it was refused. */
+export type CartMutationResult =
+  | { ok: true; cart: Cart }
+  | {
+      ok: false
+      /** The platform's refusal (a `StoreApiError`: `code` names it, e.g. `insufficient_inventory`). */
+      error: unknown
+    }
+
+/** The id prefix of a line the platform has not confirmed yet. */
+const PENDING_PREFIX = "optimistic-"
+
+/**
+ * A cart that can still be shopped. A completed cart is an order now: the
+ * platform still answers it, lines and all, but refuses every change to it.
+ */
+export function isLiveCart(cart: Cart | null | undefined): cart is Cart {
+  return Boolean(cart && !cart.completed_at)
+}
+
+/** The platform's answer that the cart a change was aimed at is over (ordered, or gone). */
+export function isEndedCartError(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code
+  return code === "cart_completed" || code === "cart_not_found"
+}
+
+/**
+ * A line the platform has not confirmed yet: it was added a moment ago and
+ * carries a placeholder id. Its quantity and removal work already (the
+ * provider holds them until the line exists); anything that needs the real
+ * line (a server read keyed by the line id) should wait until this is false.
+ */
+export function isPendingLine(line: Pick<CartLineItem, "id">): boolean {
+  return (line as { pending?: unknown }).pending === true || line.id.startsWith(PENDING_PREFIX)
+}
+
+/** The variant a placeholder line id stands for; null for a real line id. */
+function pendingVariant(lineId: string): string | null {
+  return lineId.startsWith(PENDING_PREFIX) ? lineId.slice(PENDING_PREFIX.length) : null
+}
+
+type CartDrawerContextValue = {
+  isOpen: boolean
+  open: () => void
+  close: () => void
+  toggle: () => void
+  /** Cart snapshot AFTER any pending optimistic updates. */
+  cart: Cart | null
+  /**
+   * Dispatch an optimistic update. MUST be called inside a
+   * `startTransition` (React requirement for useOptimistic setters
+   * outside Action props). Prefer `applyOptimistic`.
+   */
+  dispatchOptimistic: (action: OptimisticCartAction) => void
+  /**
+   * Dispatches the optimistic action AND awaits the provided server
+   * mutation inside a single transition. For a store that owns the server
+   * call itself (a Next.js server action); the built-in methods below cover
+   * the SDK-wired path and are the fast one.
+   */
+  applyOptimistic: (
+    action: OptimisticCartAction,
+    serverAction: () => Promise<unknown>
+  ) => void
+  /**
+   * Add a variant: the line shows at once, the platform confirms behind it.
+   * Answers with the confirmed cart or the refusal (require the provider's
+   * `client` prop).
+   */
+  addLine: (
+    variantId: string,
+    quantity?: number,
+    display?: OptimisticAddDisplay
+  ) => Promise<CartMutationResult>
+  /** `addLine`, answering only whether it was confirmed. */
+  addItem: (
+    variantId: string,
+    quantity?: number,
+    display?: OptimisticAddDisplay
+  ) => Promise<boolean>
+  /**
+   * Set a line's quantity (0 deletes, the Cartbase contract). Every click
+   * shows at once; fast clicks on one line send the last number.
+   */
+  updateQuantity: (lineId: string, quantity: number) => Promise<boolean>
+  removeItem: (lineId: string) => Promise<boolean>
+  /** Re-read the decorated cart (totals/gift-card tender are live per read). */
+  refresh: () => Promise<void>
+  /**
+   * The cart is over (the order was placed): the drawer empties and the
+   * store's `onCartEnd` clears its cookie. The checkout calls it; the next
+   * add starts a new cart.
+   */
+  forget: () => Promise<void>
+  /** True when the provider was given a client, so the methods above reach the platform. */
+  canMutate: boolean
+  labels: CartDrawerLabels
+  hrefs: CartDrawerHrefs
+}
+
+const CartDrawerContext = createContext<CartDrawerContextValue>({
+  isOpen: false,
+  open: () => {},
+  close: () => {},
+  toggle: () => {},
+  cart: null,
+  dispatchOptimistic: () => {},
+  applyOptimistic: () => {},
+  addLine: async () => ({ ok: false, error: new Error("No CartDrawerProvider with a client is mounted") }),
+  addItem: async () => false,
+  updateQuantity: async () => false,
+  removeItem: async () => false,
+  refresh: async () => {},
+  forget: async () => {},
+  canMutate: false,
+  labels: defaultCartDrawerLabels,
+  hrefs: defaultHrefs,
+})
+
+export function useCartDrawer(): CartDrawerContextValue {
+  return useContext(CartDrawerContext)
+}
+
+/**
+ * Reducer for the useOptimistic cart. Pure function. Returns the next
+ * cart shape after applying the action. Falls back to a synthetic empty
+ * cart when there's no current cart yet so optimistic adds work even on
+ * first-add (the confirmed cart replaces it).
+ *
+ * A change aimed at a placeholder line also finds the real line of the
+ * same variant: the confirmed cart can arrive while the change is still
+ * pending, and the line must not come back or lose its new number.
+ *
+ * Exported for unit tests (pure logic, no React).
+ */
+export function reduceCart(
+  current: Cart | null,
+  action: OptimisticCartAction
+): Cart | null {
+  if (!current) {
+    if (action.type !== "add") return current
+    return {
+      id: "optimistic-cart",
+      items: [makeOptimisticLine(action)],
+    } as unknown as Cart
+  }
+
+  switch (action.type) {
+    case "add": {
+      const items = current.items ?? []
+      const existing = items.find((i) => i.variant_id === action.variant_id)
+      if (existing) {
+        return {
+          ...current,
+          items: items.map((i) =>
+            i.variant_id === action.variant_id
+              ? {
+                  ...i,
+                  quantity: i.quantity + action.quantity,
+                  total:
+                    (i.unit_price ?? 0) * (i.quantity + action.quantity),
+                }
+              : i
+          ),
+        }
+      }
+      return {
+        ...current,
+        items: [...items, makeOptimisticLine(action)],
+      }
+    }
+    case "remove": {
+      const variant = pendingVariant(action.lineId)
+      return {
+        ...current,
+        items: (current.items ?? []).filter(
+          (i) => i.id !== action.lineId && !(variant && i.variant_id === variant)
+        ),
+      }
+    }
+    case "update_quantity": {
+      const variant = pendingVariant(action.lineId)
+      return {
+        ...current,
+        items: (current.items ?? []).map((i) =>
+          i.id === action.lineId || (variant && i.variant_id === variant)
+            ? {
+                ...i,
+                quantity: action.quantity,
+                total: (i.unit_price ?? 0) * action.quantity,
+              }
+            : i
+        ),
+      }
+    }
+  }
+}
+
+/**
+ * Build a synthetic line item from an "add" action: a placeholder id and
+ * `pending: true` (see `isPendingLine`). The confirmed cart replaces it.
+ * Cast through `unknown` because `CartLineItem` has many fields we don't
+ * have at click time (created_at, tax_lines, adjustments…) — the renderer
+ * is lenient about missing optional fields.
+ */
+export function makeOptimisticLine(
+  action: Extract<OptimisticCartAction, { type: "add" }>
+): CartLineItem {
+  const unitPrice = action.unit_price ?? 0
+  return {
+    id: `${PENDING_PREFIX}${action.variant_id}`,
+    pending: true,
+    variant_id: action.variant_id,
+    product_id: action.product_id,
+    product_title: action.product_title,
+    product_handle: action.product_handle,
+    thumbnail: action.thumbnail,
+    variant_title: action.variant_title,
+    quantity: action.quantity,
+    unit_price: unitPrice,
+    total: unitPrice * action.quantity,
+    original_total: unitPrice * action.quantity,
+  } as unknown as CartLineItem
+}
+
+/** The per-action fields every failure report carries. */
+function failureContext(action: OptimisticCartAction, err: unknown): Record<string, unknown> {
+  const err_ = err as { message?: string; name?: string; code?: string } | null
+  const ctx: Record<string, unknown> = { action_type: action.type }
+  if (action.type === "add") {
+    ctx.quantity = action.quantity
+    ctx.product_id = action.product_id
+    ctx.variant_id = action.variant_id
+  } else if (action.type === "remove") {
+    ctx.line_id = action.lineId
+  } else {
+    ctx.line_id = action.lineId
+    ctx.quantity = action.quantity
+  }
+  ctx.err_name = err_?.name
+  ctx.err_code = err_?.code
+  ctx.err_message = err_?.message ?? String(err)
+  return ctx
+}
+
+export function CartDrawerProvider({
+  cart,
+  client,
+  cartId,
+  onCartChange,
+  onCartEnd,
+  onOptimisticError,
+  labels: labelOverrides,
+  hrefs: hrefOverrides,
+  children,
+}: {
+  /**
+   * Server-fetched cart snapshot (RSC/server-action pattern). When the
+   * prop changes (e.g. after a router refresh) it becomes the confirmed
+   * snapshot, unless a change of the provider's own is still on its way.
+   * Leave it out and pass `client` + `cartId` to read the cart in the
+   * browser instead, so the page never waits for it.
+   */
+  cart?: Cart | null
+  /** StorefrontClient for the SDK-wired mutations (addLine/addItem/updateQuantity/removeItem/refresh). */
+  client?: StorefrontClient
+  /** Known cart id to retrieve when no `cart` snapshot is passed. */
+  cartId?: string | null
+  /**
+   * Fires with the decorated cart after every server-confirmed change,
+   * including first-add cart creation — persist `cart.id` (cookie/storage)
+   * here so the cart survives reloads.
+   */
+  onCartChange?: (cart: Cart) => void
+  /**
+   * Fires when the cart is over: the order was placed, or the platform
+   * answered that the stored cart is completed or gone. Clear the stored
+   * cart id (the cookie) here; the next add creates a new cart and
+   * `onCartChange` stores its id.
+   */
+  onCartEnd?: () => void
+  /** Ops funnel for every failed optimistic mutation (see module JSDoc). */
+  onOptimisticError?: (failure: OptimisticCartError) => void
+  /**
+   * Overrides. The default is the language mounted by
+   * `StorefrontLocaleProvider`, English when none is mounted, so a store
+   * that mounts its pack has nothing to hand over here (2026-09-14).
+   */
+  labels?: Partial<CartDrawerLabels>
+  hrefs?: Partial<CartDrawerHrefs>
+  children: ReactNode
+}) {
+  const [isOpen, setIsOpen] = useState(false)
+  const prevItemCount = useRef(0)
+
+  // The queue every SDK change goes through, and the latest confirmed cart
+  // it reads when a change's turn comes (state lags a render behind).
+  const queue = useRef<CartMutationQueue | null>(null)
+  if (!queue.current) queue.current = createCartMutationQueue()
+  // A completed cart is an order: the drawer never holds one.
+  const latest = useRef<Cart | null>(isLiveCart(cart) ? cart : null)
+
+  // The store's hooks, read through refs so an inline handler never re-runs an effect.
+  const cartEnded = useRef(onCartEnd)
+  cartEnded.current = onCartEnd
+
+  // Confirmed snapshot: seeded from the prop, replaced by every SDK
+  // mutation response and by prop updates from server refreshes.
+  const [serverCart, setServerCart] = useState<Cart | null>(latest.current)
+
+  /** The cart is over: the drawer empties and the store forgets the id. */
+  const end = useCallback(() => {
+    latest.current = null
+    startTransition(() => setServerCart(null))
+    try {
+      cartEnded.current?.()
+    } catch {
+      // A store's handler must never break the drawer.
+    }
+  }, [])
+
+  useEffect(() => {
+    if (cart === undefined) return
+    // A refresh carrying the cart as it was must not overwrite an answer
+    // still on its way; the queue's own answers are newer.
+    if (queue.current?.busy()) return
+    if (cart && !isLiveCart(cart)) {
+      end()
+      return
+    }
+    latest.current = cart
+    setServerCart(cart)
+  }, [cart, end])
+
+  // A confirmed cart becomes the snapshot inside a transition, so it lands
+  // together with the end of the change that asked for it and a pending
+  // line is never shown twice. A completed one ends the cart instead.
+  const adopt = useCallback(
+    (next: Cart) => {
+      if (!isLiveCart(next)) {
+        end()
+        return
+      }
+      latest.current = next
+      startTransition(() => setServerCart(next))
+    },
+    [end]
+  )
+
+  // Client+cartId mode: read the cart on mount, through the queue, so an
+  // add made before the read answers goes to this cart, not a new one.
+  useEffect(() => {
+    if (cart !== undefined || !client || !cartId) return
+    let cancelled = false
+    void queue.current!.run(async () => {
+      try {
+        const res = await sdkRetrieveCart(client, cartId)
+        if (!cancelled) adopt(res.cart)
+      } catch (err) {
+        // A stored id the platform no longer knows: forget it. Any other
+        // failure (a network blip) keeps the id for the next visit.
+        if (!cancelled && isEndedCartError(err)) end()
+      }
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [cart, client, cartId, adopt, end])
+
+  const [optimisticCart, dispatchOptimistic] = useOptimistic(
+    serverCart,
+    reduceCart
+  )
+
+  // totalItems counts PRODUCT lines only. Backend-injected fee lines
+  // (e.g. the COD fee added by the payment-session flow) are excluded
+  // — otherwise the auto-open useEffect below treats a fee insertion
+  // as "a new item was added," opens the drawer mid-checkout, and
+  // locks body scroll. See @cartbase/storefront/lib/cart-helpers for the
+  // shared predicate.
+  const totalItems = productItemCount(optimisticCart?.items)
+
+  // Auto-open when items are added (count increases AFTER initial load)
+  useEffect(() => {
+    if (totalItems > prevItemCount.current && prevItemCount.current > 0) {
+      setIsOpen(true)
+    }
+    prevItemCount.current = totalItems
+  }, [totalItems])
+
+  // Lock body scroll while open
+  useEffect(() => {
+    if (isOpen) {
+      document.body.style.overflow = "hidden"
+    } else {
+      document.body.style.overflow = ""
+    }
+    return () => {
+      document.body.style.overflow = ""
+    }
+  }, [isOpen])
+
+  // Escape closes
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === "Escape" && isOpen) setIsOpen(false)
+    }
+    document.addEventListener("keydown", handleEscape)
+    return () => document.removeEventListener("keydown", handleEscape)
+  }, [isOpen])
+
+  const open = useCallback(() => setIsOpen(true), [])
+  const close = useCallback(() => setIsOpen(false), [])
+  const toggle = useCallback(() => setIsOpen((prev) => !prev), [])
+
+  /** The single funnel for every failed change: console + `onOptimisticError`. */
+  const report = useCallback(
+    (action: OptimisticCartAction, err: unknown) => {
+      // eslint-disable-next-line no-console
+      console.error("[cart-optimistic]", action.type, err)
+      try {
+        onOptimisticError?.({ actionType: action.type, error: err, context: failureContext(action, err) })
+      } catch {
+        // The ops funnel itself must never break the UI.
+      }
+    },
+    [onOptimisticError]
+  )
+
+  /**
+   * Show an action for as long as its work runs. useOptimistic setters
+   * MUST be called inside a transition; the transition stays pending for
+   * the whole round-trip and the action falls away when it ends, by which
+   * time the confirmed cart carries it (or, on failure, it simply reverts).
+   * `work` settles without throwing; its answer is passed through.
+   */
+  const showWhile = useCallback(
+    <T,>(action: OptimisticCartAction, work: Promise<T>): Promise<T> =>
+      new Promise<T>((resolve) => {
+        startTransition(async () => {
+          dispatchOptimistic(action)
+          resolve(await work)
+        })
+      }),
+    [dispatchOptimistic]
+  )
+
+  /** The store-owned path: its own server call, reverted on throw. */
+  const applyOptimistic = useCallback(
+    (action: OptimisticCartAction, serverAction: () => Promise<unknown>) => {
+      void showWhile(
+        action,
+        serverAction().then(
+          () => true,
+          (err) => {
+            report(action, err)
+            return false
+          }
+        )
+      )
+    },
+    [showWhile, report]
+  )
+
+  /** Adopt a server-confirmed decorated cart and tell the store. */
+  const confirm = useCallback(
+    (next: Cart) => {
+      adopt(next)
+      // A completed cart has ended the cart; its id is never stored again.
+      if (isLiveCart(next)) onCartChange?.(next)
+    },
+    [adopt, onCartChange]
+  )
+
+  /** The line a change is for, as the latest confirmed cart knows it; null when it is gone. */
+  const lineNow = useCallback((lineId: string): string | null => {
+    const items = latest.current?.items ?? []
+    const variant = pendingVariant(lineId)
+    if (variant) return items.find((i) => i.variant_id === variant)?.id ?? null
+    return items.some((i) => i.id === lineId) ? lineId : null
+  }, [])
+
+  const addLine = useCallback(
+    (
+      variantId: string,
+      quantity = 1,
+      display: OptimisticAddDisplay = {}
+    ): Promise<CartMutationResult> => {
+      if (!client) {
+        return Promise.resolve({ ok: false, error: new Error("CartDrawerProvider has no client") })
+      }
+      const action: OptimisticCartAction = {
+        type: "add",
+        variant_id: variantId,
+        quantity,
+        ...display,
+      }
+      const work = queue.current!.run(async (): Promise<CartMutationResult> => {
+        // First add with no cart: create one with the item in a single
+        // call. region_id falls back to the store default server-side.
+        const create = () => sdkCreateCart(client, { items: [{ variant_id: variantId, quantity }] })
+        try {
+          const cartId = latest.current?.id
+          let res
+          if (!cartId) {
+            res = await create()
+          } else {
+            try {
+              res = await sdkAddLineItem(client, cartId, { variant_id: variantId, quantity })
+            } catch (error) {
+              // The stored cart is over (ordered in another tab, or gone):
+              // Medusa's starter treats it as no cart, so a new one starts
+              // with this item.
+              if (!isEndedCartError(error)) throw error
+              end()
+              res = await create()
+            }
+          }
+          confirm(res.cart)
+          return { ok: true, cart: res.cart }
+        } catch (error) {
+          report(action, error)
+          return { ok: false, error }
+        }
+      })
+      return showWhile(action, work)
+    },
+    [client, confirm, report, showWhile, end]
+  )
+
+  const addItem = useCallback(
+    (variantId: string, quantity = 1, display: OptimisticAddDisplay = {}): Promise<boolean> =>
+      addLine(variantId, quantity, display).then((result) => result.ok),
+    [addLine]
+  )
+
+  const updateQuantity = useCallback(
+    (lineId: string, quantity: number): Promise<boolean> => {
+      if (!client) return Promise.resolve(false)
+      const work = queue.current!.quantity(lineId, quantity, async (latestQuantity) => {
+        const id = lineNow(lineId)
+        const cartId = latest.current?.id
+        if (!id || !cartId) return false
+        try {
+          // Cartbase contract: body is `{quantity}` only; 0 deletes the line.
+          const res = await sdkUpdateLineItem(client, cartId, id, { quantity: latestQuantity })
+          confirm(res.cart)
+          return true
+        } catch (err) {
+          if (isEndedCartError(err)) end()
+          else report({ type: "update_quantity", lineId, quantity: latestQuantity }, err)
+          return false
+        }
+      })
+      return showWhile(
+        { type: "update_quantity", lineId, quantity },
+        work.then((sent) => sent === true)
+      )
+    },
+    [client, lineNow, confirm, report, showWhile, end]
+  )
+
+  const removeItem = useCallback(
+    (lineId: string): Promise<boolean> => {
+      if (!client) return Promise.resolve(false)
+      const action: OptimisticCartAction = { type: "remove", lineId }
+      // A quantity change still waiting for this line has nothing to change.
+      queue.current!.forget(lineId)
+      const work = queue.current!.run(async () => {
+        const id = lineNow(lineId)
+        const cartId = latest.current?.id
+        // Already gone (or never confirmed): nothing to delete.
+        if (!id || !cartId) return true
+        try {
+          const res = await sdkDeleteLineItem(client, cartId, id)
+          confirm(res.cart)
+          return true
+        } catch (err) {
+          if (isEndedCartError(err)) {
+            end()
+            return true
+          }
+          report(action, err)
+          return false
+        }
+      })
+      return showWhile(action, work)
+    },
+    [client, lineNow, confirm, report, showWhile, end]
+  )
+
+  const refresh = useCallback(
+    (): Promise<void> => {
+      if (!client) return Promise.resolve()
+      return queue.current!.run(async () => {
+        const id = latest.current?.id
+        if (!id) return
+        try {
+          const res = await sdkRetrieveCart(client, id)
+          confirm(res.cart)
+        } catch (err) {
+          // A cart the platform no longer knows ends; a transient failure
+          // keeps the last snapshot.
+          if (isEndedCartError(err)) end()
+        }
+      })
+    },
+    [client, confirm, end]
+  )
+
+  /** The order was placed: empty the drawer and let the store forget the id. */
+  const forget = useCallback(
+    (): Promise<void> => queue.current!.run(async () => end()),
+    [end]
+  )
+
+  // The mounted language is the default (2026-09-14): a store that mounts
+  // StorefrontLocaleProvider has nothing to hand over here, and a `labels`
+  // prop overrides only the keys it names.
+  const inherited = useLocaleArea("cartDrawer", defaultCartDrawerLabels)
+  const labels: CartDrawerLabels = {
+    ...inherited,
+    ...labelOverrides,
+  }
+  const hrefs: CartDrawerHrefs = {
+    ...defaultHrefs,
+    ...hrefOverrides,
+  }
+
+  return (
+    <CartDrawerContext.Provider
+      value={{
+        isOpen,
+        open,
+        close,
+        toggle,
+        cart: optimisticCart,
+        dispatchOptimistic,
+        applyOptimistic,
+        addLine,
+        addItem,
+        updateQuantity,
+        removeItem,
+        refresh,
+        forget,
+        canMutate: Boolean(client),
+        labels,
+        hrefs,
+      }}
+    >
+      {children}
+    </CartDrawerContext.Provider>
+  )
+}