@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -1,10 +1,15 @@
 # Wix Storefront — ready-made client
 
-The storefront client is **shipped as real files**, not snippets to regenerate. It's a complete
-catalog + PDP + server-cart + checkout, styled with your app's design tokens (base44's
-`src/index.css` — the shadcn palette the design phase already set). Copy it into the app and wire
-the routes — you generate almost none of the commerce code (variant resolution, modifiers, stock
-gating, the server cart all ship and are correct).
+The storefront **commerce engine ships as real files** — the hooks, the server cart, the REST
+transport, the image helpers, and the `Shop` listing page, all correct (variant resolution,
+modifiers, stock gating, checkout). It reads from your app's design tokens (base44's `src/index.css`
+— the shadcn palette the design phase already set).
+
+**The presentation doesn't ship — you build it** (STEP 3): the product **card**, **grid**, **variant
+controls**, and the whole **product (PDP) page**, plus **Home** and the **header/footer**. Each is
+built on a shipped hook whose return type + field shapes are documented in the outline right next to
+it — the data is handed to you done, the layout and look are yours. `Shop` renders once your
+`ProductGrid` exists; the PDP renders once you build its page — that's the point.
 
 Talks to Wix directly over the public `WIX_CLIENT_ID` (anonymous visitor tokens). Never mock
 products; never hand-build a `/checkout` URL — the shipped cart goes through the eCom
@@ -22,40 +27,38 @@ so you don't need to open them:**
 | file | what it is |
 |---|---|
 | `context/CartContext.jsx` | `useCart()` provider: server cart, add/update/remove, checkout |
-| `hooks/useProductDetail.js` | PDP data — product + variant resolution for a slug, plus load/add state |
+| `hooks/useProductDetail.js` | PDP data — product + variant resolution for a slug, plus load/add state; **your product page (STEP 3) is built on it** |
 | `hooks/useShop.js` | catalog listing — category menu, cursor paging, sort, failure state |
-| `hooks/useProductCard.js` | headless data layer for a grid tile — returns `leftBadges`, `promoBadge`, `priceDisplay`, `compareAtDisplay`, `colors`, `optionLabel`, `isQuickAddable`, `image`, `hoverImage`; **always use this to build your own product card UI on the grid** |
-| `components/ProductCard.jsx` | reference implementation of a grid tile built on `useProductCard` — read it for inspiration, build your own component rather than using it directly |
-| `components/ProductGrid.jsx` | reference grid layout (2-col mobile → auto-fill desktop) with skeleton + empty state — read it for the skeleton/empty-state patterns, build your own layout rather than using it directly |
-| `components/ProductGallery.jsx` | PDP main image + thumbnails |
-| `lib/storeImage.js` | `productImage()` / `productGallery()` / `storeImage()` — normalise Wix image urls |
+| `hooks/useProductCard.js` | headless data layer for a grid tile — returns `leftBadges`, `promoBadge`, `priceDisplay`, `compareAtDisplay`, `colors`, `optionLabel`, `isQuickAddable`, `image`, `hoverImage`; **your `ProductCard` (STEP 3) is built on it** |
+| `lib/storeImage.js` | `productImage()` / `productGallery()` / `storeImage()` / `choiceImage()` — normalise Wix image urls; `productGallery(product)` → `[{ url, altText }]` (your PDP gallery); `choiceImage(choice)` resolves an option choice's photo (V3 read shape: `media.items[].mediaId`, not `linkedMedia`) |
 | `components/CartButton.jsx` | header cart **icon** button with a live-count badge |
 | `components/CartDrawer.jsx` | slide-over cart (mount once; opens from `useCart`) |
-| `hooks/useVariantOptions.js` | headless data layer for options/modifiers — returns `optionGroups` + `modifierGroups` (normalised, render-agnostic); **always use this to build your own variant UI on the PDP** |
-| `components/VariantPicker.jsx` | reference implementation of a variant selector built on `useVariantOptions` (pills + colour swatches) — read it for inspiration, but build your own component rather than using it directly |
+| `hooks/useVariantOptions.js` | headless data layer for options/modifiers — returns `optionGroups` + `modifierGroups` (normalised, render-agnostic); **your PDP's variant controls (STEP 3) render from it** |
 | `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 3) |
-| `pages/Shop.jsx`, `pages/ProductDetail.jsx` | the two shipped routes (`/shop`, `/product/:slug`) |
+| `pages/Shop.jsx` | the shipped `/shop` listing page — renders your `ProductGrid` (you build `/product/:slug` and `/`) |
 | `rest/wix-config.js` | the two ids, written by the install step |
 | `rest/wix-client.js` + `rest/wix-store-*.js` | REST transport + catalog/cart helpers |
 
-They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
-`read_file` the shipped page/component/hook source to inspect it** — the table above says what each is
-and every field shape you need is in the snippets below. Read a shipped file's source **only** on a
-real fallback — a runtime error, or a field the snippets don't cover (see "Fallback only" at the
-end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
+Everything in the table is already in place — go **straight to wiring + building your presentation**
+(card, grid, variant controls, the product page, Home — STEP 3), nothing to verify first.
+**Don't `read_file` the shipped page/hook source to inspect it** — the table says what each is and
+every field shape you need is in the outlines below. Read a shipped file's source **only** on a real
+fallback — a runtime error, or a field the outlines don't cover (see "Fallback only" at the end).
+(Shipped files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/storefront/app/` → `src/`.)
 
 
-## STEP 2 — Theme (nothing to style on the shipped components)
-The shipped components carry **no palette of their own** — they render from base44's design tokens
+## STEP 2 — Theme
+The shipped pages carry **no palette of their own** — they render from base44's design tokens
 in `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`,
 `--muted`, `--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`,
 `text-foreground`, `bg-primary`, `text-muted-foreground`, `border-border`, `rounded-lg`,
 `font-display`). Those tokens are **already set to the brand by the design phase**, so the shipped
 pages are themed with zero work here. To adjust the palette, edit `index.css` (`:root` **and**
 `.dark`) — the base44 way; **never add a parallel theme file (e.g. a `theme.css`) or restyle the
-shipped JSX.** Build the Home/Header you add (STEP 3) from the **same** base44 tokens/classes so it
-matches automatically. A dark brand is just base44's dark palette in `index.css` — no per-component work.
+shipped pages.** Style the components you build (STEP 3) and the Home/Header you add from the
+**same** base44 tokens/classes so everything matches automatically. A dark brand is just base44's
+dark palette in `index.css` — no per-component work.
 
 ## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
@@ -64,77 +67,126 @@ replace it.
 - Wrap the routed tree in `<CartProvider>` (from `@/context/CartContext`).
 - Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
   route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every** page
-  — including the shipped `Shop` / `ProductDetail` — so you **never edit the shipped pages to add a
-  header/footer** (they render inside `<Outlet/>` as-is). Mount `<CartDrawer/>` once in the Layout.
+  — including the shipped `Shop` and your own pages — so you **never edit the shipped `Shop` to add a
+  header/footer** (it renders inside `<Outlet/>` as-is). Mount `<CartDrawer/>` once in the Layout.
 - **Pin the top chrome as one fixed block.** Put `<WixManageBanner/>` (shipped, preview-only) **above**
   your `<Header/>` inside a single `position:fixed` top region — the header itself is plain in-flow
   markup, the region owns the fixing — so banner + header ride together (no scroll drift/gap). Pad
   the content by the region's measured height so it clears the chrome and self-corrects when the
   banner is dismissed.
-- Routes under the Layout: `/shop` → `Shop`, `/product/:slug` → `ProductDetail` (both shipped, as-is).
-  **You add `/` → your own Home** page.
-- **Build your own variant selector on the PDP — this is required, not optional, and it's your chance to be creative.** `ProductDetail.jsx` ships with a `VariantPicker` import — remove it and replace with your own component built on `useVariantOptions`. Design the controls to fit the brief: the business type, the tone, the audience. A fashion brand might want large colour swatches and a size chart link; a tech store might want a compact dropdown. `VariantPicker.jsx` is in `src/` for reference — read it, don't use it:
-- **Build your own product card for the grid — this is required, not optional, and it's your chance to be creative.** `ProductGrid.jsx` ships with a `ProductCard` import — replace it with your own component built on `useProductCard`. The hook hands you everything the tile needs (badges, price display, colour dots, quick-add flag, images) — you decide the layout, shape, hover behaviour, and CTA style. A lifestyle brand might want full-bleed images with an overlay gradient; a tech store might want a compact horizontal list item. `ProductCard.jsx` is in `src/` for reference — read it, don't use it:
-- **Build your own grid layout — this is required, not optional, and it's your chance to be creative.** `ProductGrid.jsx` ships as a reference (2-col mobile → auto-fill desktop, 220px min) — replace it with an arrangement that fits the brief. A curated boutique might want a 3-col asymmetric editorial layout; a high-volume store might want a dense 4-col grid; a featured strip on the home page might want horizontal scroll. Keep the skeleton and empty-state patterns from `ProductGrid.jsx` (copy them into your own component) — the states themselves are correct, just the layout is yours to choose.
+- Routes under the Layout: `/shop` → `Shop` (shipped, renders your grid); `/product/:slug` → **your
+  `ProductDetail`**; `/` → **your `Home`**.
+
+**Build the presentation — it's all yours.** Each piece below is built on a shipped hook whose return
+type + field shapes are in the outline right after this list — the data is done, the render is yours.
+`Shop` won't show products until `ProductGrid` exists, and `/product/:slug` won't render until you
+build the product page, so these aren't optional:
+
+- **`components/ProductGrid.jsx`** — `Shop` and your Home render it. It receives `products`, `loading`,
+  `empty`, `emptyHint` and owns three states (loading, empty, list) plus the layout. A boutique might
+  want a 3-col editorial layout; a high-volume store a dense 4-col grid; a home strip a horizontal scroll.
+- **`components/ProductCard.jsx`** — your grid maps each product to it. Built on `useProductCard`
+  (badges, price display, colour dots, quick-add flag, images) — you decide layout, shape, hover, CTA.
+  A lifestyle brand might want full-bleed images with an overlay gradient; a tech store a compact item.
+- **`pages/ProductDetail.jsx`** — the **whole product page**, built on `useProductDetail`; route
+  `/product/:slug` to it. Gallery, price, description, the variant controls (options/modifiers via
+  `useVariantOptions`), the buy box — you arrange and style all of it (nothing PDP ships). This is the
+  surface that usually looks most generic, so make the layout the brand's: an editorial split, a sticky
+  buy column, a full-bleed gallery, large swatches vs a compact dropdown — your call.
 
 ```jsx
+// components/ProductCard.jsx — your grid maps each product to it.
 import { Link } from "react-router-dom";
-import { useCart } from "@/context/CartContext";
+import { useCart } from "@/context/CartContext";          // addToCart(product.id) for quick-add
 import { useProductCard } from "@/hooks/useProductCard";
 
-export default function MyProductCard({ product }) {
+export default function ProductCard({ product }) {
   const { addToCart } = useCart();
   const {
     isSoldOut, isPreorder,
-    leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }] — render left side of image
-    promoBadge,       // { type: 'discount'|'ribbon', label } | null — render right side
-    priceDisplay,     // "€10" or "€10 – €20" (range when variants differ)
-    compareAtDisplay, // original price string | null
-    colors,           // hex strings → render as dots (slice to how many you want)
-    optionLabel,      // "3 sizes · 2 materials" or empty string
-    isQuickAddable,   // true for single-variant, in-stock products
-    image,            // primary image URL | null
-    hoverImage,       // second image URL | null
+    leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }] — image top-left
+    promoBadge,       // { type: 'discount'|'ribbon', label } | null — image top-right
+    priceDisplay,     // "€10"  |  "€10 – €20" (range when variants differ)
+    compareAtDisplay, // original price string | null — strike-through
+    colors,           // hex strings → colour dots
+    optionLabel,      // "3 sizes · 2 materials" | ""
+    isQuickAddable,   // true → addToCart(product.id);  else <Link to={`/product/${product.slug}`}>
+    image, hoverImage,// URLs | null
   } = useProductCard(product);
-
-  // Then render however you want:
-  return (
-    <div>
-      {/* image, badges, price, colour dots, quick-add or "Choose options" CTA */}
-      {isQuickAddable && <button onClick={() => addToCart(product.id)}>Quick add</button>}
-      {!isQuickAddable && !isSoldOut && <Link to={`/product/${product.slug}`}>Choose options</Link>}
-      {isSoldOut && isPreorder && <Link to={`/product/${product.slug}`}>Pre-order</Link>}
-    </div>
-  );
+  // …you implement the tile.
 }
 ```
 
 ```jsx
+// Variant controls — render the product's options/modifiers from useVariantOptions.
+// The inputs (options, modifiers, selectedOptions, modifierValues) come from useProductDetail (below).
 import { useVariantOptions } from "@/hooks/useVariantOptions";
 
-// options/modifiers/selectedOptions/modifierValues come from useProductDetail:
 const { optionGroups, modifierGroups } = useVariantOptions(options, modifiers, selectedOptions, modifierValues);
-
-// optionGroups: [{ id, name, isColor, choices: [{ choiceId, name, colorCode, isColorSwatch, inStock, selected }] }]
+// optionGroups:   [{ id, name, isColor, choices: [{ choiceId, name, colorCode, isColorSwatch, inStock, selected }] }]
 // modifierGroups: [{ key, name, mandatory, type: 'choices'|'text', choices?: [{ key, name, selected }], value?: string }]
+// pick a choice:  selectOption(group.id, choice.choiceId)
+// set a modifier: setModifier(m.key, choice.key)   ·   text type: setModifier(m.key, e.target.value)
+```
 
-// Then render however you want:
-optionGroups.map((group) =>
-  group.choices.map((c) =>
-    c.isColorSwatch
-      ? <MySwatch key={c.choiceId} color={c.colorCode} active={c.selected} disabled={!c.inStock}
-                  onClick={() => selectOption(group.id, c.choiceId)} />
-      : <MyPill  key={c.choiceId} active={c.selected} disabled={!c.inStock}
-                  onClick={() => selectOption(group.id, c.choiceId)}>{c.name}</MyPill>
-  )
-);
-modifierGroups.map((m) =>
-  m.type === "text"
-    ? <MyInput key={m.key} label={m.name} value={m.value} onChange={(v) => setModifier(m.key, v)} />
-    : m.choices.map((c) =>
-        <MyPill key={c.key} active={c.selected} onClick={() => setModifier(m.key, c.key)}>{c.name}</MyPill>
-      )
-);
+```jsx
+// components/ProductGrid.jsx — Shop and your Home render it.
+import ProductCard from "./ProductCard";                 // your card, above
+
+export default function ProductGrid({ products, loading, empty, emptyHint }) {
+  // products   — array | null (null while loading)
+  // loading    — boolean
+  // empty      — heading string for the no-products state
+  // emptyHint  — sub-text string for the no-products state
+  // …you implement: the loading state, the empty state (empty + emptyHint), and the layout
+  //    mapping products → <ProductCard product={p} />.
+}
+```
+
+```jsx
+// pages/ProductDetail.jsx — YOU build the whole product page. Route `/product/:slug` to it.
+// A thin view over useProductDetail: keep the data logic in the hook, render however fits the brand.
+import { useMemo } from "react";
+import { useParams, Link } from "react-router-dom";
+import { useProductDetail } from "@/hooks/useProductDetail";
+import { productGallery } from "@/lib/storeImage";
+
+export default function ProductDetail() {
+  const { slug } = useParams();
+  const d = useProductDetail(slug);
+  // useProductDetail(slug) returns:
+  //   product         Wix product | null (loading) — has .name, .plainDescription (HTML), .slug
+  //   notFound        bool — dead link (distinct from error)
+  //   error           string | null — failed load; call retry() to reload
+  //   retry           () => void
+  //   price           formatted string, follows the selection ("€24.00")
+  //   compareAtPrice  formatted string — a "was" price; strike it only when it differs from price
+  //   options, modifiers                                            → feed useVariantOptions for the variant controls (block above)
+  //   selectedOptions, selectOption, modifierValues, setModifier    → also for the variant controls
+  //   variant         resolved variant | null (null until every option is picked)
+  //   focusMediaUrl   image url for the selected choice — make the gallery show it
+  //   quantity, setQuantity(n)   number (may be "" mid-edit) — keep min 1
+  //   inStock, canAdd, adding    booleans that gate the buy button
+  //   submit          async () => adds the resolved variant + quantity + modifiers to the cart
+  const images = useMemo(() => productGallery(d.product), [d.product]);  // [{ url, altText }], main first, de-duped
+
+  // …you implement the page. Handle in order:
+  //   error     → show d.error + a retry button (onClick={d.retry})
+  //   notFound  → a "not found" message + a <Link to="/shop">
+  //   !product  → a loading placeholder
+  //   else the product view, laid out to fit the brand:
+  //     • gallery from `images` — main + thumbnails, a carousel, a full-bleed hero (your call);
+  //       make the shown image follow d.focusMediaUrl when a choice is selected
+  //     • d.product.name · d.price (strike d.compareAtPrice when it differs) ·
+  //       d.product.plainDescription (HTML → dangerouslySetInnerHTML)
+  //     • variant controls — render d.options/d.modifiers via useVariantOptions (block above);
+  //       d.selectOption / d.setModifier update the selection
+  //     • a "pick an option to continue" hint when d.options.length && !d.variant
+  //     • a quantity control (d.quantity / d.setQuantity, min 1 — a −/＋ stepper reads better than a
+  //       native number input) + the buy button:
+  //         <button disabled={!d.canAdd || d.adding} onClick={d.submit}>
+  //           {d.adding ? "Adding…" : d.inStock ? "Add to cart" : "Out of stock"}</button>
+}
 ```
 
 ```jsx
@@ -144,7 +196,7 @@ import { CartProvider } from "@/context/CartContext";
 import CartDrawer from "@/components/CartDrawer";
 import WixManageBanner from "@/components/WixManageBanner";   // shipped, preview-only · default export, no props
 import Shop from "@/pages/Shop";                       // shipped · default export, no props
-import ProductDetail from "@/pages/ProductDetail";     // shipped · default export, no props
+import ProductDetail from "@/pages/ProductDetail";     // YOU build
 import Home from "@/pages/Home";       // YOU build
 import Header from "@/components/Header";   // YOU build — plain in-flow markup, NOT position:fixed
 import Footer from "@/components/Footer";   // YOU build
@@ -163,7 +215,7 @@ function Layout() {
       <Header />                             {/* your brand header, in-flow inside this fixed block */}
     </div>
     <div style={{ paddingTop: offset }}>     {/* clears the chrome; shrinks when the banner is dismissed */}
-      <Outlet />                             {/* shipped Shop/ProductDetail render here, untouched */}
+      <Outlet />                             {/* shipped Shop + your pages render here */}
       <Footer />
     </div>
     <CartDrawer />                           {/* overlays every page */}
@@ -175,7 +227,7 @@ function Layout() {
     <Route element={<Layout />}>                                   {/* chrome wraps all */}
       <Route path="/" element={<Home />} />                        {/* yours */}
       <Route path="/shop" element={<Shop />} />                    {/* shipped, as-is */}
-      <Route path="/product/:slug" element={<ProductDetail />} />  {/* shipped, as-is */}
+      <Route path="/product/:slug" element={<ProductDetail />} />  {/* yours */}
     </Route>
   </Routes>
 </CartProvider>
@@ -184,8 +236,8 @@ function Layout() {
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** (mount `<CartButton/>` in it) and a **`Footer`** — the
 two you drop into the `Layout` (STEP 3) so they wrap every route — plus the overall brand story,
-styled from the same base44 tokens/classes. **Compose the shipped pieces** — a
-featured strip is just `queryProducts` + the shipped `ProductGrid`; the nav is a `<CartButton/>`
+styled from the same base44 tokens/classes. **Reuse your own `ProductGrid`** (STEP 3) and the shipped
+cart pieces — a featured strip is just `queryProducts` + your `ProductGrid`; the nav is a `<CartButton/>`
 (a clean cart-**icon** button with a live-count badge — render it as-is, don't wrap it in your own
 text button) + a link to `/shop`:
 
@@ -193,8 +245,8 @@ text button) + a link to `/shop`:
 import { useState, useEffect } from "react";
 import { Link } from "react-router-dom";
 import { queryProducts } from "@/rest/wix-store-catalog";
-import ProductGrid from "@/components/ProductGrid";
-import CartButton from "@/components/CartButton";
+import ProductGrid from "@/components/ProductGrid";        // yours (STEP 3)
+import CartButton from "@/components/CartButton";           // shipped
 
 // Responsive header: choose ONE branch with a state flag, so <CartButton/> mounts once.
 // Do NOT render a desktop nav AND a mobile nav toggled by `hidden md:flex` / `md:hidden`:
@@ -237,6 +289,8 @@ render.
 
 ## Using the client from your own UI (cart, hand-built images)
 
+> Migrating from Cart V1 / Checkout V1? These helpers are V2-only — see the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide) for the before/after.
+
 ```jsx
 import { Link } from "react-router-dom";
 import { useCart } from "@/context/CartContext";
@@ -246,22 +300,27 @@ import { useCart } from "@/context/CartContext";
 //   addToCart(productId, variantId?, qty=1, { modifierChoices?, customTextFields? }?),
 //   removeItem(lineItemId), updateQuantity(lineItemId, qty), checkout(), refreshCart() }
 // Every mutation catches its own failure into `error` (the shipped CartDrawer renders it), so a
-// refusal — an empty cart, or a line item that stopped being AVAILABLE — reaches the buyer instead
+// refusal — an empty cart, or a line item whose status left IN_STOCK — reaches the buyer instead
 // of becoming an unhandled rejection.
 //
-// Cart money: every amount is { amount, convertedAmount, formattedAmount, formattedConvertedAmount } —
-// show a formatted one so the currency symbol and grouping come from Wix. Read
-// `cart.subtotalAfterDiscounts` rather than `cart.subtotal`: the two match until a cart-level coupon
-// applies, and then `subtotal` is the pre-discount figure. `cart.discount` + `cart.appliedDiscounts`
-// carry the reduction. Never sum line items yourself — tax and shipping resolve at checkout.
-// `lineItems[].availability.quantityAvailable` is the stock cap for a quantity control.
+// Cart money: every amount is a ConvertedMoney { amount, convertedAmount } with NO formatted string —
+// `amount` is in the site currency, `convertedAmount` in the display currency; format the number
+// yourself (Intl.NumberFormat with the cart's currency —
+// `cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode`) so the symbol and grouping
+// match the locale. The V2 cart has no `subtotalAfterDiscounts`/`discount`/`appliedDiscounts`: it
+// carries only a raw `cart.subtotal` (ConvertedMoney). The authoritative discounted totals come from
+// a currentCartV2 estimate/calculate `summary.priceSummary`, not the cart — call that when you need
+// the after-coupon figure; otherwise show `cart.subtotal`. Never sum line items yourself — tax and
+// shipping resolve at checkout.
+// A line's `status` (IN_STOCK / PARTIALLY_IN_STOCK / OUT_OF_STOCK) tells a quantity control whether
+// another increment is still fulfillable.
 
 function CartCount() {                                   // header badge
   const { itemCount, setIsOpen } = useCart();
   return <button onClick={() => setIsOpen(true)}>Cart ({itemCount})</button>;
 }
 
-// Buy from a card → link to the PDP; the shipped ProductDetail owns options/variants + add-to-cart.
+// Buy from a card → link to the PDP; your ProductDetail (on useProductDetail) owns options/variants + add-to-cart.
 // (Listing helpers return no variants — only getProductBySlug does — so buying happens on the PDP.)
 const CardBuy = ({ product }) => <Link to={`/product/${product.slug}`}>View</Link>;
 
@@ -294,7 +353,7 @@ const { products: inCategory } = await queryProductsByCategory(menu[0].id, { lim
 
 // product.plainDescription is HTML → render as HTML (the PDP does this):
 <div dangerouslySetInnerHTML={{ __html: product.plainDescription }} />
-// image urls live at: product.media.main.image.url  ·  cart lineItems[].image.url
+// image urls live at: product.media.main.image.url  ·  cart lineItems[].attributes.image.url
 ```
 
 Fallback only — when you hit an error or need something not shown here (coupons, members, a field
@@ -306,8 +365,8 @@ reference page inline; these are the areas they sit in:
 - Headless redirect session (hosted checkout): https://dev.wix.com/docs/api-reference/business-management/headless/redirects.md
 
 ## Hard rules
-- Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
-- Header/footer live in a `Layout` around `<Outlet/>` (STEP 3) — never edit the shipped `Shop`/`ProductDetail` to add chrome.
+- Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped pages or adding a parallel theme file. Everything you build (card, grid, PDP, variant controls, Home) draws from the same tokens.
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 3) — never edit the shipped `Shop` to add chrome.
 - The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your `Header` is plain in-flow markup (not `position:fixed`).
 - Checkout goes through the shipped cart (redirect-session) — never a hand-built `/checkout` URL.
 - Render live Wix data or the shipped empty state — never mock products.
@@ -323,9 +382,10 @@ client build; run in parallel.
 
 ## Verify (before declaring done)
 - [ ] Client files copied into `src/`; `WIX_CLIENT_ID` set (not the placeholder).
-- [ ] Brand palette lives in `index.css` (`:root`/`.dark`); no parallel theme file; shipped components/pages not restyled or rewritten.
-- [ ] **Opened `/shop` and a product detail page** (not just the home page) and confirmed the shipped cards render themed (surface, text, brand color) with images.
-- [ ] `Layout` (fixed `<WixManageBanner/>` + `<Header/>` region, then `<Outlet/>` + Footer) wraps all routes; shipped `Shop`/`ProductDetail` untouched; content clears the fixed chrome; `<CartProvider>` wraps the tree; `<CartDrawer/>` mounted; `<CartButton/>` in the header.
+- [ ] **The pieces you own exist and are wired:** `components/ProductCard.jsx`, `components/ProductGrid.jsx` (imported by `Shop` + your Home), and `pages/ProductDetail.jsx` (routed at `/product/:slug`, with working variant controls). `/shop` and a PDP compile and render (they won't until these exist).
+- [ ] Brand palette lives in `index.css` (`:root`/`.dark`); no parallel theme file; the shipped `Shop` page not restyled or rewritten.
+- [ ] **Opened `/shop` and a product detail page** (not just the home page) and confirmed your cards render themed (surface, text, brand color) with images; the grid shows its loading + empty states; the PDP shows the gallery, price, variant controls, and add-to-cart, and its error/not-found/loading states hold.
+- [ ] `Layout` (fixed `<WixManageBanner/>` + `<Header/>` region, then `<Outlet/>` + Footer) wraps all routes; the shipped `Shop` untouched; content clears the fixed chrome; `<CartProvider>` wraps the tree; `<CartDrawer/>` mounted; `<CartButton/>` in the header.
 - [ ] Cart survives reload (same visitor); add / update-qty / remove work; checkout redirects; the drawer shows a **subtotal**.
 - [ ] Empty catalog shows the shipped empty state; no mock products anywhere.
 - [ ] A product with several images shows **thumbnails** on the PDP, and one with per-variant prices shows a **range** on its card.

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

@@ -2,29 +2,36 @@
 // check out via the context (redirect-session URL). Styled with base44 design tokens (shadcn Tailwind classes).
 //
 // Load-bearing beyond the styling:
-// • prices come from the SERVER cart — `price` is post-discount, `fullPrice` is before it, so the
-//   two together are the strikethrough. Never compute a total in the client: tax, shipping and
-//   promotions are resolved server-side, so `subtotal` is the only figure safe to show pre-checkout.
-//   Money objects carry { amount, convertedAmount, formattedAmount, formattedConvertedAmount }; use a
-//   formatted one so the currency symbol and grouping come from Wix. Prefer `subtotalAfterDiscounts`
-//   over `subtotal` — the two are equal until a cart-level coupon applies, and then `subtotal` is the
-//   pre-discount figure, which would quote the buyer more than they'll pay.
-// • `availability.quantityAvailable` caps the stepper, so exceeding stock is refused here rather than
+// • 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`.
+// • `quantityInfo.availableQuantity` caps the stepper, so exceeding stock is refused here rather than
 //   at checkout.
-// • `availability.status` is flagged per line here because checkout() refuses the whole cart when
-//   any item isn't AVAILABLE — showing it on the row is what makes that refusal understandable.
+// • `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 { useCart } from "@/context/CartContext";
 import { storeImage } from "@/lib/storeImage";
 
+// Cart V2 money is a ConvertedMoney { amount, convertedAmount } with NO formatted string — format it
+// with the cart's currency (buyer's display currency when present, else the site currency).
+function formatCartMoney(money, cart) {
+  const value = money?.convertedAmount ?? money?.amount;
+  const currency = cart?.customerInfo?.currencyCode ?? cart?.businessInfo?.currencyCode ?? "USD";
+  return value == null ? "" : new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+}
+
 export default function CartDrawer() {
   const { cart, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading, error, clearError } = useCart();
   const lineItems = cart?.lineItems ?? [];
-  const money = (m) => m?.formattedConvertedAmount || m?.formattedAmount;
-  const subtotal = money(cart?.subtotalAfterDiscounts) || money(cart?.subtotal);
-  const discount = money(cart?.discount);
-  const hasDiscount = (cart?.appliedDiscounts?.length || 0) > 0 && Number(cart?.discount?.amount) > 0;
-  const unavailable = lineItems.filter((li) => li.availability?.status && li.availability.status !== "AVAILABLE");
+  // 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);
+  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).
@@ -70,46 +77,44 @@ export default function CartDrawer() {
                 className="border border-border bg-card text-foreground rounded-sm py-2 px-4 cursor-pointer text-sm">Continue shopping</button>
             </div>
           ) : lineItems.map((item) => {
-            const image = storeImage(item.image?.url);
-            const struck = item.fullPrice?.formattedAmount;
-            const paid = item.price?.formattedAmount;
-            const isOut = item.availability?.status && item.availability.status !== "AVAILABLE";
-            const stock = item.availability?.quantityAvailable;
-            const atStockLimit = Number.isFinite(stock) && item.quantity >= stock;
+            const image = storeImage(item.attributes?.image?.url);
+            const paid = formatCartMoney(item.pricing?.totalPrice, cart);
+            const isOut = item.status && item.status !== "IN_STOCK";
+            const stock = item.quantityInfo?.availableQuantity;
+            const qty = item.quantityInfo?.confirmedQuantity;
+            const atStockLimit = Number.isFinite(stock) && qty >= stock;
             return (
               <div key={item.id} className="flex gap-3 py-3 px-0 border-b border-border">
                 <div className="w-16 h-16 shrink-0 rounded-sm bg-card overflow-hidden">
-                  {image && <img src={image} alt={item.productName?.original || ""} className="w-full h-full object-cover" />}
+                  {image && <img src={image} alt={item.name?.original || ""} className="w-full h-full object-cover" />}
                 </div>
                 <div className="flex-1 flex flex-col gap-1 min-w-0">
-                  <span className="font-semibold truncate">{item.productName?.original}</span>
-                  {item.descriptionLines?.map((dl, i) => (
+                  <span className="font-semibold truncate">{item.name?.original}</span>
+                  {/* V2 nests these under `attributes` — a top-level lineItem.descriptionLines no longer exists */}
+                  {item.attributes?.descriptionLines?.map((dl, i) => (
                     <small key={i} className="text-muted-foreground">
                       {dl.name?.original}: {dl.plainText?.original || dl.colorInfo?.original}
                     </small>
                   ))}
                   {isOut ? (
                     <small className="text-destructive">
-                      {item.availability.status === "NOT_AVAILABLE" ? "No longer available" : "Not enough stock"}
+                      {item.status === "PARTIALLY_IN_STOCK" ? "Not enough stock" : "No longer available"}
                     </small>
                   ) : atStockLimit ? (
                     <small className="text-muted-foreground">Only {stock} left</small>
                   ) : null}
                   <div className="flex items-center gap-2 mt-1">
-                    <QtyButton disabled={loading || item.quantity <= 1} label="Decrease quantity"
-                      onClick={() => updateQuantity(item.id, item.quantity - 1)}>−</QtyButton>
-                    <span className="min-w-5 text-center" aria-label={`Quantity ${item.quantity}`}>{item.quantity}</span>
+                    <QtyButton disabled={loading || qty <= 1} label="Decrease quantity"
+                      onClick={() => updateQuantity(item.id, qty - 1)}>−</QtyButton>
+                    <span className="min-w-5 text-center" aria-label={`Quantity ${qty}`}>{qty}</span>
                     <QtyButton disabled={loading || atStockLimit} label="Increase quantity"
-                      onClick={() => updateQuantity(item.id, item.quantity + 1)}>+</QtyButton>
+                      onClick={() => updateQuantity(item.id, qty + 1)}>+</QtyButton>
                     <button onClick={() => removeItem(item.id)} disabled={loading}
                       className="ml-auto border-none bg-transparent cursor-pointer text-muted-foreground text-[13px] underline disabled:opacity-50">Remove</button>
                   </div>
                 </div>
                 <div className="flex flex-col items-end shrink-0">
                   <span className="font-semibold">{paid}</span>
-                  {struck && struck !== paid && (
-                    <span className="text-muted-foreground line-through text-[13px]">{struck}</span>
-                  )}
                 </div>
               </div>
             );
@@ -118,12 +123,6 @@ export default function CartDrawer() {
 
         {lineItems.length > 0 && (
           <footer className="p-4 border-t border-border flex flex-col gap-3">
-            {hasDiscount && (
-              <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

@@ -16,7 +16,7 @@ export function CartProvider({ children }) {
   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
-  // whose availability.status isn't AVAILABLE. Hold the message so the drawer can show it; without
+  // whose status isn't IN_STOCK. Hold the message so the drawer can show it; without
   // this the rejection is unhandled and the shopper sees the spinner stop with nothing said.
   const [error, setError] = useState(null);
 
@@ -28,7 +28,7 @@ export function CartProvider({ children }) {
     return () => document.removeEventListener("visibilitychange", onVisible);
   }, [refreshCart]);
 
-  const itemCount = (cart?.lineItems ?? []).reduce((n, li) => n + (li.quantity || 0), 0);
+  const itemCount = (cart?.lineItems ?? []).reduce((n, li) => n + (li.quantityInfo?.confirmedQuantity || 0), 0);
 
   // Every mutation runs through here so a rejection always lands somewhere visible. `run` keeps the
   // cart untouched on failure — the server stays the source of truth — and re-reads it for anything

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

@@ -5,7 +5,7 @@
 // renders what this returns.
 import { useState, useEffect, useMemo } from "react";
 import { getProductBySlug } from "@/rest/wix-store-catalog";
-import { storeImage } from "@/lib/storeImage";
+import { choiceImage, variantImage } from "@/lib/storeImage";
 import { useCart } from "@/context/CartContext";
 
 export function useProductDetail(slug) {
@@ -61,19 +61,26 @@ export function useProductDetail(slug) {
       m.modifierRenderType === "FREE_TEXT" ? !!modifierValues[m.freeTextSettings?.key] : !!modifierValues[m.key]);
   }, [options, variant, inStock, modifiers, modifierValues]);
 
+  // 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 || "";
 
-  // A colour choice carries `linkedMedia` — the shots of the product in that colour. Picking "Dark
-  // Green" should move the gallery to the green photo, so resolve the selection to a URL here; only
-  // colour-style choices have linked media, so the first hit across the options is the right one.
+  // 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
+  // the product's main image), so preferring the variant would override the correct choice image for
+  // every colour. Fall back to the resolved variant's image only when no chosen option carries one.
+  // See lib/storeImage: choiceImage() / variantImage().
   const focusMediaUrl = useMemo(() => {
     for (const o of options) {
       const choice = (o.choicesSettings?.choices || []).find((c) => c.choiceId === selectedOptions[o.id]);
-      const url = storeImage(choice?.linkedMedia?.[0]);
+      const url = choiceImage(choice);
       if (url) return url;
     }
-    return null;
-  }, [options, selectedOptions]);
+    return variantImage(variant);
+  }, [variant, options, selectedOptions]);
 
   const selectOption = (optionId, choiceId) => setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
   const setModifier = (key, value) => setModifierValues((s) => ({ ...s, [key]: value }));
@@ -104,6 +111,6 @@ 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, submit, focusMediaUrl,
+    quantity, setQuantity, variant, inStock, canAdd, adding, price, compareAtPrice, submit, focusMediaUrl,
   };
 }