@cartbase/storefront 0.17.0 → 0.18.1

package/src/cart-drawer/context.tsx

@@ -25,41 +25,43 @@ 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 cart={cart}>`
- * (the cart is fetched server-side and passed down as a prop). The
- * provider manages open/close state, auto-opens when item count rises,
- * locks body scroll while open, and closes on escape.
+ * 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.
  *
- * Optimistic UI: the cart exposed via `useCartDrawer().cart` is wrapped
- * in React 19's `useOptimistic`. Callers (PDP add buttons, drawer
- * quantity steppers, drawer remove buttons) dispatch optimistic actions
- * BEFORE awaiting the corresponding server mutation. The drawer reflects
- * the change at React update speed (~16ms) instead of waiting for the
- * full backend round-trip (~800-1500ms). On mutation failure the
- * optimistic state reverts automatically because the confirmed cart
- * snapshot never updated past the failed mutation. See
- * https://react.dev/reference/react/useOptimistic.
+ * 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 (`../data/cart`) are replaced by
+ * data seam: the Medusa server actions are replaced by
  * `@cartbase/storefront/api/carts` calls made through a `StorefrontClient`
- * passed to the provider. Every mutation returns the FULL decorated cart
- * (totals + gift_cards[]/gift_card_total/gift_card_remainder — SERVER
- * truth), which the provider adopts as the new confirmed snapshot, so no
- * RSC re-fetch is required for the drawer to settle. Amounts are EUR
- * decimal major units (the optimistic `unit_price × quantity` arithmetic
- * is unit-agnostic and unchanged).
+ * passed to the provider. Amounts are EUR decimal major units.
  *
- * The source's `logEvent` ops funnel (backend error log endpoint) has no
- * Cartbase SDK equivalent yet — the same single-funnel discipline is kept
- * via the `onOptimisticError` prop: every failed optimistic mutation
- * (every PDP add, cross-sell add, drawer remove, drawer quantity change)
- * flows through it with per-action context. Wire it to the store's ops
- * logging; the console.error stays regardless.
+ * 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 = {
@@ -120,6 +122,47 @@ export type OptimisticCartAction =
       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
@@ -130,40 +173,51 @@ type CartDrawerContextValue = {
   /**
    * Dispatch an optimistic update. MUST be called inside a
    * `startTransition` (React requirement for useOptimistic setters
-   * outside Action props). The CartDrawerProvider exposes a helper
-   * `applyOptimistic` that wraps the dispatch in startTransition for
-   * convenience; prefer that.
+   * outside Action props). Prefer `applyOptimistic`.
    */
   dispatchOptimistic: (action: OptimisticCartAction) => void
   /**
-   * Convenience wrapper: dispatches the optimistic action AND awaits
-   * the provided server mutation inside a single transition. Use from
-   * PDP add buttons or anywhere the store owns the server call itself
-   * (e.g. a Next.js server action). The built-in helpers below cover
-   * the SDK-wired path.
+   * 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
   /**
-   * SDK-wired mutations (require the provider's `client` prop). Each
-   * dispatches the optimistic action, calls the matching
-   * `@cartbase/storefront/api/carts` function, and adopts the returned
-   * decorated cart. Resolves `true` on server confirmation, `false` on
-   * failure (after funneling through `onOptimisticError`) or when no
-   * client is configured.
+   * 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>
-  /** POST line-items/:id with `{quantity}` — Cartbase contract: 0 deletes. */
+  /**
+   * 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
 }
@@ -176,10 +230,13 @@ const CartDrawerContext = createContext<CartDrawerContextValue>({
   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,
 })
@@ -192,7 +249,11 @@ export function useCartDrawer(): CartDrawerContextValue {
  * 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 server backfills the real cart_id + line_id below).
+ * 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).
  */
@@ -201,10 +262,6 @@ export function reduceCart(
   action: OptimisticCartAction
 ): Cart | null {
   if (!current) {
-    // No cart yet on the server — synthesize a minimal one so the drawer
-    // can render the item immediately. The real createCart call will
-    // create the cart and the confirmed snapshot replaces this synthetic
-    // one.
     if (action.type !== "add") return current
     return {
       id: "optimistic-cart",
@@ -237,16 +294,20 @@ export function reduceCart(
       }
     }
     case "remove": {
+      const variant = pendingVariant(action.lineId)
       return {
         ...current,
-        items: (current.items ?? []).filter((i) => i.id !== action.lineId),
+        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
+          i.id === action.lineId || (variant && i.variant_id === variant)
             ? {
                 ...i,
                 quantity: action.quantity,
@@ -260,18 +321,19 @@ export function reduceCart(
 }
 
 /**
- * Build a synthetic line item from an "add" action. The real server
- * response will replace this with the actual line on confirmation.
- * 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.
+ * 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: `optimistic-${action.variant_id}`,
+    id: `${PENDING_PREFIX}${action.variant_id}`,
+    pending: true,
     variant_id: action.variant_id,
     product_id: action.product_id,
     product_title: action.product_title,
@@ -285,11 +347,32 @@ export function makeOptimisticLine(
   } 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,
@@ -298,11 +381,12 @@ export function CartDrawerProvider({
   /**
    * Server-fetched cart snapshot (RSC/server-action pattern). When the
    * prop changes (e.g. after a router refresh) it becomes the confirmed
-   * snapshot. Optional when `client` + `cartId` are given — the provider
-   * then retrieves the cart itself on mount.
+   * 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 (addItem/updateQuantity/removeItem/refresh). */
+  /** 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
@@ -312,6 +396,13 @@ export function CartDrawerProvider({
    * 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
   /**
@@ -326,31 +417,79 @@ export function CartDrawerProvider({
   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 (each returns the full decorated cart) and by
-  // prop updates from server refreshes.
-  const [serverCart, setServerCart] = useState<Cart | null>(cart ?? null)
+  // 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) setServerCart(cart)
-  }, [cart])
+    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: retrieve the decorated cart on mount when no
-  // snapshot was provided.
+  // 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
-    sdkRetrieveCart(client, cartId)
-      .then((res) => {
-        if (!cancelled) setServerCart(res.cart)
-      })
-      .catch(() => {
-        // 404 cart_not_found (expired/foreign id) → stay empty; the next
-        // addItem creates a fresh cart.
-      })
+    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])
+  }, [cart, client, cartId, adopt, end])
 
   const [optimisticCart, dispatchOptimistic] = useOptimistic(
     serverCart,
@@ -398,149 +537,206 @@ export function CartDrawerProvider({
   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]
+  )
+
   /**
-   * Shared optimistic runner. useOptimistic setters MUST be called
-   * inside a transition or an Action prop, otherwise React errors
-   * during render. Wrapping both the dispatch AND the awaited server
-   * work in a single startTransition ensures the optimistic state stays
-   * "pending" for the entire round-trip — and reverts cleanly on throw.
-   *
-   * On failure the optimistic state auto-reverts because the confirmed
-   * snapshot hasn't updated. We do NOT rethrow — useOptimistic
-   * semantics require the transition to settle cleanly. Every failure
-   * is logged (console + `onOptimisticError`): this is the single
-   * funnel for every PDP add, cross-sell add, drawer remove, drawer
-   * quantity change. Without it those failures are invisible to ops.
+   * 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 runOptimistic = useCallback(
-    (
-      action: OptimisticCartAction,
-      work: () => Promise<unknown>
-    ): Promise<boolean> =>
-      new Promise<boolean>((resolve) => {
+  const showWhile = useCallback(
+    <T,>(action: OptimisticCartAction, work: Promise<T>): Promise<T> =>
+      new Promise<T>((resolve) => {
         startTransition(async () => {
           dispatchOptimistic(action)
-          try {
-            await work()
-            resolve(true)
-          } catch (err) {
-            const err_ = err as { message?: string; name?: string }
-            // eslint-disable-next-line no-console
-            console.error("[cart-optimistic]", action.type, err_)
-            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 if (action.type === "update_quantity") {
-              ctx.line_id = action.lineId
-              ctx.quantity = action.quantity
-            }
-            ctx.err_name = err_?.name
-            ctx.err_message = err_?.message ?? String(err)
-            try {
-              onOptimisticError?.({ actionType: action.type, error: err, context: ctx })
-            } catch {
-              // The ops funnel itself must never break the UI.
-            }
-            resolve(false)
-          }
+          resolve(await work)
         })
       }),
-    [dispatchOptimistic, onOptimisticError]
+    [dispatchOptimistic]
   )
 
+  /** The store-owned path: its own server call, reverted on throw. */
   const applyOptimistic = useCallback(
     (action: OptimisticCartAction, serverAction: () => Promise<unknown>) => {
-      void runOptimistic(action, serverAction)
+      void showWhile(
+        action,
+        serverAction().then(
+          () => true,
+          (err) => {
+            report(action, err)
+            return false
+          }
+        )
+      )
     },
-    [runOptimistic]
+    [showWhile, report]
   )
 
-  /** Adopt a server-confirmed decorated cart. */
+  /** Adopt a server-confirmed decorated cart and tell the store. */
   const confirm = useCallback(
     (next: Cart) => {
-      setServerCart(next)
-      onCartChange?.(next)
+      adopt(next)
+      // A completed cart has ended the cart; its id is never stored again.
+      if (isLiveCart(next)) onCartChange?.(next)
     },
-    [onCartChange]
+    [adopt, onCartChange]
   )
 
-  const addItem = useCallback(
+  /** 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<boolean> => {
-      if (!client) return Promise.resolve(false)
+    ): 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,
       }
-      return runOptimistic(action, async () => {
-        const existingId = serverCart?.id
-        if (existingId) {
-          const res = await sdkAddLineItem(client, existingId, {
-            variant_id: variantId,
-            quantity,
-          })
-          confirm(res.cart)
-        } else {
-          // 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 res = await sdkCreateCart(client, {
-            items: [{ variant_id: variantId, quantity }],
-          })
+      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, serverCart?.id, runOptimistic, confirm]
+    [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> => {
-      const id = serverCart?.id
-      if (!client || !id) return Promise.resolve(false)
-      return runOptimistic(
-        { type: "update_quantity", lineId, quantity },
-        async () => {
-          // Cartbase contract: body is `{quantity}` only (metadata is NOT
-          // accepted on update, only on add); quantity 0 deletes the line.
-          const res = await sdkUpdateLineItem(client, id, lineId, { quantity })
+      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, serverCart?.id, runOptimistic, confirm]
+    [client, lineNow, confirm, report, showWhile, end]
   )
 
   const removeItem = useCallback(
     (lineId: string): Promise<boolean> => {
-      const id = serverCart?.id
-      if (!client || !id) return Promise.resolve(false)
-      return runOptimistic({ type: "remove", lineId }, async () => {
-        const res = await sdkDeleteLineItem(client, id, lineId)
-        confirm(res.cart)
+      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, serverCart?.id, runOptimistic, confirm]
+    [client, lineNow, confirm, report, showWhile, end]
   )
 
-  const refresh = useCallback(async (): Promise<void> => {
-    const id = serverCart?.id
-    if (!client || !id) return
-    try {
-      const res = await sdkRetrieveCart(client, id)
-      confirm(res.cart)
-    } catch {
-      // Keep the last snapshot on transient failure.
-    }
-  }, [client, serverCart?.id, confirm])
+  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`
@@ -565,10 +761,13 @@ export function CartDrawerProvider({
         cart: optimisticCart,
         dispatchOptimistic,
         applyOptimistic,
+        addLine,
         addItem,
         updateQuantity,
         removeItem,
         refresh,
+        forget,
+        canMutate: Boolean(client),
         labels,
         hrefs,
       }}