create-brainerce-store 1.78.0 → 1.80.0

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

@@ -1,328 +1,343 @@
-'use client';
-
-import { useEffect, useRef, useState, useMemo } from 'react';
-import type {
-  Product,
-  ProductCustomizationField,
-  ProductImage,
-  ProductRecommendationsResponse,
-  ProductVariant,
-  InventoryInfo,
-  ModifierGroup,
-} from 'brainerce';
-import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
-import { resolveDisplayPrice, type DisplayPrice } from '@/core/lib/display-price';
-import { useCart, useStoreInfo } from '@/core/providers/store-provider';
-import { trackAddToCart, trackProductView } from '@/core/lib/tracking';
-import {
-  buildInitialSelections,
-  toModifierSelections,
-  validateCustomization,
-  validateSelections,
-  type CustomizationValues,
-} from '@/core/lib/product-options';
-
-export interface ProductPriceInfo {
-  price: number;
-  originalPrice: number;
-  isOnSale: boolean;
-  discountAmount?: number;
-  discountPercent: number;
-}
-
-export interface UseProductPageResult {
-  product: Product;
-  recommendations: ProductRecommendationsResponse | null;
-  /** Product image list. */
-  images: ProductImage[];
-  /** Index into `images`; -1 means "variant image not in the list". */
-  selectedImageIndex: number;
-  setSelectedImageIndex: (index: number) => void;
-  /** URL of the image to show as the main image (variant-aware). */
-  mainImageUrl: string | null;
-  /** Variant selection. */
-  selectedVariant: ProductVariant | null;
-  setSelectedVariant: (variant: ProductVariant | null) => void;
-  /**
-   * Effective price info in the STORE currency (variant price + discount-rule
-   * overlay).
-   *
-   * ⛔ This is the CHARGED amount, and it is what feeds `view_item` /
-   * `add_to_cart`. Analytics revenue has to be one currency across the store,
-   * so do NOT swap in a converted figure here. Render `displayPrice` instead.
-   */
-  priceInfo: ProductPriceInfo;
-  /**
-   * The price to RENDER, region-aware: the FX-converted amounts when the
-   * product was read with a `regionId` whose currency differs from the store's,
-   * and `priceInfo` in the store currency otherwise.
-   *
-   * ⛔ Pass `displayPrice.currency` to `<PriceDisplay currency>` alongside the
-   * numbers. It defaults to the store currency, so a converted amount rendered
-   * without it is a euro figure wearing a dollar sign.
-   */
-  displayPrice: DisplayPrice;
-  /** Variant inventory when a variant is selected, else product inventory. */
-  inventory: InventoryInfo | null;
-  canPurchase: boolean;
-  /** Resolved description content ({ html } or { text }). */
-  description: ReturnType<typeof getDescriptionContent> | null;
-  /** Quantity picker. */
-  quantity: number;
-  setQuantity: (update: number | ((q: number) => number)) => void;
-  /** Add-to-cart state machine. */
-  addingToCart: boolean;
-  addedMessage: boolean;
-  handleAddToCart: () => Promise<void>;
-  /** Customization (buyer input) sub-contract. */
-  customizationFields: ProductCustomizationField[];
-  customizationValues: CustomizationValues;
-  setCustomizationValues: (values: CustomizationValues) => void;
-  customizationErrors: Record<string, string>;
-  /** Modifier groups (toppings, sauce, …) sub-contract. */
-  modifierGroups: ModifierGroup[];
-  modifierSelections: Record<string, string[]>;
-  setModifierSelection: (groupId: string, next: string[]) => void;
-  modifierError: string | null;
-}
-
-/**
- * Product-page behavior: variant selection, variant-aware image + price +
- * inventory resolution, quantity, customization + modifier state and
- * validation, and the add-to-cart state machine. Pure data/behavior —
- * rendering lives in `ui/product/product-client-section.tsx`.
- */
-export function useProductPage(initialProduct: Product): UseProductPageResult {
-  const { refreshCart } = useCart();
-  const { storeInfo } = useStoreInfo();
-  const currency = storeInfo?.currency;
-
-  const product = initialProduct;
-  const recommendations = product?.recommendations ?? null;
-
-  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(
-    product.variants && product.variants.length > 0 ? product.variants[0] : null
-  );
-  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
-  const [quantity, setQuantity] = useState(1);
-  const [addingToCart, setAddingToCart] = useState(false);
-  const [addedMessage, setAddedMessage] = useState(false);
-  const customizationFields = product.customizationFields ?? [];
-  const [customizationValues, setCustomizationValues] = useState<CustomizationValues>(() => {
-    const initial: CustomizationValues = {};
-    for (const field of customizationFields) {
-      if (field.defaultValue != null) initial[field.key] = field.defaultValue;
-    }
-    return initial;
-  });
-  const [customizationErrors, setCustomizationErrors] = useState<Record<string, string>>({});
-
-  // Modifier groups (PRD §8.4) — only present on restaurant / build-your-own products.
-  const modifierGroups: ModifierGroup[] = useMemo(
-    () => (product as Product & { modifierGroups?: ModifierGroup[] }).modifierGroups ?? [],
-    [product]
-  );
-  const [modifierSelections, setModifierSelections] = useState<Record<string, string[]>>(() =>
-    buildInitialSelections(modifierGroups)
-  );
-  const [modifierError, setModifierError] = useState<string | null>(null);
-
-  function setModifierSelection(groupId: string, next: string[]) {
-    setModifierSelections((prev) => ({ ...prev, [groupId]: next }));
-  }
-
-  // Images list - switch main image when variant changes
-  const images: ProductImage[] = useMemo(() => {
-    return product?.images || [];
-  }, [product]);
-
-  // When variant changes, update selected image to variant image if available
-  useEffect(() => {
-    if (!selectedVariant?.image || !product) return;
-
-    const variantImgUrl =
-      typeof selectedVariant.image === 'string' ? selectedVariant.image : selectedVariant.image.url;
-
-    // Find if variant image exists in product images
-    const idx = images.findIndex((img) => img.url === variantImgUrl);
-    if (idx >= 0) {
-      setSelectedImageIndex(idx);
-    } else {
-      // Variant image not in product images - select index 0 as fallback
-      setSelectedImageIndex(-1);
-    }
-  }, [selectedVariant, images, product]);
-
-  // Determine which image to show
-  const mainImageUrl = useMemo(() => {
-    if (selectedImageIndex === -1 && selectedVariant?.image) {
-      const img = selectedVariant.image;
-      return typeof img === 'string' ? img : img.url;
-    }
-    return images[selectedImageIndex]?.url || null;
-  }, [selectedImageIndex, selectedVariant, images]);
-
-  // Price info - use variant price if selected, else product price
-  const priceInfo = useMemo(() => {
-    if (selectedVariant?.price) {
-      const variantBase = parseFloat(selectedVariant.price);
-      const variantSale = selectedVariant.salePrice ? parseFloat(selectedVariant.salePrice) : null;
-      const variantEffective =
-        variantSale != null && variantSale < variantBase ? variantSale : variantBase;
-
-      // Overlay any product-level discount rule onto the variant price using the rule's ratio
-      if (product.discount) {
-        const ruleOriginal = parseFloat(product.discount.originalPrice) || 0;
-        const ruleDiscounted = parseFloat(product.discount.discountedPrice) || 0;
-        const ratio = ruleOriginal > 0 ? ruleDiscounted / ruleOriginal : 1;
-        const discounted = variantEffective * ratio;
-        const amount = Math.max(0, variantEffective - discounted);
-        return {
-          price: discounted,
-          originalPrice: variantEffective,
-          isOnSale: discounted < variantEffective,
-          discountAmount: amount,
-          discountPercent: variantEffective > 0 ? Math.round((amount / variantEffective) * 100) : 0,
-        };
-      }
-
-      return {
-        price: variantEffective,
-        originalPrice: variantBase,
-        isOnSale: variantEffective < variantBase,
-        discountPercent:
-          variantEffective < variantBase && variantBase > 0
-            ? Math.round(((variantBase - variantEffective) / variantBase) * 100)
-            : 0,
-      };
-    }
-    return getProductPriceInfo(product);
-  }, [product, selectedVariant]);
-
-  // Region display pricing, variant-aware. The selected variant carries its own
-  // FX fields; fall back to the product's, then to the store-currency figures
-  // above. Same helper the product card uses, so a card and the page it opens
-  // can never quote different currencies for the same item.
-  const displayPrice = useMemo<DisplayPrice>(() => {
-    const fallback = {
-      price: priceInfo.originalPrice,
-      salePrice: priceInfo.isOnSale ? priceInfo.price : null,
-    };
-    const source = selectedVariant?.displayPrice != null ? selectedVariant : product;
-    return resolveDisplayPrice(source, fallback, currency);
-  }, [product, selectedVariant, priceInfo, currency]);
-
-  // Inventory: use variant inventory if selected, else product inventory
-  const inventory = selectedVariant?.inventory ?? product?.inventory ?? null;
-  const canPurchase = inventory?.canPurchase !== false;
-
-  // Description
-  const description = useMemo(() => {
-    return product ? getDescriptionContent(product) : null;
-  }, [product]);
-
-  // `view_item` — the event Meta and Google build remarketing audiences from.
-  // The ref keeps it to once per product rather than once per render: the
-  // shopper is looking at one product, and re-firing on every swatch click or
-  // quantity change would inflate the audience with phantom views.
-  const viewedProductIdRef = useRef<string | null>(null);
-  useEffect(() => {
-    if (!product || viewedProductIdRef.current === product.id) return;
-    viewedProductIdRef.current = product.id;
-    trackProductView(product, selectedVariant, priceInfo.price, currency);
-  }, [product, selectedVariant, priceInfo.price, currency]);
-
-  async function handleAddToCart() {
-    if (!product || addingToCart) return;
-
-    if (customizationFields.length > 0) {
-      const errs = validateCustomization(customizationFields, customizationValues);
-      if (Object.keys(errs).length > 0) {
-        setCustomizationErrors(errs);
-        return;
-      }
-    }
-    setCustomizationErrors({});
-
-    // Client-side modifier validation mirrors the server's checks. The server
-    // is authoritative — `MODIFIER_VALIDATION_FAILED` envelope on add-to-cart
-    // failure is the source of truth — but pre-flighting catches the obvious
-    // issues without a round-trip.
-    if (modifierGroups.length > 0) {
-      const error = validateSelections(modifierGroups, modifierSelections);
-      if (error) {
-        setModifierError(error);
-        return;
-      }
-    }
-    setModifierError(null);
-
-    const selections =
-      modifierGroups.length > 0
-        ? toModifierSelections(modifierGroups, modifierSelections)
-        : undefined;
-
-    try {
-      setAddingToCart(true);
-      const { getClient } = await import('@/core/lib/brainerce');
-      const client = getClient();
-      await client.smartAddToCart({
-        productId: product.id,
-        variantId: selectedVariant?.id,
-        quantity,
-        metadata:
-          customizationFields.length > 0 && Object.keys(customizationValues).length > 0
-            ? customizationValues
-            : undefined,
-        ...(selections && selections.length > 0 ? { selections } : {}),
-      });
-      await refreshCart();
-      // Report only after the server accepted the line — an add that failed
-      // validation is not an add-to-cart, and feeding the ad platforms events
-      // that never became cart lines poisons their conversion modelling.
-      trackAddToCart(product, selectedVariant, quantity, priceInfo.price, currency);
-      setAddedMessage(true);
-      setTimeout(() => setAddedMessage(false), 2000);
-    } catch (err) {
-      // Surface the structured `MODIFIER_VALIDATION_FAILED` envelope when present.
-      const e = err as { details?: { code?: string; errors?: Array<{ message: string }> } };
-      const validationErrors = e?.details?.errors;
-      if (e?.details?.code === 'MODIFIER_VALIDATION_FAILED' && validationErrors?.length) {
-        setModifierError(validationErrors.map((v) => v.message).join('; '));
-      } else {
-        console.error('Failed to add to cart:', err);
-      }
-    } finally {
-      setAddingToCart(false);
-    }
-  }
-
-  return {
-    product,
-    recommendations,
-    images,
-    selectedImageIndex,
-    setSelectedImageIndex,
-    mainImageUrl,
-    selectedVariant,
-    setSelectedVariant,
-    priceInfo,
-    displayPrice,
-    inventory,
-    canPurchase,
-    description,
-    quantity,
-    setQuantity,
-    addingToCart,
-    addedMessage,
-    handleAddToCart,
-    customizationFields,
-    customizationValues,
-    setCustomizationValues,
-    customizationErrors,
-    modifierGroups,
-    modifierSelections,
-    setModifierSelection,
-    modifierError,
-  };
-}
+'use client';
+
+import { useEffect, useRef, useState, useMemo } from 'react';
+import type {
+  Product,
+  ProductCustomizationField,
+  ProductImage,
+  ProductRecommendationsResponse,
+  ProductVariant,
+  InventoryInfo,
+  ModifierGroup,
+} from 'brainerce';
+import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
+import { resolveDisplayPrice, type DisplayPrice } from '@/core/lib/display-price';
+import { resolveStockInfo } from '@/core/lib/kit';
+import { useCart, useStoreInfo } from '@/core/providers/store-provider';
+import { trackAddToCart, trackProductView } from '@/core/lib/tracking';
+import {
+  buildInitialSelections,
+  toModifierSelections,
+  validateCustomization,
+  validateSelections,
+  type CustomizationValues,
+} from '@/core/lib/product-options';
+
+export interface ProductPriceInfo {
+  price: number;
+  originalPrice: number;
+  isOnSale: boolean;
+  discountAmount?: number;
+  discountPercent: number;
+}
+
+export interface UseProductPageResult {
+  product: Product;
+  recommendations: ProductRecommendationsResponse | null;
+  /** Product image list. */
+  images: ProductImage[];
+  /** Index into `images`; -1 means "variant image not in the list". */
+  selectedImageIndex: number;
+  setSelectedImageIndex: (index: number) => void;
+  /** URL of the image to show as the main image (variant-aware). */
+  mainImageUrl: string | null;
+  /** Variant selection. */
+  selectedVariant: ProductVariant | null;
+  setSelectedVariant: (variant: ProductVariant | null) => void;
+  /**
+   * Effective price info in the STORE currency (variant price + discount-rule
+   * overlay).
+   *
+   * ⛔ This is the CHARGED amount, and it is what feeds `view_item` /
+   * `add_to_cart`. Analytics revenue has to be one currency across the store,
+   * so do NOT swap in a converted figure here. Render `displayPrice` instead.
+   */
+  priceInfo: ProductPriceInfo;
+  /**
+   * The price to RENDER, region-aware: the FX-converted amounts when the
+   * product was read with a `regionId` whose currency differs from the store's,
+   * and `priceInfo` in the store currency otherwise.
+   *
+   * ⛔ Pass `displayPrice.currency` to `<PriceDisplay currency>` alongside the
+   * numbers. It defaults to the store currency, so a converted amount rendered
+   * without it is a euro figure wearing a dollar sign.
+   */
+  displayPrice: DisplayPrice;
+  /** Variant inventory when a variant is selected, else product inventory. */
+  inventory: InventoryInfo | null;
+  canPurchase: boolean;
+  /** Resolved description content ({ html } or { text }). */
+  description: ReturnType<typeof getDescriptionContent> | null;
+  /** Quantity picker. */
+  quantity: number;
+  setQuantity: (update: number | ((q: number) => number)) => void;
+  /** Add-to-cart state machine. */
+  addingToCart: boolean;
+  addedMessage: boolean;
+  handleAddToCart: () => Promise<void>;
+  /** Customization (buyer input) sub-contract. */
+  customizationFields: ProductCustomizationField[];
+  customizationValues: CustomizationValues;
+  setCustomizationValues: (values: CustomizationValues) => void;
+  customizationErrors: Record<string, string>;
+  /** Modifier groups (toppings, sauce, …) sub-contract. */
+  modifierGroups: ModifierGroup[];
+  modifierSelections: Record<string, string[]>;
+  setModifierSelection: (groupId: string, next: string[]) => void;
+  modifierError: string | null;
+}
+
+/**
+ * Product-page behavior: variant selection, variant-aware image + price +
+ * inventory resolution, quantity, customization + modifier state and
+ * validation, and the add-to-cart state machine. Pure data/behavior —
+ * rendering lives in `ui/product/product-client-section.tsx`.
+ */
+export function useProductPage(initialProduct: Product): UseProductPageResult {
+  const { refreshCart } = useCart();
+  const { storeInfo } = useStoreInfo();
+  const currency = storeInfo?.currency;
+
+  const product = initialProduct;
+  const recommendations = product?.recommendations ?? null;
+
+  // ⛔ Never pre-select a variant on a KIT. A kit is added to the cart as ONE
+  // line using its own `productId`, and add-to-cart rejects a kit carrying a
+  // `variantId` with a 400 — so an auto-selected variant would make the buy
+  // button fail. Kits carry no variants today; this keeps that from becoming a
+  // silent dependency.
+  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(
+    product.type !== 'KIT' && product.variants && product.variants.length > 0
+      ? product.variants[0]
+      : null
+  );
+  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
+  const [quantity, setQuantity] = useState(1);
+  const [addingToCart, setAddingToCart] = useState(false);
+  const [addedMessage, setAddedMessage] = useState(false);
+  const customizationFields = product.customizationFields ?? [];
+  const [customizationValues, setCustomizationValues] = useState<CustomizationValues>(() => {
+    const initial: CustomizationValues = {};
+    for (const field of customizationFields) {
+      if (field.defaultValue != null) initial[field.key] = field.defaultValue;
+    }
+    return initial;
+  });
+  const [customizationErrors, setCustomizationErrors] = useState<Record<string, string>>({});
+
+  // Modifier groups (PRD §8.4) — only present on restaurant / build-your-own products.
+  const modifierGroups: ModifierGroup[] = useMemo(
+    () => (product as Product & { modifierGroups?: ModifierGroup[] }).modifierGroups ?? [],
+    [product]
+  );
+  const [modifierSelections, setModifierSelections] = useState<Record<string, string[]>>(() =>
+    buildInitialSelections(modifierGroups)
+  );
+  const [modifierError, setModifierError] = useState<string | null>(null);
+
+  function setModifierSelection(groupId: string, next: string[]) {
+    setModifierSelections((prev) => ({ ...prev, [groupId]: next }));
+  }
+
+  // Images list - switch main image when variant changes
+  const images: ProductImage[] = useMemo(() => {
+    return product?.images || [];
+  }, [product]);
+
+  // When variant changes, update selected image to variant image if available
+  useEffect(() => {
+    if (!selectedVariant?.image || !product) return;
+
+    const variantImgUrl =
+      typeof selectedVariant.image === 'string' ? selectedVariant.image : selectedVariant.image.url;
+
+    // Find if variant image exists in product images
+    const idx = images.findIndex((img) => img.url === variantImgUrl);
+    if (idx >= 0) {
+      setSelectedImageIndex(idx);
+    } else {
+      // Variant image not in product images - select index 0 as fallback
+      setSelectedImageIndex(-1);
+    }
+  }, [selectedVariant, images, product]);
+
+  // Determine which image to show
+  const mainImageUrl = useMemo(() => {
+    if (selectedImageIndex === -1 && selectedVariant?.image) {
+      const img = selectedVariant.image;
+      return typeof img === 'string' ? img : img.url;
+    }
+    return images[selectedImageIndex]?.url || null;
+  }, [selectedImageIndex, selectedVariant, images]);
+
+  // Price info - use variant price if selected, else product price
+  const priceInfo = useMemo(() => {
+    if (selectedVariant?.price) {
+      const variantBase = parseFloat(selectedVariant.price);
+      const variantSale = selectedVariant.salePrice ? parseFloat(selectedVariant.salePrice) : null;
+      const variantEffective =
+        variantSale != null && variantSale < variantBase ? variantSale : variantBase;
+
+      // Overlay any product-level discount rule onto the variant price using the rule's ratio
+      if (product.discount) {
+        const ruleOriginal = parseFloat(product.discount.originalPrice) || 0;
+        const ruleDiscounted = parseFloat(product.discount.discountedPrice) || 0;
+        const ratio = ruleOriginal > 0 ? ruleDiscounted / ruleOriginal : 1;
+        const discounted = variantEffective * ratio;
+        const amount = Math.max(0, variantEffective - discounted);
+        return {
+          price: discounted,
+          originalPrice: variantEffective,
+          isOnSale: discounted < variantEffective,
+          discountAmount: amount,
+          discountPercent: variantEffective > 0 ? Math.round((amount / variantEffective) * 100) : 0,
+        };
+      }
+
+      return {
+        price: variantEffective,
+        originalPrice: variantBase,
+        isOnSale: variantEffective < variantBase,
+        discountPercent:
+          variantEffective < variantBase && variantBase > 0
+            ? Math.round(((variantBase - variantEffective) / variantBase) * 100)
+            : 0,
+      };
+    }
+    return getProductPriceInfo(product);
+  }, [product, selectedVariant]);
+
+  // Region display pricing, variant-aware. The selected variant carries its own
+  // FX fields; fall back to the product's, then to the store-currency figures
+  // above. Same helper the product card uses, so a card and the page it opens
+  // can never quote different currencies for the same item.
+  const displayPrice = useMemo<DisplayPrice>(() => {
+    const fallback = {
+      price: priceInfo.originalPrice,
+      salePrice: priceInfo.isOnSale ? priceInfo.price : null,
+    };
+    const source = selectedVariant?.displayPrice != null ? selectedVariant : product;
+    return resolveDisplayPrice(source, fallback, currency);
+  }, [product, selectedVariant, priceInfo, currency]);
+
+  // Inventory: the selected variant's when there is one, else the product's.
+  //
+  // ⛔ Goes through `resolveStockInfo` because a KIT has NO `inventory` block —
+  // its stock is `product.kitAvailable`. Reading `inventory` directly gave one
+  // kit two contradictory answers on the same page: `<StockBadge>` printed a red
+  // "Out of stock" (nullish inventory) while the add-to-cart button stayed
+  // ENABLED (`undefined?.canPurchase !== false` is `true`). Both now read the
+  // same resolved value, so the badge and the button can never disagree.
+  const inventory = resolveStockInfo(product, selectedVariant?.inventory);
+  const canPurchase = inventory?.canPurchase !== false;
+
+  // Description
+  const description = useMemo(() => {
+    return product ? getDescriptionContent(product) : null;
+  }, [product]);
+
+  // `view_item` — the event Meta and Google build remarketing audiences from.
+  // The ref keeps it to once per product rather than once per render: the
+  // shopper is looking at one product, and re-firing on every swatch click or
+  // quantity change would inflate the audience with phantom views.
+  const viewedProductIdRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!product || viewedProductIdRef.current === product.id) return;
+    viewedProductIdRef.current = product.id;
+    trackProductView(product, selectedVariant, priceInfo.price, currency);
+  }, [product, selectedVariant, priceInfo.price, currency]);
+
+  async function handleAddToCart() {
+    if (!product || addingToCart) return;
+
+    if (customizationFields.length > 0) {
+      const errs = validateCustomization(customizationFields, customizationValues);
+      if (Object.keys(errs).length > 0) {
+        setCustomizationErrors(errs);
+        return;
+      }
+    }
+    setCustomizationErrors({});
+
+    // Client-side modifier validation mirrors the server's checks. The server
+    // is authoritative — `MODIFIER_VALIDATION_FAILED` envelope on add-to-cart
+    // failure is the source of truth — but pre-flighting catches the obvious
+    // issues without a round-trip.
+    if (modifierGroups.length > 0) {
+      const error = validateSelections(modifierGroups, modifierSelections);
+      if (error) {
+        setModifierError(error);
+        return;
+      }
+    }
+    setModifierError(null);
+
+    const selections =
+      modifierGroups.length > 0
+        ? toModifierSelections(modifierGroups, modifierSelections)
+        : undefined;
+
+    try {
+      setAddingToCart(true);
+      const { getClient } = await import('@/core/lib/brainerce');
+      const client = getClient();
+      await client.smartAddToCart({
+        productId: product.id,
+        variantId: selectedVariant?.id,
+        quantity,
+        metadata:
+          customizationFields.length > 0 && Object.keys(customizationValues).length > 0
+            ? customizationValues
+            : undefined,
+        ...(selections && selections.length > 0 ? { selections } : {}),
+      });
+      await refreshCart();
+      // Report only after the server accepted the line — an add that failed
+      // validation is not an add-to-cart, and feeding the ad platforms events
+      // that never became cart lines poisons their conversion modelling.
+      trackAddToCart(product, selectedVariant, quantity, priceInfo.price, currency);
+      setAddedMessage(true);
+      setTimeout(() => setAddedMessage(false), 2000);
+    } catch (err) {
+      // Surface the structured `MODIFIER_VALIDATION_FAILED` envelope when present.
+      const e = err as { details?: { code?: string; errors?: Array<{ message: string }> } };
+      const validationErrors = e?.details?.errors;
+      if (e?.details?.code === 'MODIFIER_VALIDATION_FAILED' && validationErrors?.length) {
+        setModifierError(validationErrors.map((v) => v.message).join('; '));
+      } else {
+        console.error('Failed to add to cart:', err);
+      }
+    } finally {
+      setAddingToCart(false);
+    }
+  }
+
+  return {
+    product,
+    recommendations,
+    images,
+    selectedImageIndex,
+    setSelectedImageIndex,
+    mainImageUrl,
+    selectedVariant,
+    setSelectedVariant,
+    priceInfo,
+    displayPrice,
+    inventory,
+    canPurchase,
+    description,
+    quantity,
+    setQuantity,
+    addingToCart,
+    addedMessage,
+    handleAddToCart,
+    customizationFields,
+    customizationValues,
+    setCustomizationValues,
+    customizationErrors,
+    modifierGroups,
+    modifierSelections,
+    setModifierSelection,
+    modifierError,
+  };
+}