create-brainerce-store 1.80.0 → 1.82.0

package/templates/nextjs/designs/atelier/ui/cart/cart-bundle-offer.tsx

@@ -6,6 +6,7 @@ import type { CartBundleOffer as CartBundleOfferType } from 'brainerce';
 import { formatPrice } from 'brainerce';
 import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 import { IconBag } from '@/ui/shared/icons';
 
@@ -23,8 +24,10 @@ interface CartBundleOfferCardProps {
  */
 export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBundleOfferCardProps) {
   const t = useTranslations('cart');
+  const tp = useTranslations('productDetail');
   const currency = useCurrency();
   const [adding, setAdding] = useState(false);
+  const [addError, setAddError] = useState<AddToCartError | null>(null);
 
   const offered = offer.offeredProducts;
 
@@ -37,6 +40,7 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
 
   async function handleAdd() {
     if (adding) return;
+    setAddError(null);
     try {
       setAdding(true);
       const { getClient } = await import('@/core/lib/brainerce');
@@ -46,6 +50,10 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
       await client.addBundleToCart(cartId, offer.id);
       onAdd();
     } catch (err) {
+      // The cart page is where a shopper is most likely to be AT the 50-line
+      // cap, and a bundle adds one line per offered product. Logging alone
+      // left the button spinning back to idle with nothing added.
+      setAddError(toAddToCartError(err));
       console.error('Failed to add bundle:', err);
     } finally {
       setAdding(false);
@@ -105,6 +113,16 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
           {adding ? t('addingBundle') : t('addBundleItem')}
         </button>
       </div>
+
+      {/*
+        Why the bundle was refused. Without this the button resets and
+        nothing is added, which reads as a broken button.
+      */}
+      {addError && (
+        <p role="alert" className="text-destructive mt-2 text-xs">
+          {addError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}
+        </p>
+      )}
     </article>
   );
 }

package/templates/nextjs/designs/atelier/ui/cart/cart-item.tsx

@@ -9,6 +9,7 @@ import { useTranslations } from '@/core/lib/translations';
 import { useCurrency } from '@/core/lib/use-currency';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { cn } from '@/core/lib/utils';
+import { getErrorCode } from '@/core/lib/add-to-cart-error';
 import { OrderCustomizations } from '@/components/account/order-customizations';
 import { IconMinus, IconPlus, IconTrash } from '@/ui/shared/icons';
 
@@ -18,6 +19,17 @@ interface CartItemProps {
   className?: string;
 }
 
+/**
+ * Which `cart.*` string each refusal shows. A map rather than a ternary chain:
+ * four outcomes nest badly, and this keeps the copy next to the reason.
+ */
+const LINE_ERROR_KEYS = {
+  NOT_ENOUGH_STOCK: 'notEnoughStock',
+  ITEM_UNAVAILABLE: 'itemUnavailable',
+  UPDATE_FAILED: 'quantityUpdateFailed',
+  REMOVE_FAILED: 'removeFailed',
+} as const;
+
 /**
  * Single cart line: image, name, variant, unit price, quantity controls,
  * remove, line total; the `item` prop comes from useCartPage().cart.
@@ -25,9 +37,14 @@ interface CartItemProps {
 export function CartItem({ item, onUpdate, className }: CartItemProps) {
   const t = useTranslations('common');
   const td = useTranslations('productDetail');
+  const tc = useTranslations('cart');
   const currency = useCurrency();
   const [updating, setUpdating] = useState(false);
   const [removing, setRemoving] = useState(false);
+  // Why the last quantity change or removal did not take. Both calls used to
+  // fail into console.error alone: the row snapped back to the quantity it
+  // already had, or stayed put after Remove, and nothing on screen said why.
+  const [lineError, setLineError] = useState<keyof typeof LINE_ERROR_KEYS | null>(null);
 
   const productName = item.product.name;
   const imageUrl = getCartItemImage(item);
@@ -49,12 +66,29 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   async function handleQuantityChange(newQuantity: number) {
     if (newQuantity < 1 || updating) return;
 
+    setLineError(null);
     try {
       setUpdating(true);
       const client = getClient();
       await client.smartUpdateCartItem(item.productId, newQuantity, item.variantId || undefined);
       onUpdate();
     } catch (err) {
+      // Two of these refusals are PERMANENT, and "please try again" would send
+      // the shopper round a loop that cannot succeed: INSUFFICIENT_STOCK (more
+      // than the inventory left) and PRODUCT_UNAVAILABLE (the line cannot be
+      // bought at all any more). Both get their own sentence; everything else
+      // is a blip worth one more tap. The 50-line cart cap is NOT a cause here
+      // at all, it only ever refuses a brand new line. Both codes are part of
+      // the documented API error catalogue, not guesses. Keep the log: the
+      // shopper gets the sentence, the developer still needs the detail.
+      const code = getErrorCode(err);
+      setLineError(
+        code === 'INSUFFICIENT_STOCK'
+          ? 'NOT_ENOUGH_STOCK'
+          : code === 'PRODUCT_UNAVAILABLE'
+            ? 'ITEM_UNAVAILABLE'
+            : 'UPDATE_FAILED'
+      );
       console.error('Failed to update quantity:', err);
     } finally {
       setUpdating(false);
@@ -64,12 +98,17 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   async function handleRemove() {
     if (removing) return;
 
+    setLineError(null);
     try {
       setRemoving(true);
       const client = getClient();
       await client.smartRemoveFromCart(item.productId, item.variantId || undefined);
       onUpdate();
     } catch (err) {
+      // Nothing is lost when a remove fails, so the line is still there and
+      // still correct. Say so anyway: a Remove that visibly does nothing reads
+      // as a broken button.
+      setLineError('REMOVE_FAILED');
       console.error('Failed to remove item:', err);
     } finally {
       setRemoving(false);
@@ -157,6 +196,17 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
             {removing ? t('removing') : t('remove')}
           </button>
         </div>
+
+        {/*
+          Why the quantity change or the removal did not take. Keep it inside
+          this line's own column: it describes THIS row, and a shopper with ten
+          rows on screen has to be able to tell which one refused.
+        */}
+        {lineError && (
+          <p role="alert" className="text-destructive mt-2 text-xs font-medium">
+            {tc(LINE_ERROR_KEYS[lineError])}
+          </p>
+        )}
       </div>
 
       {/* Line total */}

package/templates/nextjs/designs/atelier/ui/cart/cart-upgrade-banner.tsx

@@ -7,6 +7,7 @@ import { formatPrice } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
 import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 import { IconX } from '@/ui/shared/icons';
 
@@ -29,9 +30,20 @@ export function CartUpgradeBanner({
   className,
 }: CartUpgradeBannerProps) {
   const t = useTranslations('cart');
+  const tp = useTranslations('productDetail');
   const currency = useCurrency();
   const [upgrading, setUpgrading] = useState(false);
   const [dismissed, setDismissed] = useState(false);
+  // True once the upgraded product is in the cart. A retry after a failed
+  // removal must retry the REMOVAL only, or a second press buys two of them.
+  const [upgradeAdded, setUpgradeAdded] = useState(false);
+  // `'ORIGINAL_NOT_REMOVED'` is kept local instead of being added to the shared
+  // `AddToCartError`: every other consumer of that type branches on
+  // `=== 'CART_FULL'` and would silently render "we could not add this" for a
+  // case where the add actually succeeded.
+  const [upgradeError, setUpgradeError] = useState<AddToCartError | 'ORIGINAL_NOT_REMOVED' | null>(
+    null
+  );
 
   const storageKey = `dismissed_upgrade_${suggestion.sourceProductId}`;
 
@@ -48,6 +60,16 @@ export function CartUpgradeBanner({
   if (dismissed) return null;
 
   const target = suggestion.targetProduct;
+
+  // A one-click upgrade cannot choose a variation for the shopper. When the
+  // target is VARIABLE with no pinned variant the backend says so
+  // (`requiresVariantSelection`), and adding it without a `variantId` is
+  // rejected outright, so offering the button here would only ever produce an
+  // error. Say nothing instead of promising something that cannot work; the
+  // shopper can still reach the product from the catalogue and pick a variation
+  // there. If you want to support this properly, add a variation picker to the
+  // banner and pass the chosen `variantId` to `smartAddToCart` below.
+  if (target.requiresVariantSelection && !target.pinnedVariant?.id) return null;
   const firstImage = target.images?.[0];
   const imageUrl = firstImage
     ? typeof firstImage === 'string'
@@ -65,15 +87,72 @@ export function CartUpgradeBanner({
     setDismissed(true);
   }
 
+  /**
+   * Swap the cart line for the upgraded product: ADD FIRST, THEN REMOVE.
+   *
+   * The order is load-bearing, not incidental. This used to remove and then
+   * add, so any failure of the add (a network blip, the target selling out, or
+   * the 50-line cart cap answering 400) left the shopper with NEITHER product
+   * and nothing on screen: the remove had committed, the add had not, and the
+   * whole thing went to the console. Adding first means a failed add leaves the
+   * cart exactly as it was.
+   *
+   * The other candidate, remove-then-add with a compensating re-add, was
+   * rejected because the compensation is not a restore. A cart line carries
+   * `modifiers`, `customizations`, `notes` and `parentCartItemId`, and
+   * `smartAddToCart` accepts none of those back in that shape (it takes
+   * `selections`), so re-adding would silently strip the shopper's choices even
+   * when it SUCCEEDS, and orphan a nested-combo child line. The SDK has no swap
+   * primitive to sidestep the choice with (`smartRemoveFromCart` is only
+   * `smartUpdateCartItem(productId, 0, variantId)`), so these two orderings are
+   * the whole option space.
+   *
+   * The accepted cost: the cart is briefly one line longer, so a cart sitting
+   * at the 50-line cap refuses a swap that is net-zero. The shopper is told the
+   * cart is full and the cart is untouched, which is a far better outcome than
+   * losing the line. Do NOT add a "fall back to remove-then-add when the cart is
+   * full" path; that hands the loss window back for a rare edge.
+   */
   async function handleUpgrade() {
     if (upgrading) return;
+    setUpgradeError(null);
     try {
       setUpgrading(true);
       const client = getClient();
-      await client.smartRemoveFromCart(cartItem.productId, cartItem.variantId || undefined);
-      await client.smartAddToCart({ productId: target.id, quantity: cartItem.quantity });
+      if (!upgradeAdded) {
+        // A VARIABLE target needs a variant. The backend already tells us which
+        // case we are in (`pinnedVariant` when the slot pins one,
+        // `requiresVariantSelection` when the shopper must choose), but this
+        // banner used to send neither -- and `CartService.addItem` rejects a
+        // VARIABLE product with no `variantId`, so an upgrade to a variable
+        // product failed EVERY time, not occasionally. Under the old
+        // remove-then-add ordering that silently destroyed the original line.
+        // The unpinned case is filtered out before render, so by here either a
+        // pin exists or the target is SIMPLE.
+        await client.smartAddToCart({
+          productId: target.id,
+          quantity: cartItem.quantity,
+          ...(target.pinnedVariant?.id ? { variantId: target.pinnedVariant.id } : {}),
+        });
+        setUpgradeAdded(true);
+      }
+      try {
+        await client.smartRemoveFromCart(cartItem.productId, cartItem.variantId || undefined);
+      } catch (err) {
+        // The upgrade IS in the cart and only the old line survived, so nothing
+        // was lost and this is not a failed upgrade. Deliberately does NOT call
+        // onUpgrade(): the backend drops an upgrade suggestion once its target
+        // is in the cart, so refreshing here unmounts this banner and takes the
+        // message with it. Pressing Upgrade again retries the removal alone.
+        setUpgradeError('ORIGINAL_NOT_REMOVED');
+        console.error('Upgraded, but could not remove the original cart item:', err);
+        return;
+      }
       onUpgrade();
     } catch (err) {
+      // The add failed, so the cart is untouched. Say so: logging alone left the
+      // button spinning back to idle with nothing changed and no explanation.
+      setUpgradeError(toAddToCartError(err));
       console.error('Failed to upgrade cart item:', err);
     } finally {
       setUpgrading(false);
@@ -95,9 +174,26 @@ export function CartUpgradeBanner({
       </span>
 
       {/* Text */}
-      <p className="min-w-0 flex-1 text-sm text-foreground">
-        {t('upgradeFor', { name: target.name, amount: formattedDelta })}
-      </p>
+      <div className="min-w-0 flex-1">
+        <p className="text-sm text-foreground">
+          {t('upgradeFor', { name: target.name, amount: formattedDelta })}
+        </p>
+
+        {/*
+          Why the swap did not complete. Without this the button resets, the
+          cart looks unchanged, and the shopper has no idea whether anything
+          happened.
+        */}
+        {upgradeError && (
+          <p role="alert" className="text-destructive mt-1 text-xs font-medium">
+            {upgradeError === 'ORIGINAL_NOT_REMOVED'
+              ? t('upgradeOriginalNotRemoved')
+              : upgradeError === 'CART_FULL'
+                ? tp('cartFull')
+                : tp('addToCartFailed')}
+          </p>
+        )}
+      </div>
 
       {/* Upgrade button */}
       <button

package/templates/nextjs/designs/atelier/ui/product/frequently-bought-together.tsx

@@ -7,6 +7,7 @@ import { formatPrice } from 'brainerce';
 import { useCart, useStoreInfo } from '@/core/providers/store-provider';
 import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 import { IconPlus, IconBag } from '@/ui/shared/icons';
 
@@ -108,6 +109,7 @@ export function FrequentlyBoughtTogether({
 
   const [selected, setSelected] = useState<Set<string>>(() => new Set(crossSells.map((i) => i.id)));
   const [adding, setAdding] = useState(false);
+  const [addError, setAddError] = useState<AddToCartError | null>(null);
 
   if (!storeInfo?.upsell?.frequentlyBoughtTogetherEnabled) return null;
   if (crossSells.length === 0) return null;
@@ -138,6 +140,7 @@ export function FrequentlyBoughtTogether({
 
   async function handleAddAll() {
     if (adding || selected.size === 0) return;
+    setAddError(null);
     try {
       setAdding(true);
       const { getClient } = await import('@/core/lib/brainerce');
@@ -148,6 +151,10 @@ export function FrequentlyBoughtTogether({
       }
       await refreshCart();
     } catch (err) {
+      // The loop is not transactional: if the cart hits its 50-line cap
+      // part-way through, the earlier items ARE in the cart and the rest are
+      // not. Saying so beats a silent stop the shopper reads as a dead button.
+      setAddError(toAddToCartError(err));
       console.error('Failed to add items to cart:', err);
     } finally {
       setAdding(false);
@@ -205,6 +212,16 @@ export function FrequentlyBoughtTogether({
           {adding ? t('addingAll') : t('addSelectedToCart')}
         </button>
       </div>
+
+      {/*
+        Why the add was refused. Some items may already be in the cart:
+        the loop above adds one at a time and stops at the first refusal.
+      */}
+      {addError && (
+        <p role="alert" className="text-destructive mt-3 text-sm font-medium">
+          {addError === 'CART_FULL' ? t('cartFull') : t('addToCartFailed')}
+        </p>
+      )}
     </section>
   );
 }

package/templates/nextjs/designs/atelier/ui/product/product-card.tsx

@@ -16,6 +16,7 @@ import { flyToCart } from '@/ui/shared/fly-to-cart';
 import { openCartDrawer } from '@/ui/cart/cart-drawer';
 import { useCurrency } from '@/core/lib/use-currency';
 import { trackAddToCart } from '@/core/lib/tracking';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 import { IconBag, IconCheck, IconDownload, IconStar } from '@/ui/shared/icons';
 
@@ -63,6 +64,7 @@ export function ProductCard({ product, className }: ProductCardProps) {
 
   const [adding, setAdding] = useState(false);
   const [added, setAdded] = useState(false);
+  const [addError, setAddError] = useState<AddToCartError | null>(null);
 
   // ⛔ A KIT carries NO `inventory` object — its stock is on `kitAvailable`
   // (`null` = unlimited, `0` = not sellable). Reading `inventory` here left a
@@ -86,6 +88,7 @@ export function ProductCard({ product, className }: ProductCardProps) {
     }
 
     if (adding || !canPurchase) return;
+    setAddError(null);
 
     try {
       flyToCart(imageWellRef.current);
@@ -103,6 +106,10 @@ export function ProductCard({ product, className }: ProductCardProps) {
       setAdded(true);
       setTimeout(() => setAdded(false), 2000);
     } catch (err) {
+      // Quick-add used to fail in silence: the button spun, reset, and the
+      // item never appeared. A cart at the 50-line cap is the commonest
+      // cause and the shopper can fix it, so say so on the card.
+      setAddError(toAddToCartError(err));
       console.error('Failed to add to cart:', err);
     } finally {
       setAdding(false);
@@ -245,6 +252,16 @@ export function ProductCard({ product, className }: ProductCardProps) {
             )}
           </button>
         )}
+
+        {/*
+          Quick-add refusal. The card has no other error surface, and without
+          this the shopper taps, the button resets, and nothing appears.
+        */}
+        {addError && (
+          <p role="alert" className="text-destructive mt-2 text-xs">
+            {addError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}
+          </p>
+        )}
       </div>
     </article>
   );

package/templates/nextjs/designs/atelier/ui/product/product-client-section.tsx

@@ -147,6 +147,7 @@ export function ProductClientSection({
     setQuantity,
     addingToCart,
     addedMessage,
+    addToCartError,
     handleAddToCart,
     customizationFields,
     customizationValues,
@@ -434,6 +435,18 @@ export function ProductClientSection({
             </button>
           </div>
 
+          {/*
+            Why the add was refused. Deliberately OUTSIDE the modifier block
+            above: that block only renders when the product HAS modifier
+            groups, so a refusal shown there would be invisible on almost
+            every product and the shopper would just watch the button reset.
+          */}
+          {addToCartError && (
+            <p role="alert" className="text-destructive mt-3 text-sm font-medium">
+              {addToCartError === 'CART_FULL' ? t('cartFull') : t('addToCartFailed')}
+            </p>
+          )}
+
           {/*
             Sold out is not the end of the page. `canOfferStockAlert` is the whole
             gate — it also covers the merchant's switch and backorderable items,

package/templates/nextjs/ui-canvas/cart/cart-bundle-offer.tsx

@@ -6,6 +6,7 @@ import type { CartBundleOffer as CartBundleOfferType } from 'brainerce';
 import { formatPrice } from 'brainerce';
 import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 
 interface CartBundleOfferCardProps {
@@ -24,8 +25,10 @@ interface CartBundleOfferCardProps {
  */
 export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBundleOfferCardProps) {
   const t = useTranslations('cart');
+  const tp = useTranslations('productDetail');
   const currency = useCurrency();
   const [adding, setAdding] = useState(false);
+  const [addError, setAddError] = useState<AddToCartError | null>(null);
 
   const offered = offer.offeredProducts;
 
@@ -38,6 +41,7 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
 
   async function handleAdd() {
     if (adding) return;
+    setAddError(null);
     try {
       setAdding(true);
       const { getClient } = await import('@/core/lib/brainerce');
@@ -47,6 +51,10 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
       await client.addBundleToCart(cartId, offer.id);
       onAdd();
     } catch (err) {
+      // The cart page is where a shopper is most likely to be AT the 50-line
+      // cap, and a bundle adds one line per offered product. Logging alone
+      // left the button spinning back to idle with nothing added.
+      setAddError(toAddToCartError(err));
       console.error('Failed to add bundle:', err);
     } finally {
       setAdding(false);
@@ -84,6 +92,14 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
           {adding ? t('addingBundle') : t('addBundleItem')}
         </button>
       </div>
+
+      {/*
+        Why the bundle was refused. Without this the button resets and
+        nothing is added, which reads as a broken button.
+      */}
+      {addError && (
+        <p role="alert">{addError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}</p>
+      )}
     </article>
   );
 }

package/templates/nextjs/ui-canvas/cart/cart-item.tsx

@@ -9,6 +9,7 @@ import { useTranslations } from '@/core/lib/translations';
 import { useCurrency } from '@/core/lib/use-currency';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { cn } from '@/core/lib/utils';
+import { getErrorCode } from '@/core/lib/add-to-cart-error';
 
 interface CartItemProps {
   item: CartItemType;
@@ -16,6 +17,17 @@ interface CartItemProps {
   className?: string;
 }
 
+/**
+ * Which `cart.*` string each refusal shows. A map rather than a ternary chain:
+ * four outcomes nest badly, and this keeps the copy next to the reason.
+ */
+const LINE_ERROR_KEYS = {
+  NOT_ENOUGH_STOCK: 'notEnoughStock',
+  ITEM_UNAVAILABLE: 'itemUnavailable',
+  UPDATE_FAILED: 'quantityUpdateFailed',
+  REMOVE_FAILED: 'removeFailed',
+} as const;
+
 /**
  * DESIGN ME — single cart line: image, name, variant, unit price, quantity
  * controls, remove, line total; the `item` prop comes from useCartPage().cart.
@@ -25,9 +37,14 @@ interface CartItemProps {
 export function CartItem({ item, onUpdate, className }: CartItemProps) {
   const t = useTranslations('common');
   const td = useTranslations('productDetail');
+  const tc = useTranslations('cart');
   const currency = useCurrency();
   const [updating, setUpdating] = useState(false);
   const [removing, setRemoving] = useState(false);
+  // Why the last quantity change or removal did not take. Both calls used to
+  // fail into console.error alone: the row snapped back to the quantity it
+  // already had, or stayed put after Remove, and nothing on screen said why.
+  const [lineError, setLineError] = useState<keyof typeof LINE_ERROR_KEYS | null>(null);
 
   const productName = item.product.name;
   const imageUrl = getCartItemImage(item);
@@ -49,12 +66,29 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   async function handleQuantityChange(newQuantity: number) {
     if (newQuantity < 1 || updating) return;
 
+    setLineError(null);
     try {
       setUpdating(true);
       const client = getClient();
       await client.smartUpdateCartItem(item.productId, newQuantity, item.variantId || undefined);
       onUpdate();
     } catch (err) {
+      // Two of these refusals are PERMANENT, and "please try again" would send
+      // the shopper round a loop that cannot succeed: INSUFFICIENT_STOCK (more
+      // than the inventory left) and PRODUCT_UNAVAILABLE (the line cannot be
+      // bought at all any more). Both get their own sentence; everything else
+      // is a blip worth one more tap. The 50-line cart cap is NOT a cause here
+      // at all, it only ever refuses a brand new line. Both codes are part of
+      // the documented API error catalogue, not guesses. Keep the log: the
+      // shopper gets the sentence, the developer still needs the detail.
+      const code = getErrorCode(err);
+      setLineError(
+        code === 'INSUFFICIENT_STOCK'
+          ? 'NOT_ENOUGH_STOCK'
+          : code === 'PRODUCT_UNAVAILABLE'
+            ? 'ITEM_UNAVAILABLE'
+            : 'UPDATE_FAILED'
+      );
       console.error('Failed to update quantity:', err);
     } finally {
       setUpdating(false);
@@ -64,12 +98,17 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   async function handleRemove() {
     if (removing) return;
 
+    setLineError(null);
     try {
       setRemoving(true);
       const client = getClient();
       await client.smartRemoveFromCart(item.productId, item.variantId || undefined);
       onUpdate();
     } catch (err) {
+      // Nothing is lost when a remove fails, so the line is still there and
+      // still correct. Say so anyway: a Remove that visibly does nothing reads
+      // as a broken button.
+      setLineError('REMOVE_FAILED');
       console.error('Failed to remove item:', err);
     } finally {
       setRemoving(false);
@@ -128,6 +167,13 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
             {removing ? t('removing') : t('remove')}
           </button>
         </div>
+
+        {/*
+          Why the quantity change or the removal did not take. Keep it inside
+          this line's own column: it describes THIS row, and a shopper with ten
+          rows on screen has to be able to tell which one refused.
+        */}
+        {lineError && <p role="alert">{tc(LINE_ERROR_KEYS[lineError])}</p>}
       </div>
 
       {/* Line total */}