create-brainerce-store 1.79.0 → 1.81.0

package/templates/nextjs/base/scripts/connect.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Connect this storefront to a Brainerce sales channel.
+ *
+ * Run it when the build is finished, not before:
+ *
+ *   npm run connect
+ *
+ * WHY THIS IS A SEPARATE STEP. Nothing in a storefront's code depends on WHICH
+ * store it points at — the pages, the routing, the cart, the checkout and every
+ * SDK call are identical either way. Only one environment variable differs. So
+ * a run scaffolded with `--defer-connection` builds the whole storefront
+ * uninterrupted and comes here at the end, instead of stopping for an approval
+ * before a single file exists.
+ *
+ * One click in a browser, and this writes the id into `.env.local`. A store and
+ * a sales channel are created for you if you have neither.
+ *
+ * ⛔ NEVER PROMPTS. This is run by coding agents in shells with no TTY, where a
+ * prompt does not fail — it hangs. Everything is printed and polled.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+
+const API_BASE = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(/\/$/, '');
+const ENV_PATH = resolve(process.cwd(), '.env.local');
+const KEYS = ['NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID', 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID'];
+
+/** Only ever hand the OS a URL on the host we asked. It arrives in a network
+ *  response, so it is untrusted input on the way to a process launch. */
+function openable(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return false;
+    const base = new URL(API_BASE).hostname.replace(/^api(-staging)?\./, '');
+    return url.hostname === base || url.hostname.endsWith(`.${base}`);
+  } catch {
+    return false;
+  }
+}
+
+function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : process.platform === 'darwin'
+        ? ['open', [url]]
+        : ['xdg-open', [url]];
+  try {
+    // No shell, argument array: the URL cannot become a command.
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Rewrite in place so hand-added variables survive. A blind overwrite here
+ *  would silently drop a payment key someone pasted in an hour earlier. */
+function writeEnv(connectionId) {
+  let body = existsSync(ENV_PATH) ? readFileSync(ENV_PATH, 'utf8') : '';
+  for (const key of KEYS) {
+    const line = `${key}=${connectionId}`;
+    const pattern = new RegExp(`^${key}=.*$`, 'm');
+    body = pattern.test(body) ? body.replace(pattern, line) : `${body.trimEnd()}\n${line}\n`;
+  }
+  writeFileSync(ENV_PATH, body.startsWith('\n') ? body.slice(1) : body);
+}
+
+async function main() {
+  if (process.env.BRAINERCE_CONNECTION_ID) {
+    // Already known (CI, or a channel someone created by hand). Nothing to approve.
+    writeEnv(process.env.BRAINERCE_CONNECTION_ID.trim());
+    console.log('Wrote BRAINERCE_CONNECTION_ID from the environment into .env.local.');
+    return;
+  }
+
+  let start;
+  try {
+    const res = await fetch(`${API_BASE}/api/device-auth/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientName: process.env.BRAINERCE_CLIENT_NAME || 'this storefront' }),
+    });
+    if (!res.ok) {
+      console.error(`Could not start the approval (HTTP ${res.status}).`);
+      console.error('Create a sales channel in the dashboard, then set the id in .env.local.');
+      process.exit(1);
+    }
+    start = await res.json();
+  } catch (error) {
+    console.error(`Could not reach Brainerce: ${error?.message ?? error}`);
+    process.exit(1);
+  }
+
+  const opened = openable(start.verificationUriComplete) && openBrowser(start.verificationUriComplete);
+  console.log('');
+  console.log(opened ? 'Opened your browser to approve this connection.' : 'Open this link to approve:');
+  console.log(`  ${start.verificationUriComplete}`);
+  // The code is the only thing a person can actually check: it proves the
+  // request came from this run and not from someone else's.
+  console.log(`  The page should show the code ${start.userCode}. Check that it matches.`);
+  console.log('');
+  console.log('Waiting for approval. A store and a sales channel are created if you have none.');
+
+  const deadline = Date.now() + start.expiresIn * 1000;
+  let interval = (start.interval || 5) * 1000;
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, interval));
+    let result;
+    try {
+      const res = await fetch(`${API_BASE}/api/device-auth/poll`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceCode: start.deviceCode }),
+      });
+      result = await res.json();
+    } catch {
+      continue; // A blip mid-poll is not fatal; the deadline is the real bound.
+    }
+    if (result.status === 'approved' && result.connectionId) {
+      writeEnv(result.connectionId);
+      console.log('');
+      console.log('Connected. The sales channel id is in .env.local.');
+      console.log('Start the storefront with: npm run dev');
+      return;
+    }
+    if (result.status === 'denied') {
+      console.error('The connection request was declined. Nothing was created.');
+      process.exit(1);
+    }
+    if (result.status === 'expired') {
+      console.error('The code expired before it was approved. Run this again.');
+      process.exit(1);
+    }
+    // Polled inside the interval: back off rather than hammering.
+    if (result.status === 'slow_down') interval += 1000;
+  }
+
+  console.error('Timed out waiting for approval. Run this again for a fresh code.');
+  process.exit(1);
+}
+
+main();

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

@@ -31,6 +31,7 @@ import { GiftCardInput } from '@/ui/cart/gift-card-input';
 import { ReservationCountdown } from '@/ui/cart/reservation-countdown';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 import { isValidCheckoutId } from '@/core/lib/safe-redirect';
 import { trackBeginCheckout } from '@/core/lib/tracking';
@@ -52,6 +53,7 @@ function CheckoutContent() {
   const t = useTranslations('checkout');
   const tc = useTranslations('common');
   const tr = useTranslations('reservation');
+  const tp = useTranslations('productDetail');
 
   const [step, setStep] = useState<CheckoutStep>('address');
   const [checkout, setCheckout] = useState<Checkout | null>(null);
@@ -77,6 +79,7 @@ function CheckoutContent() {
   const [orderBumps, setOrderBumps] = useState<CheckoutBumpsResponse | null>(null);
   const [addedBumpIds, setAddedBumpIds] = useState<Set<string>>(new Set());
   const [bumpLoading, setBumpLoading] = useState<string | null>(null);
+  const [bumpError, setBumpError] = useState<AddToCartError | null>(null);
   const [customFields, setCustomFields] = useState<CheckoutCustomFieldDefinition[]>([]);
   const [customFieldValues, setCustomFieldValues] = useState<Record<string, unknown>>({});
   const [customFieldsLoading, setCustomFieldsLoading] = useState(false);
@@ -354,6 +357,7 @@ function CheckoutContent() {
   // Handle bump toggle
   async function handleBumpToggle(bumpId: string, add: boolean, variantId?: string) {
     if (!cart?.id || bumpLoading) return;
+    setBumpError(null);
     try {
       setBumpLoading(bumpId);
       const client = getClient();
@@ -370,6 +374,10 @@ function CheckoutContent() {
       }
       await refreshCart();
     } catch (err) {
+      // A bump is an extra cart line, so it can be refused by the 50-line cap
+      // like any other add. Logging alone left the checkbox springing back with
+      // no explanation, at the least forgiving point in the flow.
+      setBumpError(toAddToCartError(err));
       console.error('Failed to toggle order bump:', err);
     } finally {
       setBumpLoading(null);
@@ -1044,6 +1052,16 @@ function CheckoutContent() {
                     loading={bumpLoading === bump.id}
                   />
                 ))}
+
+                {/*
+                  Why the bump was refused. Without it the checkbox just springs
+                  back and the shopper is left guessing at checkout.
+                */}
+                {bumpError && (
+                  <p className="text-destructive text-xs" role="alert">
+                    {bumpError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}
+                  </p>
+                )}
               </div>
             )}
 

package/templates/nextjs/base/src/components/account/profile-section.tsx

@@ -7,6 +7,7 @@ import { useTranslations } from '@/core/lib/translations';
 import { cn } from '@/core/lib/utils';
 import { birthMonthKey, toBirthdayNumber } from '@/core/lib/birthday';
 import { BirthdayPicker } from '@/components/shared/birthday-picker';
+import { useStoreCapabilities } from '@/core/providers/store-provider';
 
 interface ProfileSectionProps {
   profile: CustomerProfile;
@@ -17,6 +18,9 @@ interface ProfileSectionProps {
 export function ProfileSection({ profile, onProfileUpdate, className }: ProfileSectionProps) {
   const t = useTranslations('account');
   const tc = useTranslations('common');
+  const { capabilities } = useStoreCapabilities();
+  /** Explicit `true` only — see the note on the same gate in `register-form.tsx`. */
+  const birthdayGiftOn = capabilities?.features.hasBirthdayRewards === true;
   const [editing, setEditing] = useState(false);
   const [saving, setSaving] = useState(false);
   const [message, setMessage] = useState<{ type: 'success' | 'error'; text: string } | null>(null);
@@ -182,7 +186,9 @@ export function ProfileSection({ profile, onProfileUpdate, className }: ProfileS
                   onChange={selectBirthday}
                   triggerClassName="rounded-md"
                 />
-                <p className="text-muted-foreground mt-1 text-xs">{tc('birthdayGiftNote')}</p>
+                {birthdayGiftOn && (
+                  <p className="text-muted-foreground mt-1 text-xs">{tc('birthdayGiftNote')}</p>
+                )}
               </div>
               <p className="text-muted-foreground truncate text-sm">{profile.email}</p>
               <div className="flex items-center gap-2">

package/templates/nextjs/base/src/components/auth/register-form.tsx

@@ -9,6 +9,7 @@ import { useStoreInfo } from '@/core/providers/store-provider';
 import { toBirthdayNumber } from '@/core/lib/birthday';
 import { BirthdayPicker } from '@/components/shared/birthday-picker';
 import { readReferralCookie } from '@/core/lib/referral';
+import { useStoreCapabilities } from '@/core/providers/store-provider';
 
 interface RegisterData {
   firstName: string;
@@ -66,6 +67,20 @@ export function RegisterForm({ onSubmit, error, className }: RegisterFormProps)
   const [privacyError, setPrivacyError] = useState(false);
   const [passwordError, setPasswordError] = useState<string | null>(null);
   const [acceptsMarketing, setAcceptsMarketing] = useState(false);
+  const { capabilities } = useStoreCapabilities();
+
+  /**
+   * Whether to promise a birthday gift beside the picker.
+   *
+   * The gate is inverted relative to `ReferralGreeting`, and deliberately so.
+   * There, an undecided capability must not suppress a real referral, so only
+   * an explicit `false` hides anything. Here the text makes a PROMISE, and a
+   * promise may only be printed on an explicit `true`: a store with birthday
+   * rewards switched off — which is the default — would otherwise tell every
+   * customer a gift is coming and send nothing, and `requireBirthday` can make
+   * handing over the date compulsory on top of that.
+   */
+  const birthdayGiftOn = capabilities?.features.hasBirthdayRewards === true;
   const [birthMonth, setBirthMonth] = useState('');
   const [birthDay, setBirthDay] = useState('');
   const [birthdayError, setBirthdayError] = useState<string | null>(null);
@@ -293,7 +308,9 @@ export function RegisterForm({ onSubmit, error, className }: RegisterFormProps)
           required={birthdayRequired}
           invalid={birthdayError !== null}
         />
-        <p className="text-muted-foreground mt-1.5 text-xs">{tc('birthdayGiftNote')}</p>
+        {birthdayGiftOn && (
+          <p className="text-muted-foreground mt-1.5 text-xs">{tc('birthdayGiftNote')}</p>
+        )}
         {birthdayError && <p className="text-destructive mt-1 text-xs">{birthdayError}</p>}
       </div>
 

package/templates/nextjs/base/src/components/tracking-bootstrap.tsx

@@ -12,7 +12,7 @@ import { useStoreInfo } from '@/core/providers/store-provider';
  *
  * There is nothing to configure here and no environment variable to set. The
  * tag ids arrive inside `storeInfo.tracking`, which the backend resolves from
- * the merchant's connected marketplace apps: connecting the Google & YouTube
+ * the merchant's connected marketplace apps: connecting the Google
  * app runs GA4 discovery and the measurement id shows up on its own, likewise
  * the Meta and TikTok pixels. Connect an app in the dashboard and this file
  * starts loading its tag within a minute — no redeploy, no code change.

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

@@ -12,6 +12,7 @@ import type {
 } from 'brainerce';
 import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
 import { resolveDisplayPrice, type DisplayPrice } from '@/core/lib/display-price';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { resolveStockInfo } from '@/core/lib/kit';
 import { useCart, useStoreInfo } from '@/core/providers/store-provider';
 import { trackAddToCart, trackProductView } from '@/core/lib/tracking';
@@ -74,6 +75,16 @@ export interface UseProductPageResult {
   /** Add-to-cart state machine. */
   addingToCart: boolean;
   addedMessage: boolean;
+  /**
+   * Set when the server refused the add, cleared on the next attempt.
+   *
+   * ⛔ Render this OUTSIDE any `modifierGroups.length > 0` block. `modifierError`
+   * below lives inside one in every design, which is correct for a modifier
+   * message and useless here: most products carry no modifier groups, so a
+   * refusal shown there would render nothing at all and the shopper would tap
+   * "Add to cart" and watch it silently reset.
+   */
+  addToCartError: AddToCartError | null;
   handleAddToCart: () => Promise<void>;
   /** Customization (buyer input) sub-contract. */
   customizationFields: ProductCustomizationField[];
@@ -115,6 +126,7 @@ export function useProductPage(initialProduct: Product): UseProductPageResult {
   const [quantity, setQuantity] = useState(1);
   const [addingToCart, setAddingToCart] = useState(false);
   const [addedMessage, setAddedMessage] = useState(false);
+  const [addToCartError, setAddToCartError] = useState<AddToCartError | null>(null);
   const customizationFields = product.customizationFields ?? [];
   const [customizationValues, setCustomizationValues] = useState<CustomizationValues>(() => {
     const initial: CustomizationValues = {};
@@ -250,6 +262,10 @@ export function useProductPage(initialProduct: Product): UseProductPageResult {
   async function handleAddToCart() {
     if (!product || addingToCart) return;
 
+    // Clear the previous refusal before re-trying, so a stale "cart is full"
+    // does not sit under a button that has since succeeded.
+    setAddToCartError(null);
+
     if (customizationFields.length > 0) {
       const errs = validateCustomization(customizationFields, customizationValues);
       if (Object.keys(errs).length > 0) {
@@ -305,6 +321,11 @@ export function useProductPage(initialProduct: Product): UseProductPageResult {
       if (e?.details?.code === 'MODIFIER_VALIDATION_FAILED' && validationErrors?.length) {
         setModifierError(validationErrors.map((v) => v.message).join('; '));
       } else {
+        // Everything else used to stop at `console.error`, which the shopper
+        // cannot read: the button spun, reset, and the item never appeared.
+        // The commonest cause is now the 50-line cart cap, which is entirely
+        // actionable, so give the UI a code to render and keep the log for us.
+        setAddToCartError(toAddToCartError(err));
         console.error('Failed to add to cart:', err);
       }
     } finally {
@@ -330,6 +351,7 @@ export function useProductPage(initialProduct: Product): UseProductPageResult {
     setQuantity,
     addingToCart,
     addedMessage,
+    addToCartError,
     handleAddToCart,
     customizationFields,
     customizationValues,

package/templates/nextjs/base/src/core/lib/add-to-cart-error.ts

@@ -0,0 +1,49 @@
+/**
+ * Add-to-cart refusals the shopper has to be told about.
+ *
+ * Lives in `core/` and returns a CODE, never a message: `ui/` owns the copy, so
+ * each design maps this to its own `productDetail.*` string rather than showing
+ * the raw API sentence. Shared by the product page hook and the grid quick-add.
+ */
+export type AddToCartError = 'CART_FULL' | 'FAILED';
+
+/**
+ * The API's stable, machine-readable error code for a failed call, or
+ * `undefined` when the failure carried none (a network drop, a timeout, an
+ * older backend).
+ *
+ * Where it comes from: the API answers an error as
+ * `{ statusCode, code, message, details?, timestamp, path }`, and the SDK hands
+ * that whole body back as `BrainerceError.details`. So the code lives one level
+ * in, at `err.details.code` — not on the error itself. Read it rather than the
+ * message: the message is human-readable prose that changes freely (and is
+ * English regardless of the shopper's language), the code does not.
+ */
+export function getErrorCode(err: unknown): string | undefined {
+  const body = (err as { details?: { code?: unknown } } | null)?.details;
+  return typeof body?.code === 'string' ? body.code : undefined;
+}
+
+/**
+ * A storefront cart holds at most 50 DISTINCT product lines. The 51st add is
+ * refused with `400 CART_LINE_LIMIT_REACHED`.
+ *
+ * The cap applies to storefront traffic only (`storeId` and `vc_*` modes). It
+ * does NOT block quantity changes or removals, so "remove something first" is
+ * advice the shopper can actually act on.
+ *
+ * The message match is a FALLBACK, kept only for the window where a storefront
+ * built from this template talks to a backend older than the code. Once the
+ * backend carrying `CART_LINE_LIMIT_REACHED` is live everywhere, the regex can
+ * go: every storefront talks to the current API, so the code is always there.
+ * It cannot produce a false `CART_FULL` in the meantime, which is why it costs
+ * nothing to keep until then.
+ *
+ * Anything unrecognised falls through to `FAILED`, which is still a visible
+ * message rather than the silence this replaced.
+ */
+export function toAddToCartError(err: unknown): AddToCartError {
+  if (getErrorCode(err) === 'CART_LINE_LIMIT_REACHED') return 'CART_FULL';
+  const message = (err as { message?: string } | null)?.message ?? '';
+  return /cart can hold at most/i.test(message) ? 'CART_FULL' : 'FAILED';
+}

package/templates/nextjs/base/src/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 { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Card } from '@/components/ui/card';
@@ -21,8 +22,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;
 
@@ -35,6 +38,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');
@@ -44,6 +48,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);
@@ -112,6 +120,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>
+      )}
     </Card>
   );
 }

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

@@ -10,6 +10,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';
 
 interface CartItemProps {
@@ -18,12 +19,28 @@ 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;
+
 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);
@@ -45,12 +62,28 @@ 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. 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);
@@ -60,12 +93,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);
@@ -161,6 +199,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">
+            {tc(LINE_ERROR_KEYS[lineError])}
+          </p>
+        )}
       </div>
 
       {/* Line total */}