@wix/agent-skills 1.19.0 → 1.19.2

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -9,7 +9,7 @@ or configuration changes are needed to build the UI. Never mock products or hand
 `/checkout` URL; the shipped cart uses the eCom redirect session.
 
 ## Prerequisites
-- The site's **Wix Stores** catalog is the read/cart target. It's installed and seeded separately, in parallel with this build — so it may be empty at build time; render the empty state until products land.
+- The site's **Wix Stores** catalog is the read/cart target. It may be empty while the client is being built — render the empty state cleanly. Flows that seed do so after the client is built; verify the storefront once the catalog is populated, not against the empty state.
 
 ## Already installed in `src/`
 Successful deployment verified these files are in place; use this map without needing to read their source (`@/` → `src/`).
@@ -103,18 +103,22 @@ export default function ProductCard({ product }) {
   const {
     isSoldOut, isPreorder, isPartiallyOutOfStock, // booleans
     leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
-    promoBadge,       // { type: 'discount'|'ribbon', label } | null
-    priceDisplay,     // formatted price or min–max range; may be undefined if absent
-    compareAtDisplay, // formatted compare-at price | null
+    ribbons,          // every merchant ribbon label, primary first — render ALL of them, one shared style
+    promoBadge,       // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
+    priceDisplay,     // the price the buyer pays (discounted when an automatic discount applies), or a min–max range
+    compareAtDisplay, // struck "was" price | null — never beside a range (the PDP shows the real comparison)
     colors,           // hex colour strings
     optionLabel,      // e.g. "3 sizes · 2 materials", or ""
     isQuickAddable,   // no product options and not sold out; does NOT check modifiers
+    directAddVariantId, // the variant a quick-add sends; null when not quick-addable
     image, hoverImage,// normalised primary / second gallery URL | null
   } = useProductCard(product);
   // Render your card.
 }
 ```
-For quick-add, call `addToCart(product.id)` only when `isQuickAddable` and no mandatory
+A ribbon is a label, never proof of a price: don't render a "Sale" badge from `compareAtDisplay`,
+and don't compute a percent-off — the hook deliberately doesn't. For quick-add, call
+`addToCart(product.id, directAddVariantId)` only when `isQuickAddable` and no mandatory
 modifier needs input (`product.modifiers` entries have a `mandatory` boolean). Otherwise link to `/product/${product.slug}` for selection, including
 pre-orders. Listing results have no full variants; the PDP hook loads and resolves them.
 Use cart-context `loading` to disable repeated adds. Failures open the shipped drawer with
@@ -198,15 +202,19 @@ export default function ProductDetail() {
   // d contains:
   // product: Wix product | null; .name, .slug, .plainDescription (HTML)
   // notFound: boolean; error: string | null (load error); retry: () => void
-  // price, compareAtPrice: formatted strings ("" if absent), follow the selected variant
+  // price: formatted — the product's min–max range until every option is picked, then the selected
+  //   variant's price (an automatic discount beats the regular price); compareAtPrice: the struck
+  //   "was" price, "" when none. discountNames: automatic-discount names, product level.
   // options, modifiers: arrays consumed by useVariantOptions above
-  // selectedOptions: { [optionId]: choiceId }; selectOption(optionId, choiceId)
+  // selectedOptions: { [optionId]: choiceId } — starts EMPTY (no pre-picked choice); selectOption(optionId, choiceId)
   // modifierValues: { [key]: value }; setModifier(key, value)
   // variant: resolved variant | null; null if required choices are missing or no match exists
   // focusMediaUrl: selected choice image, then variant image, or null
-  // quantity, setQuantity(n): number (may be "" mid-edit)
-  // inStock, canAdd, adding: booleans
-  // submit: async () => adds product + resolved variant + quantity + modifiers
+  // quantity, setQuantity(n): number (may be "" mid-edit); resets to 1 when an option changes
+  // inStock, isPreorder, canAdd, adding: booleans — a pre-order variant IS addable
+  // blockedReason: string | null — why the buy button is disabled ("Choose Size", "Out of stock");
+  //   render it next to the action as neutral guidance, not an error, until the buyer tries to buy
+  // submit: async () => adds product + resolved variant + quantity + modifiers (+ preorder)
   // resolves undefined on success, null on failure (not a cart object or a boolean)
   // Replace these placeholders with your error, not-found, and loading UI.
   if (d.error) return null; // show d.error and offer d.retry()
@@ -220,24 +228,28 @@ export default function ProductDetail() {
 ```
 - Render `product.plainDescription` as HTML; strike `compareAtPrice` only when present and different from `price`.
 - Make the gallery follow `focusMediaUrl` when the selected option changes.
-- Render the option/modifier controls below; show a selection hint when `options.length && !variant`.
-- Keep quantity at least 1. Disable adding when `!canAdd || adding`; call `submit()` only with a loaded product and `canAdd`. `submit()` coerces quantity to at least 1 but does not itself enforce `canAdd`.
-- `canAdd` checks variant resolution, variant stock, and mandatory modifier values. `inStock` defaults to true without a resolved variant; use `canAdd` for the full gate.
+- Render the option/modifier controls below; mark choices whose `inStock` is false; show `d.blockedReason` beside the button while it's disabled.
+- Label the action by state: `isPreorder` → "Pre-order"; otherwise "Add to cart". Keep quantity at least 1. Disable adding when `!canAdd || adding`; call `submit()` only with a loaded product and `canAdd`. `submit()` coerces quantity to at least 1 but does not itself enforce `canAdd`.
+- `canAdd` checks variant resolution, availability (in stock or pre-orderable), and mandatory modifier values. `inStock` defaults to true without a resolved variant; use `canAdd` for the full gate.
+- Render the PDP gallery from `images` — every image reachable (thumbnails, arrows, or a swipeable rail), not just the first; a single-image product gets no empty strip.
 - `submit()` resets `adding` after completion and preserves the cart result: `undefined` on success, `null` on failure. Add failures live in `useCart().error`, not the PDP load `error`; the shipped drawer opens to display them.
 
-For an optional **Buy Now** button, check the add result before checkout:
+For an optional **add and check out** shortcut, check the add result before checkout:
 ```jsx
 // Inside ProductDetail, with the other hooks above any conditional returns:
 const { checkout, loading: cartLoading } = useCart(); // named import from @/context/CartContext
-async function buyNow() {
+async function addAndCheckout() {
   if (!d.product || !d.canAdd || d.adding || cartLoading) return;
   const result = await d.submit();
   if (result === null) return; // add failed; preserve its error and do not check out the old cart
   await checkout();
 }
-// <button disabled={!d.canAdd || d.adding || cartLoading} onClick={buyNow}>Buy now</button>
+// <button disabled={!d.canAdd || d.adding || cartLoading} onClick={addAndCheckout}>Add and check out</button>
 ```
-For direct `addToCart(...)` calls, use the same `result === null` check before checkout.
+This adds to the shopper's **current cart** and checks that cart out — so label it that way. A true
+**Buy Now** (skip the cart, buy just this item) needs a standalone cart handed to the redirect session;
+it is not shipped, and routing "Buy now" through the current cart is wrong (it would carry whatever the
+cart already holds). For direct `addToCart(...)` calls, use the same `result === null` check before checkout.
 A resolved promise alone does not mean success; a truthiness check also rejects successful `undefined`.
 
 ### Variant and modifier controls
@@ -277,14 +289,17 @@ within `CartProvider` (the PDP hook calls it for you).
 
 ```js
 const { addToCart, isOpen, setIsOpen, loading, error, clearError } = useCart();
-// addToCart(productId, variantId?, qty = 1, { modifierChoices?, customTextFields? }?)
+// addToCart(productId, variantId?, qty = 1, { modifierChoices?, customTextFields?, subscriptionOptionId?, preorder? }?)
 // isOpen: boolean; setIsOpen(true): open the drawer; setIsOpen(false): close it
 // loading: mutation-in-progress boolean; disable repeated adds while true
 // error: string | null; clearError(): clears it
 ```
-`addToCart` uses `product.id` and the resolved `variant.id` when needed. Extras are string maps:
+`addToCart` uses `product.id` and the resolved `variant.id` when needed. Extras: string maps
 `modifierChoices: { [modifier.key]: choiceKey }` and
-`customTextFields: { [modifier.freeTextSettings.key]: userInput }`; include mandatory values.
+`customTextFields: { [modifier.freeTextSettings.key]: userInput }` (include mandatory values);
+`preorder: true` for a pre-order variant (the PDP hook sets it); `subscriptionOptionId` for a chosen
+recurring plan (omit for one-time). The shipped PDP hook doesn't render subscriptions — add that
+only when the catalog has `subscriptionPricesInfo`, requiring an explicit plan choice.
 
 The context's add/remove/update/checkout methods return promises resolving to `undefined` on
 success or `null` on failure, storing the failure in `error`. They clear the previous error and
@@ -298,8 +313,10 @@ Only use these additional contracts if you choose to render your own cart surfac
 from the same `useCart()` context; mutation results and error handling are described above.
 
 ```js
-const { cart, itemCount, removeItem, updateQuantity, checkout, refreshCart } = useCart();
+const { cart, summary, itemCount, removeItem, updateQuantity, checkout, refreshCart } = useCart();
 // cart: server cart | null; itemCount: sum of confirmed line quantities
+// summary: the estimate's { priceSummary: { subtotal, discount, total } } | null — refreshed with the cart;
+//   subtotal is after discounts, discount is the CART-level discount only; both ConvertedMoney
 // removeItem(lineItemId); updateQuantity(lineItemId, qty)
 // checkout(); refreshCart()
 ```
@@ -307,7 +324,8 @@ For custom cart presentation, `cart?.lineItems ?? []` is the list. Each line has
 `name.original`, and optional `attributes.image.url`. Option/modifier labels are in
 `attributes.descriptionLines`: `[{ name: { original }, plainText?: { original },
 colorInfo?: { original, code } }]`; use `plainText.original` or `colorInfo.original` for the value.
-Update/remove use the line's `id`, not a catalog product id.
+Update/remove use the line's `id`, not a catalog product id. Show each line's `attributes.descriptionLines`
+(the chosen options and text) — a shopper verifies the configuration in the cart, not the checkout.
 
 Normalize custom cart images with `storeImage(line.attributes?.image?.url)` (see **Images**).
 
@@ -320,10 +338,10 @@ Cart money is `{ amount, convertedAmount }`, with no formatted string. `amount`
 currency; `convertedAmount` is in display currency. Format
 `money.convertedAmount ?? money.amount` with `Intl.NumberFormat` and
 `cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode` (the shipped drawer falls
-back to `USD`). Use server `cart.subtotal` and line `pricing.totalPrice`; never sum lines yourself.
-The cart has no `subtotalAfterDiscounts`, `discount`, or `appliedDiscounts`; discounted summary
-totals require a currentCartV2 estimate/calculate `summary.priceSummary`, which these helpers do
-not fetch. Tax and shipping resolve at checkout.
+back to `USD`). Use `summary.priceSummary.subtotal` (after discounts) with `cart.subtotal` as the
+fallback while `summary` is null, a Discount row only when `priceSummary.discount` is above zero, and
+line `pricing.totalPrice`; never sum lines yourself. Shipping and tax resolve at checkout — say
+"calculated at checkout", never a hardcoded charge, threshold, or a made-up zero.
 
 Line `quantityInfo.confirmedQuantity` is the current quantity; `availableQuantity` caps increases
 when finite. `status` can be `IN_STOCK`, `PARTIALLY_IN_STOCK`, `OUT_OF_STOCK`, or
@@ -416,6 +434,28 @@ function Layout() {
 }
 ```
 
+## What a complete storefront shows
+
+The wiring above is necessary, not sufficient. These are defaults for when the brief doesn't say
+otherwise — whatever the user asked for in their prompt wins over any line here. Look at the
+catalog before designing — categories, assortment size, media, options, sales — and design for this
+store, not for a stereotype of its category. Then:
+
+- **Home:** what the store sells and one shopping action in the first screen; real products from
+  the catalog under truthful headings; not a repeat of the shop page.
+- **Shop:** a real product card — image, name, price, link — in the first screen; sort and the
+  filters the catalog supports; loading, empty, no-results, and error states that look different.
+- **Product page:** image, name, price, the first choice, and the buy button with `blockedReason`
+  in the first screen; every ribbon; every image reachable in the gallery.
+- **Cart:** the shipped drawer — it opens after every add, and checkout is a button in it.
+- **Overlays you build** (quick-add, mobile nav, filters): mount at the document root, lock
+  background scroll, close on Escape, return focus on close — as the shipped `CartDrawer` does.
+- **Copy:** nothing the merchant didn't supply — no invented reviews, scarcity, or delivery
+  promises; no Wix IDs or technical words in visible text.
+
+Pre-order ships (`isPreorder`). Subscriptions, product groups, promotions, and notify-me are built
+only when the catalog has them — never fabricated; consult the documentation skill for their endpoints.
+
 ## Missing capabilities
 For anything these interfaces do not cover, consult the official Wix API documentation using
 the documentation skill available in your environment.
@@ -425,4 +465,6 @@ shipped file; catalog and cart helpers link their API references inline.
 ## Hard rules
 - Header/footer live in a `Layout` around `<Outlet/>` (see **Routes and provider**) — keep shared chrome out of individual pages.
 - Checkout goes through the shipped cart (redirect-session) — never a hand-built `/checkout` URL.
-- Render live Wix data or your empty state — never mock products.
+- Render live Wix data or your empty state — never mock products, reviews, ratings, or counts.
+- Prices and ribbons come from the hooks as-is: no computed percent-off, no "Sale" badge inferred from a compare-at price, no struck price beside a range.
+- Cart totals come from `summary`/`cart` — never summed or hardcoded in the client; shipping and tax say "calculated at checkout".

package/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx

@@ -5,15 +5,14 @@
 // • prices come from the SERVER cart. In Cart V2 each line total is `pricing.totalPrice`, a
 //   ConvertedMoney { amount, convertedAmount } with NO formatted string — format it yourself with the
 //   cart's currency (see formatCartMoney). Never compute a total in the client: tax, shipping and
-//   promotions are resolved server-side, so the cart's `subtotal` is the only figure safe to show
-//   pre-checkout. The V2 cart has no `subtotalAfterDiscounts`/`discount`/`appliedDiscounts` — the
-//   discounted total comes from a currentCartV2 estimate/calculate `summary.priceSummary`, not the
-//   cart; absent that call, show the raw `subtotal`.
+//   promotions are resolved server-side. The V2 cart has no `subtotalAfterDiscounts`/`discount` —
+//   the after-discount subtotal and the cart-level discount come from the estimate the context keeps
+//   in `summary.priceSummary`; the raw cart `subtotal` is the fallback while it's unknown.
 // • `quantityInfo.availableQuantity` caps the stepper, so exceeding stock is refused here rather than
 //   at checkout.
 // • `status` is flagged per line here because checkout() refuses the whole cart when any item isn't
 //   IN_STOCK — showing it on the row is what makes that refusal understandable.
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { useCart } from "@/context/CartContext";
 import { storeImage } from "@/lib/storeImage";
 
@@ -26,28 +25,41 @@ function formatCartMoney(money, cart) {
 }
 
 export default function CartDrawer() {
-  const { cart, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading, error, clearError } = useCart();
+  const { cart, summary, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading, error, clearError } = useCart();
   const lineItems = cart?.lineItems ?? [];
-  // The V2 cart carries only a raw `subtotal` (ConvertedMoney); discounted totals live on an
-  // estimate/calculate `summary.priceSummary`, which this cart helper doesn't fetch — so show `subtotal`.
-  const subtotal = formatCartMoney(cart?.subtotal, cart);
+  // Totals come from the estimate the context keeps next to the cart (after-discount subtotal, the
+  // cart-level discount). While it's unknown, or if it failed, fall back to the cart's raw subtotal.
+  // Delivery and tax are NOT in here — they resolve at checkout, and the footer says so.
+  const subtotal = formatCartMoney(summary?.priceSummary?.subtotal ?? cart?.subtotal, cart);
+  const discountAmount = Number(summary?.priceSummary?.discount?.convertedAmount ?? summary?.priceSummary?.discount?.amount ?? 0);
+  const discount = discountAmount > 0 ? formatCartMoney(summary.priceSummary.discount, cart) : "";
   const unavailable = lineItems.filter((li) => li.status && li.status !== "IN_STOCK");
 
-  // Escape closes the drawer while it's open — expected of anything modal, and the only way out for
-  // keyboard users (the backdrop click is pointer-only).
+  // The overlay contract, verified in the browser rather than assumed from CSS: Escape closes (the
+  // backdrop click is pointer-only), the page behind stops scrolling, focus moves into the panel on
+  // open and returns to whatever opened it on close.
+  const panelRef = useRef(null);
   useEffect(() => {
     if (!isOpen) return;
+    const opener = document.activeElement;
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    panelRef.current?.focus();
     const onKey = (e) => e.key === "Escape" && setIsOpen(false);
     document.addEventListener("keydown", onKey);
-    return () => document.removeEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = previousOverflow;
+      if (opener instanceof HTMLElement) opener.focus();
+    };
   }, [isOpen, setIsOpen]);
 
   if (!isOpen) return null;
 
   return (
     <div onClick={() => setIsOpen(false)} className="fixed inset-0 z-50 bg-black/40 flex justify-end">
-      <aside onClick={(e) => e.stopPropagation()} role="dialog" aria-modal="true" aria-label="Your cart"
-        className="w-[min(420px,100%)] h-full flex flex-col bg-background text-foreground border-l border-border font-body">
+      <aside ref={panelRef} tabIndex={-1} onClick={(e) => e.stopPropagation()} role="dialog" aria-modal="true" aria-label="Your cart"
+        className="w-[min(420px,100%)] h-full flex flex-col bg-background text-foreground border-l border-border font-body outline-none">
         <header className="flex justify-between items-center p-4 border-b border-border">
           <strong className="font-display">Your cart{lineItems.length ? ` (${lineItems.length})` : ""}</strong>
           <button onClick={() => setIsOpen(false)} aria-label="Close cart"
@@ -123,6 +135,12 @@ export default function CartDrawer() {
 
         {lineItems.length > 0 && (
           <footer className="p-4 border-t border-border flex flex-col gap-3">
+            {discount && (
+              <div className="flex justify-between items-baseline text-sm">
+                <span className="text-muted-foreground">Discount</span>
+                <span>−{discount}</span>
+              </div>
+            )}
             {subtotal && (
               <div className="flex justify-between items-baseline">
                 <span className="text-muted-foreground">Subtotal</span>

package/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx

@@ -3,6 +3,7 @@
 import { createContext, useContext, useState, useEffect, useCallback } from "react";
 import {
   getCurrentCart,
+  estimateCurrentCart,
   addToCart as apiAdd,
   removeFromCart as apiRemove,
   updateCartItemQuantity as apiQty,
@@ -12,7 +13,11 @@ import {
 const CartContext = createContext(null);
 
 export function CartProvider({ children }) {
-  const [cart, setCart] = useState(null);
+  const [cart, setCartState] = useState(null);
+  // The calculated summary (after-discount subtotal, cart-level discount) — from the estimate, never
+  // summed in the client. Refreshed with every cart change; null while unknown or when the estimate
+  // fails, in which case surfaces fall back to cart.subtotal.
+  const [summary, setSummary] = useState(null);
   const [isOpen, setIsOpen] = useState(false);
   const [loading, setLoading] = useState(false);
   // The cart helpers throw on refusal with a buyer-readable reason — an empty cart, or line items
@@ -20,7 +25,13 @@ export function CartProvider({ children }) {
   // this the rejection is unhandled and the shopper sees the spinner stop with nothing said.
   const [error, setError] = useState(null);
 
-  const refreshCart = useCallback(async () => setCart(await getCurrentCart()), []);
+  // Every cart write goes through here so the summary always describes the cart on screen.
+  const setCart = useCallback((next) => {
+    setCartState(next);
+    if (!next?.lineItems?.length) { setSummary(null); return; }
+    estimateCurrentCart().then((s) => setSummary(s)).catch(() => setSummary(null));
+  }, []);
+  const refreshCart = useCallback(async () => setCart(await getCurrentCart()), [setCart]);
   useEffect(() => {
     refreshCart();
     const onVisible = () => document.visibilityState === "visible" && refreshCart();
@@ -59,7 +70,7 @@ export function CartProvider({ children }) {
     run(async () => { window.location.href = await apiCheckout(); }, { reread: true });
 
   return (
-    <CartContext.Provider value={{ cart, itemCount, isOpen, setIsOpen, loading, error, clearError: () => setError(null), addToCart, removeItem, updateQuantity, checkout, refreshCart }}>
+    <CartContext.Provider value={{ cart, summary, itemCount, isOpen, setIsOpen, loading, error, clearError: () => setError(null), addToCart, removeItem, updateQuantity, checkout, refreshCart }}>
       {children}
     </CartContext.Provider>
   );

package/skills/wix-vibe-headless/references/storefront/app/hooks/useProductCard.js

@@ -1,22 +1,16 @@
 // Headless data layer for a product grid tile.
 // Normalises raw Wix product fields into render-agnostic structures so you can build
 // whatever card UI you want (image layout, badge style, price display, quick-add trigger)
-// without touching the badge-priority logic, price-range maths, or colour-dot extraction.
+// without touching the badge logic, price rules, or colour-dot extraction.
 //
 // Usage:
-//   const { isSoldOut, leftBadges, promoBadge, priceDisplay, compareAtDisplay,
-//           colors, optionLabel, isQuickAddable, image, hoverImage } = useProductCard(product);
-//   // then render however you want, call addToCart(product.id) from useCart() for quick-add.
+//   const { isSoldOut, leftBadges, ribbons, promoBadge, priceDisplay, compareAtDisplay,
+//           colors, optionLabel, isQuickAddable, directAddVariantId, image, hoverImage } = useProductCard(product);
+//   // then render however you want; quick-add: addToCart(product.id, directAddVariantId) from useCart().
 
 import { useMemo } from "react";
 import { productImage, productGallery } from "@/lib/storeImage";
-
-function discountPercent(product) {
-  const now = Number(product?.actualPriceRange?.minValue?.amount);
-  const was = Number(product?.compareAtPriceRange?.minValue?.amount);
-  if (!now || !was || was <= now) return null;
-  return Math.round(((was - now) / was) * 100);
-}
+import { sellingPrice } from "@/rest/wix-store-catalog";
 
 export function useProductCard(product) {
   return useMemo(() => {
@@ -32,23 +26,31 @@ export function useProductCard(product) {
     else if (isSoldOut)            leftBadges.push({ type: "sold-out",      label: "Sold out"      });
     if (isPartiallyOutOfStock)     leftBadges.push({ type: "limited-stock", label: "Limited stock" });
 
-    // Right-side promo badge: discount % beats a merchant ribbon (a "Sale" ribbon is redundant
-    // when the % is already showing). Only one at a time.
-    const discount = discountPercent(product);
-    const ribbon   = product?.ribbon?.name;
-    const promoBadge = discount
-      ? { type: "discount", label: `-${discount}%` }
-      : ribbon
-      ? { type: "ribbon",   label: ribbon }
-      : null;
+    // Merchant ribbons — the primary one plus every additional one. Render ALL of them, in one shared
+    // style (a "Sale" accent is fine, applied by label). Never compute a "-20%" badge from the price
+    // range: a range's minimum says nothing about the variant the buyer picks, and a ribbon is a
+    // label, not a price claim.
+    const ribbons = [product?.ribbon?.name, ...(product?.additionalRibbons ?? []).map((r) => r?.name)]
+      .filter((name, i, all) => name && all.indexOf(name) === i);
+    const promoBadge = ribbons[0] ? { type: "ribbon", label: ribbons[0] } : null;
 
-    // Price: show a min–max range when variants span different prices so the PDP doesn't
-    // appear to raise the price once a variant is selected.
-    const priceMin = product?.actualPriceRange?.minValue?.formattedAmount;
-    const priceMax = product?.actualPriceRange?.maxValue?.formattedAmount;
-    const compareAt = product?.compareAtPriceRange?.minValue?.formattedAmount;
-    const priceDisplay      = priceMax && priceMax !== priceMin ? `${priceMin} – ${priceMax}` : priceMin;
-    const compareAtDisplay  = compareAt && compareAt !== priceMin ? compareAt : null;
+    // Price. A single-price product shows the price the buyer pays — the lowest-priced variant's
+    // discounted price when an automatic discount applies (priceAfterDiscount), else its regular
+    // price — with the struck "was" price beside it. Variants priced differently show a min–max
+    // range with NO struck price: one lone "was" against a range implies a saving that may not
+    // apply to the variant the buyer picks; the PDP shows the real comparison once a variant is chosen.
+    const min = product?.actualPriceRange?.minValue;
+    const max = product?.actualPriceRange?.maxValue;
+    const isRange = !!(min?.amount && max?.amount && min.amount !== max.amount);
+    const minVariant = product?.variantSummary?.minPriceVariant ?? null;
+    const { current, original } = sellingPrice(minVariant?.price);
+    const priceDisplay = isRange
+      ? `${min?.formattedAmount ?? ""} – ${max?.formattedAmount ?? ""}`
+      : current?.formattedAmount ?? min?.formattedAmount;
+    const compareAtDisplay =
+      !isRange && original?.formattedAmount && Number(original.amount) > Number(current?.amount ?? min?.amount)
+        ? original.formattedAmount
+        : null;
 
     // Options preview for the tile summary row.
     // Colour options → real hex dots (more informative than "3 colours").
@@ -68,6 +70,8 @@ export function useProductCard(product) {
     // Quick-add is only safe for single-variant products (no option choices to resolve).
     // Sold-out with pre-order still shows a CTA, but it links to the PDP, not quick-add.
     const isQuickAddable = !hasOptions && !isSoldOut;
+    // The variant a direct add sends (a product with no options still has one variant).
+    const directAddVariantId = isQuickAddable ? minVariant?.id ?? null : null;
 
     // Images: normalised through lib/storeImage so URLs are consistent across the tile,
     // the PDP gallery, and the cart. Hover image is the second gallery shot (if one exists).
@@ -78,15 +82,17 @@ export function useProductCard(product) {
       isSoldOut,
       isPreorder,
       isPartiallyOutOfStock,
-      leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
-      promoBadge,       // { type: 'discount'|'ribbon', label } | null
-      priceDisplay,     // formatted price (range or single value)
-      compareAtDisplay, // formatted compare-at price | null
-      colors,           // hex strings — render as dots; the tile shows up to however many you want
-      optionLabel,      // "3 sizes · 2 materials" or empty string
+      leftBadges,          // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
+      ribbons,             // every merchant ribbon label, primary first — render all of them
+      promoBadge,          // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
+      priceDisplay,        // formatted price the buyer pays, or a min–max range
+      compareAtDisplay,    // formatted struck "was" price | null (never beside a range)
+      colors,              // hex strings — render as dots; the tile shows up to however many you want
+      optionLabel,         // "3 sizes · 2 materials" or empty string
       isQuickAddable,
-      image,            // primary image URL | null
-      hoverImage,       // second image URL for hover effect | null
+      directAddVariantId,  // pass as variantId to addToCart on quick-add
+      image,               // primary image URL | null
+      hoverImage,          // second image URL for hover effect | null
     };
   }, [product]);
 }

package/skills/wix-vibe-headless/references/storefront/app/hooks/useProductDetail.js

@@ -1,13 +1,15 @@
-// useProductDetail — all PDP logic, no markup: load product by slug, pre-select first in-stock
-// choice per option, resolve the buyer's selections to a Wix variant, gate add-to-cart on stock +
-// mandatory modifiers, and build the addToCart payload. The data paths here (variant resolution,
-// modifier keys, stock gating) are the bug-prone part — keep them verbatim; the PDP page only
-// renders what this returns.
+// useProductDetail — all PDP logic, no markup: load product by slug, resolve the buyer's selections
+// to a Wix variant, gate add-to-cart on availability + mandatory modifiers, and build the addToCart
+// payload. The data paths here (variant resolution, price precedence, modifier keys, stock gating)
+// are the bug-prone part — keep them verbatim; the PDP page only renders what this returns.
 import { useState, useEffect, useMemo } from "react";
-import { getProductBySlug } from "@/rest/wix-store-catalog";
+import { getProductBySlug, sellingPrice } from "@/rest/wix-store-catalog";
 import { choiceImage, variantImage } from "@/lib/storeImage";
 import { useCart } from "@/context/CartContext";
 
+// A variant is identified by the SET of its choice ids — sorted, so option order can't matter.
+const choiceKey = (choiceIds) => [...choiceIds].sort().join("_");
+
 export function useProductDetail(slug) {
   const { addToCart } = useCart();
   const [product, setProduct] = useState(null);
@@ -16,6 +18,8 @@ export function useProductDetail(slug) {
   // link, the other is worth retrying. Without the split, a network blip reads as "product deleted".
   const [error, setError] = useState(null);
   const [adding, setAdding] = useState(false);
+  // Selections start EMPTY. Pre-picking the first choice lets a buyer who never noticed the default
+  // buy the wrong colour; the PDP shows a neutral "choose a size" until every option is picked.
   const [selectedOptions, setSelectedOptions] = useState({});
   const [modifierValues, setModifierValues] = useState({});
   const [quantity, setQuantity] = useState(1);
@@ -26,17 +30,13 @@ export function useProductDetail(slug) {
     setProduct(null);
     setNotFound(false);
     setError(null);
+    setSelectedOptions({});
+    setQuantity(1);
     getProductBySlug(slug)
       .then((p) => {
         if (cancelled) return;
         if (!p) return setNotFound(true);
         setProduct(p);
-        const initial = {};
-        (p.options || []).forEach((o) => {
-          const first = o.choicesSettings?.choices?.find((c) => c.inStock !== false);
-          if (first) initial[o.id] = first.choiceId;
-        });
-        setSelectedOptions(initial);
       })
       .catch((e) => { if (!cancelled) setError(e?.message || "Couldn't load this product."); });
     return () => { cancelled = true; };
@@ -44,29 +44,70 @@ export function useProductDetail(slug) {
 
   const options = product?.options || [];
   const modifiers = product?.modifiers || [];
-  const variants = product?.variantsInfo?.variants || [];
 
+  // Visible variants keyed by their sorted choice ids. Two variants with the same choices is a
+  // catalog defect — report it instead of silently letting one overwrite the other.
+  const { variantByKey, duplicateKey } = useMemo(() => {
+    const map = new Map();
+    let dup = null;
+    for (const v of product?.variantsInfo?.variants || []) {
+      if (v.visible === false) continue;
+      const k = choiceKey((v.choices || []).map((c) => c.optionChoiceIds?.choiceId));
+      if (map.has(k) && !dup) dup = k;
+      map.set(k, v);
+    }
+    return { variantByKey: map, duplicateKey: dup };
+  }, [product]);
+
+  const selectionComplete = options.length > 0 && options.every((o) => selectedOptions[o.id]);
   const variant = useMemo(() => {
-    if (options.length === 0) return variants[0] || null;
-    if (!options.every((o) => selectedOptions[o.id])) return null;
-    return variants.find((v) => (v.choices || []).every((c) =>
-      selectedOptions[c.optionChoiceIds?.optionId] === c.optionChoiceIds?.choiceId)) || null;
-  }, [options, variants, selectedOptions]);
+    if (options.length === 0) return variantByKey.values().next().value || null;   // the single variant
+    if (!selectionComplete || duplicateKey) return null;
+    return variantByKey.get(choiceKey(options.map((o) => selectedOptions[o.id]))) || null;
+  }, [options, variantByKey, duplicateKey, selectedOptions, selectionComplete]);
 
+  // In stock OR pre-orderable counts as buyable; a preorder add carries preOrderRequested.
   const inStock = variant ? variant.inventoryStatus?.inStock !== false : true;
+  const isPreorder = !!variant && !inStock && variant.inventoryStatus?.preorderEnabled === true;
+  const available = inStock || isPreorder;
+
+  const missingModifier = modifiers.find((m) => m.mandatory && !(
+    m.modifierRenderType === "FREE_TEXT" ? modifierValues[m.freeTextSettings?.key] : modifierValues[m.key]));
+
   const canAdd = useMemo(() => {
+    if (!product) return false;
     if (options.length > 0 && !variant) return false;
-    if (variant && !inStock) return false;
-    return modifiers.filter((m) => m.mandatory).every((m) =>
-      m.modifierRenderType === "FREE_TEXT" ? !!modifierValues[m.freeTextSettings?.key] : !!modifierValues[m.key]);
-  }, [options, variant, inStock, modifiers, modifierValues]);
+    if (variant && !available) return false;
+    return !missingModifier;
+  }, [product, options, variant, available, missingModifier]);
+
+  // Why the buy button is disabled — neutral guidance to render next to the action ("Choose a
+  // size"), not an error; null when the buyer can add. Promote to error styling only after they try.
+  const blockedReason = useMemo(() => {
+    if (!product) return null;
+    if (duplicateKey) return "This product's variants can't be resolved right now.";
+    if (options.length > 0 && !selectionComplete) {
+      const missing = options.filter((o) => !selectedOptions[o.id]).map((o) => o.name);
+      return `Choose ${missing.join(" and ")}`;
+    }
+    if (options.length > 0 && !variant) return "This combination isn't available";
+    if (variant && !available) return "Out of stock";
+    if (missingModifier) return `Add ${missingModifier.name}`;
+    return null;
+  }, [product, duplicateKey, options, selectionComplete, selectedOptions, variant, available, missingModifier]);
 
-  // Everything the buyer sees follows the resolved `variant` (also returned below, so an agent can
-  // surface more from it — sku, barcode, subscriptionPricesInfo — without new plumbing). Price and
-  // its struck-through "was" price come off the variant, falling back to the product's range before
-  // every option is picked.
-  const price = variant?.price?.actualPrice?.formattedAmount || product?.actualPriceRange?.minValue?.formattedAmount || "";
-  const compareAtPrice = variant?.price?.compareAtPrice?.formattedAmount || product?.compareAtPriceRange?.minValue?.formattedAmount || "";
+  // Everything the buyer sees follows the resolved `variant` (also returned below). The price obeys
+  // the exact precedence in sellingPrice(): an automatic discount beats the regular price and strikes
+  // it; else the regular price with the merchant's compare-at as the "was". Before every option is
+  // picked, the product's min–max range (one value when equal) — never an empty price.
+  const min = product?.actualPriceRange?.minValue, max = product?.actualPriceRange?.maxValue;
+  const rangeDisplay = min?.amount && max?.amount && min.amount !== max.amount
+    ? `${min.formattedAmount} – ${max.formattedAmount}` : (min?.formattedAmount || "");
+  const resolved = variant ? sellingPrice(variant.price) : null;
+  const price = resolved?.current?.formattedAmount || rangeDisplay;
+  const compareAtPrice = resolved && resolved.original?.formattedAmount &&
+    Number(resolved.original.amount) > Number(resolved.current?.amount) ? resolved.original.formattedAmount : "";
+  const discountNames = product?.discountInfo?.discountRuleNames || [];   // automatic discounts, product level
 
   // The gallery follows the selection. Prefer the selected choice's own image (the per-swatch photo,
   // choice.media.items[].mediaId) — Wix's per-variant media is often NOT differentiated (it defaults to
@@ -82,7 +123,11 @@ export function useProductDetail(slug) {
     return variantImage(variant);
   }, [variant, options, selectedOptions]);
 
-  const selectOption = (optionId, choiceId) => setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
+  // Changing an option resets the quantity — the ceiling belongs to the newly resolved variant.
+  const selectOption = (optionId, choiceId) => {
+    setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
+    setQuantity(1);
+  };
   const setModifier = (key, value) => setModifierValues((s) => ({ ...s, [key]: value }));
 
   async function submit() {
@@ -101,6 +146,7 @@ export function useProductDetail(slug) {
       return await addToCart(product.id, variant?.id, Math.max(1, Number(quantity) || 1), {
         modifierChoices: Object.keys(modifierChoices).length ? modifierChoices : undefined,
         customTextFields: Object.keys(customTextFields).length ? customTextFields : undefined,
+        preorder: isPreorder,
       });
     } finally {
       setAdding(false);
@@ -111,6 +157,7 @@ export function useProductDetail(slug) {
     product, notFound, error, retry: () => setReloadKey((k) => k + 1),
     options, modifiers,
     selectedOptions, selectOption, modifierValues, setModifier,
-    quantity, setQuantity, variant, inStock, canAdd, adding, price, compareAtPrice, submit, focusMediaUrl,
+    quantity, setQuantity, variant, inStock, isPreorder, canAdd, blockedReason, adding,
+    price, compareAtPrice, discountNames, submit, focusMediaUrl,
   };
 }