@wix/agent-skills 1.17.0 → 1.18.1

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

@@ -0,0 +1,13 @@
+---
+name: rentals
+description: Rentals — renting out an item for a length the customer picks. Runs on the Bookings vertical.
+---
+
+# Rentals
+
+Rentals is **the Bookings vertical** — Wix Rentals runs on the Bookings APIs. There is nothing
+separate to build here.
+
+Read and follow `.agents/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md` (its
+**Rentals** section), and use the bookings scaffolds under `references/bookings/app/`. The install
+already deploys those for you when `rentals` is selected.

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`:
@@ -268,7 +320,7 @@ function CartCount() {                                   // header badge
   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>;
 
@@ -313,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.
@@ -330,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/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,
   };
 }

package/skills/wix-vibe-headless/references/storefront/app/lib/storeImage.js

@@ -10,6 +10,43 @@ export function storeImage(value) {
   return url;
 }
 
+// A Wix media id (e.g. "abc123~mv2.jpg") is NOT a URL — build the static CDN url for it.
+export function wixMediaUrl(mediaId) {
+  if (!mediaId || typeof mediaId !== "string") return null;
+  if (mediaId.startsWith("http") || mediaId.startsWith("//")) return storeImage(mediaId);
+  return `https://static.wixstatic.com/media/${mediaId}`;
+}
+
+// The media id inside a Wix image url (…/media/<id>/v1/… or a bare …/media/<id>). Compare two urls of
+// the SAME image that differ only in sizing/format params by their id, not full-string equality.
+export function wixMediaId(url) {
+  const m = typeof url === "string" && url.match(/\/media\/([^/?]+)/);
+  return m ? m[1] : url;
+}
+
+// The image assigned to a product OPTION CHOICE (e.g. a colour swatch). The storefront fetches with the
+// PRODUCT_CHOICES_MEDIA_REFERENCES field, so Wix returns the choice image at choice.media.items[].mediaId
+// and returns choice.linkedMedia EMPTY. Read media.items — do NOT switch this to choice.linkedMedia even
+// if a direct admin/API probe shows linkedMedia populated: a probe made WITHOUT that field mask returns
+// linkedMedia, but the storefront requests the mask, which blanks linkedMedia and returns media.items.
+export function choiceImage(choice) {
+  const mediaId = choice?.media?.items?.[0]?.mediaId;
+  return mediaId ? wixMediaUrl(mediaId) : null;
+}
+
+// The image for a resolved VARIANT (a full choice combination). Wix computes variant.media from the
+// picked choices' media, so this is the exact image for the current selection — prefer it over a
+// single choice's image once all options are chosen.
+// ⚠️ Read `media.image.url` (the URL the API already returns), or build from `media.id` — the
+// `~mv2` file id. NOT `media.uploadId`: that's a dashed GUID (the id the file was uploaded with),
+// and https://static.wixstatic.com/media/<uploadId> is a 403. Variants without media (a fresh
+// template's demo products) return null, and the caller falls back to the choice's own image.
+export function variantImage(variant) {
+  const m = variant?.media;
+  if (!m) return null;
+  return storeImage(m.image?.url) || wixMediaUrl(m.id) || storeImage(m.thumbnail?.url);
+}
+
 // The main catalog image for a product (grid tiles, cart fallbacks).
 export function productImage(product) {
   return storeImage(product?.media?.main?.image?.url);

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-catalog.js

@@ -30,12 +30,13 @@ import { wixApiRequest } from "./wix-client.js";
  *   options {array} — product options e.g. Size, Color:
  *     [{ id, name, optionRenderType "TEXT_CHOICES"|"COLOR_CHOICES"|"SWATCH_CHOICES",
  *        choicesSettings.choices [{ choiceId, key, name, inStock, visible, choiceType, colorCode,
- *                                   linkedMedia }] }],
+ *                                   media }] }],
  *     A COLOR/SWATCH option's choices carry choiceType "ONE_COLOR" and colorCode "#395E55" — render
- *     those as real colour swatches, not text pills. linkedMedia [{ image.url }] holds that colour's
- *     photos, so selecting a swatch can move the gallery to the matching shot. visible false is a
- *     retired choice the merchant no longer sells: filter it out. (TEXT_CHOICES choices are
- *     choiceType "CHOICE_TEXT" with no colorCode.)
+ *     those as real colour swatches, not text pills. A choice's photo is at media.items[].mediaId (a
+ *     bare Wix media id — build https://static.wixstatic.com/media/<id>); use choiceImage() from
+ *     lib/storeImage to resolve it. Needs the PRODUCT_CHOICES_MEDIA_REFERENCES field (requested by
+ *     getProductBySlug below). visible false is a retired choice the merchant no longer sells: filter
+ *     it out. (TEXT_CHOICES choices are choiceType "CHOICE_TEXT" with no colorCode.)
  *   modifiers {array} — non-variant customizations (engraving, gift wrap):
  *     [{ id, name, mandatory, modifierRenderType "TEXT_CHOICES"|"FREE_TEXT",
  *        key, choicesSettings.choices, freeTextSettings.key }],
@@ -85,7 +86,18 @@ export async function queryProducts({ limit = 100, cursor } = {}) {
 export async function getProductBySlug(slug) {
   const res = await wixApiRequest(`/stores/v3/products/slug/${encodeURIComponent(slug)}`, {
     method: "GET",
-    query: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"] },
+    // PRODUCT_CHOICES_MEDIA_REFERENCES → choice.media.items[].mediaId (the per-colour photos, needed
+    // for the swatch→gallery swap); VARIANT_OPTION_CHOICE_NAMES → variant choice names. Without these
+    // the choice media / variant data come back null.
+    query: {
+      fields: [
+        "CURRENCY",
+        "PLAIN_DESCRIPTION",
+        "MEDIA_ITEMS_INFO",
+        "PRODUCT_CHOICES_MEDIA_REFERENCES",
+        "VARIANT_OPTION_CHOICE_NAMES",
+      ],
+    },
   });
   return res?.product ?? null;
 }

package/skills/wix-vibe-headless/references/storefront/seed/SEED.md

@@ -4,6 +4,10 @@ Seed a Wix Stores catalog by **calling `seed-store.js`** — don't hand-write th
 a build-time module (run via `exec_tool`, not shipped in the app) that abstracts every Wix Stores
 seed operation. Load it and call **`setupStore` — the one-call path** — with plain data.
 
+**Match each product's type to what the buyer receives** (the example shows both). *Access* — a
+membership, or an online course/program the buyer enrolls in — isn't a store product at all; that's
+the `pricing-plans` vertical, not here.
+
 ```js
 // build-time exec_tool
 const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
@@ -22,12 +26,15 @@ const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
 // generate_image runs in the background while you build, so the urls are ready by seed time.
 const result = await seed.setupStore(ctx, {
   products: [
+    // physical — a shipped item: carries `quantity` (the default type)
     { name: "The Glam Rocker", description: "Sequin-studded velvet legend…", price: 49.99, quantity: 12, imageUrl: imageUrls[0] },
     // a product with buyer choices — see "Options, variants and sale prices" below
     { name: "The Understudy", description: "…", price: 245, quantity: 8, imageUrl: imageUrls[1],
       options: [{ name: "Color", type: "color", choices: [{ name: "Ink", colorCode: "#1B1B2F" }, { name: "Bone", colorCode: "#EDE6D6" }] }] },
     // a product on sale — compareAtPrice drives the strikethrough + the tile's percent-off badge
     { name: "Encore Jacket", description: "…", price: 68, compareAtPrice: 129, quantity: 5, imageUrl: imageUrls[2] },
+    // digital — a file the buyer downloads & keeps (ebook, PDF, video): `digitalFileUrl`, NO `quantity`
+    { name: "Backstage Guide", description: "…", price: 12, digitalFileUrl: "https://…/guide.pdf" },
   ],
   categories: { "Legends": ["The Glam Rocker"], "Rising Stars": [] },   // omit if the brief names none
 });
@@ -37,13 +44,15 @@ const result = await seed.setupStore(ctx, {
 **Seeding is additive — never delete or overwrite existing content.** Don't clean up, don't remove
 "sample" data, don't reset. Just add.
 
-## Options, variants and sale prices
+## How many, and exercising the UI
+
+**Default to 3 products** unless the brief asks for a specific catalog — the seed shows the shape,
+not a full inventory; the owner adds the rest later, from the Wix dashboard or by asking you for more.
 
 The shipped storefront renders colour options as real swatches, shows a size/colour summary on each
 tile, and puts a percent-off badge on a discounted product. A catalog of plain single-price products
-leaves all of that invisible, so **seed a catalog that exercises it**: unless the brief says
-otherwise, give at least one product a colour option and put one product on sale. Keep it truthful
-to the business — a ceramics studio has glaze colours, a bakery does not.
+leaves all of that invisible, so **make those 3 exercise it**: unless the brief says otherwise, give
+at least one product a colour option and put one product on sale. Keep it truthful to the business.
 
 ```js
 options: [
@@ -60,13 +69,27 @@ options: [
 - `compareAtPrice` (> `price`) is the "was" price: strikethrough on the PDP and a `−N%` badge on the
   tile, computed from the two amounts. It works with or without options.
 
+## Digital downloads
+
+**Pick the product type from what the buyer receives.** A shipped physical item is the default. A
+**downloadable file the buyer keeps** — ebook, PDF guide, template, preset pack, printable, music
+track, downloadable video — is a **digital** product: pass its file as `digitalFileUrl`. Selling
+*access* rather than a file — a membership, subscription, or an online course/program the buyer
+enrolls in — is **Pricing Plans**, not a Stores product, so it isn't seeded here.
+
+`digitalFileUrl` (plus `digitalFileName` when the url carries no filename) makes a product a digital
+download — uploaded and created with both the file and stock, which is what the cart requires
+(`quantity` is ignored). It's also the only way in: a file-less digital product is created
+successfully, reads back healthy, and is then rejected at add-to-cart as `ITEM_NOT_FOUND_IN_CATALOG`.
+
 Two things this module does **not** seed, so don't try:
 
 - **Ribbons** ("New", "Best Seller"). The tile renders `product.ribbon` when it's there, but ribbons
   are set in the Wix dashboard — tell the merchant that's where to add them.
-- **Per-choice linked media** (`linkedMedia`), which is what makes picking a colour swap the gallery
-  photo. Seeded swatches select and price correctly; the gallery just doesn't follow the colour until
-  the merchant links photos to choices in the dashboard.
+- **Per-choice media** — the photo that makes picking a choice swap the gallery image. Seeded swatches
+  select and price correctly; the gallery follows a choice once photos are linked to it (Wix dashboard,
+  or the wix-manage "Update Product with Options" recipe → Choice & variant fields). The shipped PDP then
+  follows automatically — `choiceImage()` reads it back at `media.items[].mediaId`.
 
 ## Escape hatch — individual functions
 Reach for the functions below only when the one-call `setupStore` doesn't fit (partial re-seed, custom