@wix/agent-skills 1.19.1 → 1.20.0

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

@@ -103,18 +103,23 @@ 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)
+    teaser,           // plain-text description for the tile — plainDescription is HTML; never render it raw on a card
     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 +203,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 +229,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
@@ -253,7 +266,9 @@ The product-detail example above provides both groups:
 // Text modifier: d.setModifier(m.key, text)
 ```
 Retired option choices are filtered out. Respect each choice's `inStock` and modifier's
-`mandatory` flag; the hook supplies colour values and selection state without prescribing layout.
+`mandatory` flag. A choice with `isColorSwatch` renders as a **color swatch** filled with its
+`colorCode` and labelled by its name — not as a text pill; the hook supplies the values and selection
+state without prescribing the rest of the layout.
 
 ### Images
 `useProductCard` returns normalized `image`/`hoverImage`, and `useProductDetail` returns normalized
@@ -277,14 +292,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 +316,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 +327,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,16 +341,29 @@ 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. The estimate's
+`priceSummary.delivery`, `tax`, and `additionalFees` read `"0"` when nothing was calculated (verified
+live), so a zero there is not "Free shipping" or "No tax" — don't render those rows from the estimate.
 
 Line `quantityInfo.confirmedQuantity` is the current quantity; `availableQuantity` caps increases
 when finite. `status` can be `IN_STOCK`, `PARTIALLY_IN_STOCK`, `OUT_OF_STOCK`, or
 `REMOVED_FROM_CATALOG`; surface unavailable lines and prevent checkout until resolved.
 
 ## Routes and provider
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No shipped source reads needed to wire this.** `CartDrawer` and `CartButton`
 are default exports that take **no props**. `CartProvider` is a named export accepting `children`;
 wire these exactly as shown below.
@@ -416,6 +450,53 @@ function Layout() {
 }
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/shop` | `src/routes/shop.jsx` | `Shop` |
+| `/product/:slug` | `src/routes/product.$slug.jsx` | `ProductDetail` |
+
+```jsx
+// src/routes/shop.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Shop from "@/pages/Shop";
+
+export const Route = createFileRoute("/shop")({ component: Shop });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
+## 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 +506,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, teaser,
+//           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,13 @@ 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;
+
+    // plainDescription is an HTML string despite its name (<p>…</p>). A card wants plain text:
+    // strip the tags and cut at a word boundary, so no tile ever prints a literal "<p>".
+    const text = (product?.plainDescription || "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    const teaser = text.length > 140 ? `${text.slice(0, 140).replace(/\s+\S*$/, "")}…` : text;
 
     // 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 +87,18 @@ 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)
+      teaser,              // plain-text description for the tile (tags stripped, ~140 chars) — never render plainDescription raw on a card
+      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]);
 }