@wix/agent-skills 1.20.0 → 1.21.0

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

@@ -8,25 +8,31 @@ be exact. You never write commerce code; you never skip designing the store.
 
 ## The file map (deployed into `src/`)
 
-**Don't read the shipped files** — this table and the contracts below are everything you
-need. Open a shipped file's source **only** on a real fallback: a runtime error, or a field
-this playbook doesn't cover. Files you edit: `SiteLayout.astro` and `styles/global.css`.
+**On Astro and React the shipped files are tested and work as they are** — this table and the
+contracts below are everything you need to use them, so don't spend the run reading their source;
+wire them and build your surfaces. Reading them is the right move when something is off (a runtime
+error, a field this playbook doesn't cover) or when the brief wants a behaviour they don't offer —
+then read the file that owns it and change or extend it. On `lib`, `static`, and a port the
+components don't deploy at all, and each wiring section below opens with the files to read before
+writing their equivalents. Files you edit: `SiteLayout.astro` and `styles/global.css`.
 Files you **create** (skeletons below): the shop, category, and PDP pages with their island
 components, plus your home page.
 
 | file | what it is |
 |---|---|
 | `wix/config.ts` · `wix/sdk.ts` | shared auth seam (deploy configures it — nothing to set by hand) |
-| `wix/media.ts` · `wix/money.ts` | `imgSrc()` / `imgSrcSet()` / `formatMoney()` — already used by everything shipped; `imgSrcSet` + `sizes` for responsive tiles |
+| `wix/media.ts` · `wix/money.ts` | `imgAttrs(url, sizes)` — every `<img>` attribute for a DTO image (`src`, `srcSet`, `sizes`, lazy): `<img {...imgAttrs(p.imageUrl, "25vw")} alt={p.name} />`; `imgSrc()` / `imgSrcSet()` / `formatMoney()` underneath, already used by everything shipped |
 | `wix/storefront/types.ts` | the DTOs (`ProductSummary`, `ProductDetail`, `Cart`, `Category`, `Facet`) — contracts inlined below |
-| `wix/storefront/catalog.ts` | `searchCatalog` (sort/filter/facets/search + cursor paging + result count, all server-side), `fetchFacets`, `fetchProducts`, `fetchProductsByCategory`, `fetchProductBySlug`, `fetchCategories`, `fetchCategoryBySlug`, `resolveVariant` |
+| `wix/storefront/catalog.ts` | `searchCatalog` (sort/filter/facets/search + cursor paging + result count, all server-side), `fetchFacets`, `fetchProducts`, `fetchProductsByCategory`, `fetchProductBySlug`, `fetchCategories`, `fetchCategoryBySlug`, `resolveVariant` — the transport; the rules and DTO mappers are in `catalog-core.ts` / `cart-core.ts` beside it (shared with the REST layer) |
 | `wix/storefront/cart.ts` · `cart-store.ts` | Cart V2 + shared cart state (module store — spans Astro islands) |
+| `wix/storefront/shop-store.ts` · `product-detail-store.ts` | the listing and product-detail state machines, framework-free (`createShopStore()`, `createProductDetailStore()` — `getState`/`subscribe` + actions, one instance per surface); the hooks below bind them to React, every other stack uses them directly |
 | `hooks/storefront/useCart.ts` | cart state + actions — contract below |
-| `hooks/storefront/useShop.ts` | listing: category scope, sort, filters, option facets, result count, paging — contract below |
-| `hooks/storefront/useProductDetail.ts` | option selection → variant resolution → add-to-cart — contract below |
+| `hooks/storefront/useShop.ts` | React binding of `shop-store.ts`: category scope, sort, filters, option facets, result count, paging — contract below |
+| `hooks/storefront/useProductDetail.ts` | React binding of `product-detail-store.ts`: option selection → variant resolution → add-to-cart — contract below |
 | `components/storefront/CartButton.tsx` · `CartDrawer.tsx` | header badge + slide-over cart — **wire as-is** (drawer once per page) |
 | `components/storefront/FilterPanel.tsx` | the gallery's filter LAYOUT — toolbar (result count, sort), active chips, then a 16rem sidebar of collapsible groups (price as a two-handle slider bounded by the catalog's real prices, availability, one group per option facet with swatches/pills) beside YOUR results; a bottom sheet under `md` — **wire as-is** in your `ShopView`, your grid as its children: `<FilterPanel shop={shop}>…grid…</FilterPanel>` |
 | `components/storefront/QuickAdd.tsx` | the tile's purchase control — one click for a product with no options, a picker anchored to the tile (bottom sheet on small screens) for one with options, the product page for free-text customization — **wire as-is** as the last row of every tile's text block (`<QuickAdd product={p} />`) |
+| `components/storefront/OptionPicker.tsx` | the purchase controls for one product — option groups (swatches/pills, sold-out choices disabled), choice and text modifiers, an optional quantity stepper, the buy button gated by `useProductDetail` with its plain reason, "Pre-order" when pre-orderable — **wire as-is** in your PDP (`<OptionPicker detail={d} showQuantity />`); QuickAdd's picker is this same component |
 | `components/storefront/ShopView.tsx` · `ProductDetailView.tsx` | **don't ship — YOU create them** (skeletons below): the client islands your shop, category, and PDP pages mount |
 | `styles/global.css` | **the design system**: Tailwind v4 + the `@theme` token block (colors, radii, fonts — same token family as the official Wix templates). Everything, shipped and yours, styles from these tokens |
 
@@ -74,7 +80,9 @@ of its category. Then, by default:
 - **Home:** what the store sells and one shopping action in the first screen; real products under
   truthful headings ("Best Sellers" needs data behind it); not a repeat of the shop page. A
   category tile or link on the home page goes to that category's page (`/category/<slug>`) —
-  never to an anchor on the shop page that every tile shares.
+  never to an anchor on the shop page that every tile shares — and its image is a product from
+  THAT category (fetched with the category filter) or the category's own image, never a
+  positional guess into the all-products list.
 - **Shop:** a real product card — image, name, price, link — in the first screen; the shipped
   `FilterPanel` around the grid (toolbar, then a filter sidebar beside the results on desktop and
   a sheet on phones) — a store with any filterable catalog ships it, not "when it fits"; the
@@ -88,7 +96,12 @@ of its category. Then, by default:
 - **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 (a fixed
   panel inside the `backdrop-blur` header gets clipped), lock background scroll, close on Escape,
-  return focus on close — as the shipped `CartDrawer` does.
+  return focus on close — as the shipped `CartDrawer` does. An anchored picker is positioned
+  inside its tile, not `fixed` with computed offsets. If you add dismiss-on-outside-click, decide
+  inside/outside before anything re-renders (a capture-phase listener), or a click on a swatch
+  that re-renders the panel reads as "outside" and closes it.
+- **A page whose slug resolves to nothing** (category, product) shows only the not-found state —
+  no heading, toolbar, or empty grid rendered around it.
 - **Copy:** nothing the merchant didn't supply — no invented reviews, scarcity, or delivery
   promises; no Wix IDs or technical words in visible text.
 
@@ -160,6 +173,10 @@ only when the catalog has them — never fabricated; `wix-docs` has their contra
 
 ### The pages and islands you create — skeletons
 
+The class names in these skeletons are the Astro/React spelling of layout rules that hold on
+every stack, and each rule is also named in words beside its classes. On a stack where the shipped
+components don't deploy (`lib`, `static`, a port), keep the rule and write it in your own CSS.
+
 Nothing renders until you write these — the store IS your work. Each page is a thin SSR shell
 (fetch → DTO props → island); each island is a thin view over a hook. The pages' frontmatter
 is **machinery, not design** — reproduce it as the skeletons show, exactly. Hooks first,
@@ -308,6 +325,7 @@ if (!product) {
 import { useShop } from "../../hooks/storefront/useShop";
 import FilterPanel from "./FilterPanel";
 import QuickAdd from "./QuickAdd";
+import { imgAttrs } from "../../wix/media";
 import type { Category, ProductSummary } from "../../wix/storefront/types";
 
 export default function ShopView(props: {
@@ -329,23 +347,37 @@ export default function ShopView(props: {
   //   • error → a short inline message (retry() re-runs the query)
   //   • products === null (or loading) → skeleton tiles; [] → your honest empty state, and a
   //     distinct "no products match these filters" with clearFilters() when hasActiveFilters
-  //   • else YOUR grid of YOUR tiles (ProductSummary contract above): image (hoverImageUrl on
-  //     hover; imgSrcSet + sizes for responsive delivery), name, price — a range when
+  //   • else YOUR grid of YOUR tiles (ProductSummary contract above): image via
+  //     <img {...imgAttrs(p.imageUrl, "(min-width: 768px) 25vw, 50vw")} alt={p.name} /> — src,
+  //     srcSet, sizes and lazy loading in one spread, so a tile never ships srcSet without src;
+  //     an empty imageUrl gives {} — render your placeholder then; hoverImageUrl
+  //     on hover — name, price — a range when
   //     price !== maxPrice, else price + labelled compareAtPrice — EVERY ribbon from ribbons,
   //     swatches as small color dots when present (else optionsSummary as text); tile links to
   //     `/products/${p.slug}`; and <QuickAdd product={p} /> as the LAST ROW of the tile's text
   //     block, under name and price, full width — the shipped buy control (direct add / option
   //     picker / product page, decided from the product). It is a direct child of the tile root,
   //     which carries `relative`: the picker anchors to that root and takes the tile's width.
-  //     Never overlay the control on the image or float it between image and text, and never
-  //     wrap it in a smaller positioned box (the picker would inherit that box's width).
+  //     THE TILE ROOT IS A <div className="relative flex flex-col">, NOT THE LINK: the <a> wraps
+  //     the image and the name/price, and <QuickAdd> sits beside it as the flex column's last child
+  //     (it pins itself to the bottom with mt-auto). A button inside an <a> is invalid HTML and its
+  //     click navigates to the product page instead of adding.
+  //   • ROW RHYTHM: the grid stretches every tile in a row to the tallest; with the tile a flex
+  //     column and the control pinned to the bottom, the buy buttons share one baseline across the
+  //     row even when one tile has swatches, a struck price, or a two-line name and its neighbours
+  //     don't. Put the swatches between price and control; never let them push only that tile's
+  //     button down. Never overlay the control on the image or float it
+  //     between image and text, and never wrap it in a smaller positioned box (the picker would
+  //     inherit that box's width).
+  //   • the name WRAPS (`min-w-0`, `break-words`) — no `truncate` / `line-clamp-1`: a shopper reads
+  //     "Red Velvet Cupcake 4-Pack", not "Red Velvet Cupc…"; price on its own line under it.
   //   • badges come ONLY from p.ribbons. Do NOT render a "Sale" badge because compareAtPrice
   //     is set — the struck price already says it, and a product the merchant ribboned "Sale"
   //     would show the badge twice.
-  //   • name and price on SEPARATE lines (`min-w-0`, the name may wrap) — never one flex row
-  //     where a long name and a price range fight for width and the price gets clipped at 390px.
-  //     Keep the page intro short enough that a full tile (image, name, price) is in the first
-  //     screen, also on a short desktop window.
+  //   • name and price on SEPARATE lines — never one flex row where a long name and a price
+  //     range fight for width and the price gets clipped at 390px. Keep the page intro short
+  //     enough that a full tile (image, name, price) is in the first screen, also on a short
+  //     desktop window.
   //   • hasMore → your "load more" control calling loadMore() (disabled while loadingMore)
 }
 ```
@@ -354,6 +386,7 @@ export default function ShopView(props: {
 // src/components/storefront/ProductDetailView.tsx — YOU build the whole PDP surface;
 // your [slug].astro mounts it with the server-fetched product.
 import { useProductDetail } from "../../hooks/storefront/useProductDetail";
+import OptionPicker from "./OptionPicker";
 import type { ProductDetail } from "../../wix/storefront/types";
 
 export default function ProductDetailView(props: {
@@ -371,16 +404,15 @@ export default function ProductDetailView(props: {
   //       to full-width images stacked down the column (products with per-color
   //       linked media carry several gallery urls, so that stacks big duplicates).
   //       A single-image gallery is just the one primary — no empty strip.
+  //       When d.variant resolves and carries imageUrl, that image becomes the primary (it is
+  //       one of the gallery urls) — a shopper who picks a color sees that color.
   //     • name, EVERY ribbon (d.product.ribbons), live d.price (the range until every option
   //       is picked) with d.compareAtPrice as a labelled "was" when present — never invent one;
   //       descriptionHtml rendered as HTML, then d.product.infoSections as sections/accordions
-  //     • option controls from d.optionGroups → d.selectOption(optionName, choiceName)
-  //       (isColor → real swatches via colorCode; disable out-of-stock choices);
-  //       modifiers from d.product.modifiers → d.setModifier(key, value), "*" = mandatory
-  //     • quantity (d.quantity / d.setQuantity), then the buy button gated by d.canAdd
-  //       ONLY — never resolve variants yourself — calling d.add(); label it "Pre-order" when
-  //       d.isPreorder; while disabled, render d.blockedReason beside it as neutral guidance
-  //       (not error styling); d.adding disables, d.error renders inline
+  //     • <OptionPicker detail={d} showQuantity /> right under the price — the shipped option
+  //       groups (swatches for a color option, sold-out choices disabled), modifiers, quantity,
+  //       and the buy button gated by the hook with its plain reason, "Pre-order" when it applies,
+  //       the add error inline. Never resolve variants or gate the button yourself.
   //     • in the first screen at mobile AND desktop: the image, name, price, the first choice,
   //       and the button with its reason — a shopper decides without scrolling. On a phone that
   //       means the primary image is a bounded band, not a full-height hero: e.g. the gallery
@@ -390,6 +422,31 @@ export default function ProductDetailView(props: {
 }
 ```
 
+### The reference files for stacks where the components don't deploy
+
+On `lib`, `static`, and a port, nothing under `components/` or `hooks/` arrives. The state
+machines behind the hooks do arrive — `wix/storefront/shop-store.ts`, `product-detail-store.ts`,
+`cart-store.ts` — so you never rewrite them: create a store per surface, `subscribe`, render from
+`getState()`, call its actions. Their `*State` interfaces are the render contract; read those.
+What you write is the rendering — grid, product page, picker, filter panel, drawer — and for that
+read these first; they are tested code for exactly that behaviour, and rewriting them from the
+prose above is where the bugs come from:
+
+1. `components/storefront/QuickAdd.tsx` — the three purchase paths decided from the summary DTO;
+   the panel is positioned inside the tile (the tile is `relative`), a bottom sheet on small
+   screens, never `fixed` with computed offsets; it closes on Escape, the close button, a
+   successful add, or the scrim — there is NO outside-click handler (one that runs after a
+   re-render sees the clicked swatch detached and closes on every pick).
+2. `components/storefront/OptionPicker.tsx` — the purchase controls as working code: swatches vs
+   pills, sold-out choices disabled, quantity, the gated button with its reason and the
+   "Pre-order" label; the PDP and the tile picker share it.
+3. `components/storefront/CartDrawer.tsx` — the overlay contract as working code: root-level,
+   scrim, scroll lock, Escape, focus in and back.
+4. `components/storefront/FilterPanel.tsx` — inline commits at once, the sheet stages until Apply;
+   the price pair commits only when valid.
+
+All under `references/storefront/app/`.
+
 ### Wiring — Astro (default)
 
 1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass).
@@ -398,6 +455,88 @@ export default function ProductDetailView(props: {
    SSR props; browser-state widgets (cart) are `client:only="react"`.
 3. Write `pages/index.astro` (home) on `SiteLayout`.
 
+### Wiring — another JS framework (`--stack lib`: Vue, Svelte, Solid, plain Vite)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs storefront --stack lib` put the data layer in `src/wix/` and nothing else: `sdk.ts`
+(the visitor client, configured with the public client id), `media.ts`, `money.ts`, and
+`wix/storefront/` — `catalog.ts`, `cart.ts`, `types.ts`, the `*-core.ts` rules, and the three
+stores `shop-store.ts`, `product-detail-store.ts`, `cart-store.ts`. None of it is React. The
+hooks and components don't ship on this stack; the stores replace the hooks, and you write the
+components in your framework to the contracts on this page:
+
+- bind the stores with your framework's external-store primitive (Vue: `shallowRef` updated in
+  `subscribe`; Svelte: `readable(store.getState(), (set) => store.subscribe(() => set(store.getState())))`;
+  Solid: a signal set in `subscribe`). `createShopStore(options)` per listing (`start()` when
+  mounted, `stop()` when unmounted), `createProductDetailStore({ initial | slug })` per product
+  surface, the cart store as-is (module-level). State in, actions out — exactly the hooks'
+  contracts above;
+- your filter panel, quick add, and cart drawer to the contracts in "What a complete storefront
+  shows" — the shipped `FilterPanel.tsx`, `QuickAdd.tsx`, `CartDrawer.tsx` are readable as
+  behaviour specs (the overlay contract, the three purchase paths, the sidebar/sheet split).
+
+Routes `/shop`, `/category/:slug` (via `fetchCategoryBySlug`, null → your 404), `/products/:slug`;
+dev server on 4321; a static build goes through `npx @wix/cli@latest release` with
+`site.outputDirectory` pointing at the build folder, an SSR build is hosted by you. Item-page tags
+from the entity's `seoData`.
+
+### Wiring — static site (`--stack static`, no bundler)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs storefront --stack static --out site` put the REST layer in `site/js/wix/` (browser
+ESM, the `.ts` beside each `.js` for reading). Everything the visitor loads lives under `site/` —
+pages, styles, `js/` — and `wix.config.json`'s `site.outputDirectory` is `"./site"`; the project
+root (config, plan, seed output) is never the upload. Same function names and DTOs as the table
+above, so the contracts on this page hold unchanged: `searchCatalog`, `fetchFacetData`, `fetchProductBySlug`,
+`fetchCategories`, `fetchCategoryBySlug`, `resolveVariant` from `./js/wix/catalog.js`;
+`fetchCart`, `addToCart`, `updateQuantity`, `removeLine`, `checkoutUrl` from `./js/wix/cart.js`.
+The state machines ship too: `createShopStore` from `./js/wix/shop-store.js` (the listing —
+selection, facets, URL sync, cursor paging; `start()` once the page is up), `createProductDetailStore`
+from `./js/wix/product-detail-store.js` (the PDP and every quick-add picker — selections start
+empty, `resolveVariant`, `canAdd`/`blockedReason`, `add()`), and `./js/wix/cart-store.js` (the
+cart, `subscribeCart`/`getCartState`, `addLine`, `updateLineQuantity`, `removeCartLine`,
+`goToCheckout`, `setCartOpen`). No components ship — you write the rendering in plain JS: one
+render function per surface that reads `getState()`, called from `subscribe`, with the
+surface's controls calling the store's actions. The drawer opens after every add on its own;
+overlays follow the CartDrawer contract (root-level, scroll lock, Escape, focus back). Pages are
+`shop.html`, `category.html?slug=…`,
+`product.html?slug=…`. Set `document.title` and the meta description from the entity's `seoData`
+once it loads, on the product AND category pages. The visitor token persists in `localStorage` on
+its own; never mint per page. `npx @wix/cli@latest release` uploads `site/`.
+
+### Wiring — server-rendered, another language (Flask, Laravel, Rails, …)
+
+Read the reference files listed above before writing any surface.
+
+Run `deploy.mjs storefront --stack static` in the project folder anyway: `js/wix/` is both the
+browser-side code and the readable spec. Then split by where the call runs. **Reads on the
+server:** port `js/wix/catalog.ts` and `catalog-core.ts` to your language — the same six functions
+returning the same DTO shapes as dicts, one anonymous visitor token per process for these public
+reads (mint and refresh per `client.ts`) — and render shop, category, and PDP in your templates to
+the contracts above, so product names and prices are in the HTML; item-page tags from the entity's
+`seoData`. **Buying in the browser:** the cart drawer on `./js/wix/cart-store.js`, the PDP's
+option picker and the tile's quick add on `./js/wix/product-detail-store.js` (pass the product's
+slug, or the rendered `ProductDetail` as `initial` in a JSON script tag), exactly as the static
+wiring above — the browser owns the shopper's visitor token, so the server never handles
+per-shopper tokens. Routes stay `/shop`, `/category/<slug>`, `/products/<slug>`. Add your public https origin
+to the OAuth app's allowed domains before checkout can return.
+
+**Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted.** Same port for
+the reads, run at build time with one anonymous token; the generator must emit every product and
+category page (a URL generator over `fetchCategories()` plus a full `searchCatalog` walk by
+cursor — never only the first page). Run `deploy.mjs storefront --stack static --out <build dir>`
+so `js/wix/` is inside the output the pages import from, point `site.outputDirectory` at that
+folder, `wix release`. Pages sit at different depths (`/`, `/category/…`, `/products/…`): give
+the templates one base path to `js/wix/` (a template variable, or root-relative `/js/wix/…`),
+never a relative `./js/wix/` — it breaks one level down. The frozen grid is the first paint; the
+shop's sort, filters, facets, search, and load-more still run client-side on it through
+`createShopStore()` from `./js/wix/shop-store.js`, exactly as on a static site, so the gallery
+contract above applies. Close
+with the live URL, the rebuild + release command, and one line for the owner: dashboard edits to
+the catalog reach the site when that command runs; cart and checkout are live regardless.
+
 ### Wiring — React SPA (Vite etc.)
 
 Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite
@@ -409,22 +548,27 @@ client-side when no `initial` is passed).
 Mount the shipped `CartButton` in the header and `CartDrawer` once. Deploy wrote the public
 client id into `wix/config.ts`; nothing else to configure.
 
+Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1).
+
 ## Hard rules
 
 - **Data and commerce logic only through the shipped exports** — never rewrite their
   internals or re-derive a request shape. Extend by calling the exports or adding a new
   function in `wix/storefront/` for what they don't cover (API contracts: the `wix-docs` skill).
 - **Selection→cart goes through `useProductDetail`** — never add a product with options by
-  picking `variants[0]`, and never gate `canAdd` yourself. In the gallery that is the shipped
-  `QuickAdd` — a tile never adds a product with options itself, and never hides the buy path
+  picking `variants[0]`, and never gate `canAdd` yourself. On the PDP that is the shipped
+  `OptionPicker`; in the gallery the shipped `QuickAdd` — a tile never adds a product with options itself, and never hides the buy path
   behind "go to the product page" for a product that has no options.
 - **Filters are the shipped `FilterPanel`** — mounted in the gallery whenever the store has a
   catalog to filter; not rebuilt with fewer controls, not dropped because the brief didn't ask.
 - **Categories are pages** — `/category/[slug]` with its SEO block, linked from the chrome; a
   category that exists only as a state toggle on `/shop` has no URL to share or index.
 - Don't wrap shipped calls in your own API routes — they run client-side by design.
-- Theme via the `@theme` tokens; your markup uses Tailwind utilities on the same tokens. No
-  parallel theme files, no hardcoded palette values in components.
+- Where the shipped components deploy (Astro, React): theme via the `@theme` tokens, and your
+  markup uses Tailwind utilities on the same tokens — one design system across shipped and written
+  code. No parallel theme files, no hardcoded palette values in components. Where they don't
+  (`lib`, `static`, a port): style with whatever your stack does well, on one token set of your
+  own; the rule that survives is the token set, not Tailwind.
 - Checkout only through the shipped cart (`checkout()`) — never a hand-built checkout URL.
 - Live data or an honest empty state — never mock products, prices, reviews, or counts.
 - **Prices and ribbons come from the DTOs as-is** — no computed percent-off, no "Sale" badge
@@ -446,44 +590,23 @@ client id into `wix/config.ts`; nothing else to configure.
 
 ## Point the user to their dashboard
 
-Give the owner the dashboard, products, and categories links — **the deploy step's JSON
-output already printed them ready-made** (`dashboardUrl`, `productsUrl`, `categoriesUrl`);
-copy, don't re-derive. Real payments additionally need a premium plan + a connected payment
-method (dashboard) — mention it, don't treat it as a code failure.
+Hand the owner these links — `{siteId}` is `siteId` in `wix.config.json` (the deploy JSON also prints
+`dashboardUrl`, `productsUrl`, `categoriesUrl`); an entity id fills the placeholder from the seed result.
+
+| page | `https://manage.wix.com/dashboard/{siteId}/` + |
+|---|---|
+| Products | `wix-stores/products` |
+| Edit a product | `wix-stores/products/product/{productId}` |
+| Categories | `wix-stores/categories/list` |
+| Inventory | `wix-stores/inventory` |
+| Orders | `ecom-platform/orders-list` |
+| Store settings | `wix-stores/settings` |
+
+Real payments additionally need a premium plan + a connected payment method (Settings → Accept
+payments) — mention it, don't treat it as a code failure.
 
 ## Seeding
 
 Per `seed/SEED.md` — a plain-data `plan.json` into `seed-store.mjs`, run from the project
 root. Independent of the frontend work; seed a catalog that exercises the UI (≥1 product with
 a color option, ≥1 on sale, an image per product) unless the brief says otherwise.
-
-## Verify (before declaring done)
-
-- [ ] `/shop` renders live products SSR (view-source shows product names) through **your**
-      grid/card; the `FilterPanel` shows the result count, and on desktop a sidebar beside the
-      grid with the price slider and this catalog's facets (a Color option → swatches); category links lead to `/category/<slug>`, which renders scoped and
-      carries the SEO tags in view-source; an unknown slug is a 404; empty catalog shows your
-      honest empty state.
-- [ ] Shop first screen: at 1280×720 and at 390px wide, at least one full tile — image, name,
-      price — is visible without scrolling; the tile with the longest product name and a price
-      range shows the whole price at 390px, nothing clipped.
-- [ ] Tiles: the buy control sits under name and price (not over the image); a product with no
-      options adds to the cart in one click; a product with options opens the picker across the
-      full tile width (a bottom sheet at 390px wide) and adds the chosen variant; the drawer
-      opens after either.
-- [ ] Your PDP at 390px wide: image, name, price, the first option, and the buy button are all
-      visible before scrolling. Color options render as swatches, the button shows
-      `blockedReason` ("Choose Size") until every option is picked, the price is the range until then and the variant's
-      price after, a sale shows the labelled "was", a sold-out combination reads "Out of stock",
-      a pre-orderable one reads "Pre-order".
-- [ ] Cards: every ribbon renders; a multi-price product shows a range with no struck price; a
-      product with a color option shows its swatches.
-- [ ] PDP gallery: one thumbnail per distinct photo — never two selectors leading to the same image.
-- [ ] Cart: a subscription line shows its plan terms under the product name.
-- [ ] Cart: add / quantity ± / remove work; badge count is live; subtotal shows; cart survives
-      a reload (same visitor token).
-- [ ] Checkout button redirects to Wix-hosted checkout.
-- [ ] PDP view-source carries the SEO tags (Astro).
-- [ ] Shop/PDP/home are YOUR designs on the tokens; the data-layer/hook/cart files are
-      unedited.
-- [ ] Dashboard links handed to the owner.

package/skills/wix-headless-fast/references/storefront/app/components/storefront/OptionPicker.tsx

@@ -0,0 +1,95 @@
+// The purchase controls for one product — option groups (swatches for a color option, pills
+// otherwise, out-of-stock choices disabled), choice modifiers, an optional quantity stepper, and
+// the buy button gated by the hook: disabled with a plain reason ("Choose Size") until every
+// choice is made, "Pre-order" when the resolved variant is pre-orderable, the hook's error inline.
+// QuickAdd's picker and your product page mount the same component, so buying behaves the same
+// in the gallery and on the PDP. Wire as-is; style via the tokens.
+//
+//   const d = useProductDetail({ initial });            // the PDP
+//   <OptionPicker detail={d} showQuantity />
+//
+// Price, name, gallery, description, and layout stay yours — render d.price / d.compareAtPrice
+// beside this (the range until every option is picked, then the variant's price).
+import type { UseProductDetail } from "../../hooks/storefront/useProductDetail";
+
+export default function OptionPicker({
+  detail: d,
+  showQuantity = false,
+  onAdded,
+}: {
+  detail: UseProductDetail;
+  /** The PDP shows a quantity stepper; a tile picker adds one. */
+  showQuantity?: boolean;
+  /** Called after a successful add (a tile picker closes itself here). */
+  onAdded?: () => void;
+}) {
+  if (!d.product) return null;
+  return (
+    <div className="flex flex-col gap-3">
+      {d.optionGroups.map((g) => (
+        <fieldset key={g.id}>
+          <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">{g.name}</legend>
+          <div className="flex flex-wrap gap-1.5">
+            {g.choices.map((c) =>
+              g.isColor && c.colorCode ? (
+                <button key={c.choiceId} type="button" aria-label={c.name} title={c.name} aria-pressed={c.selected}
+                  disabled={!c.inStock} onClick={() => d.selectOption(g.name, c.name)}
+                  className={`h-8 w-8 rounded-full border-2 disabled:opacity-30 ${c.selected ? "border-foreground" : "border-border"}`}
+                  style={{ backgroundColor: c.colorCode }} />
+              ) : (
+                <button key={c.choiceId} type="button" aria-pressed={c.selected} disabled={!c.inStock}
+                  onClick={() => d.selectOption(g.name, c.name)}
+                  className={`rounded-full border px-3 py-1 text-sm disabled:line-through disabled:opacity-40 ${c.selected ? "border-foreground bg-foreground text-background" : "border-border"}`}>
+                  {c.name}
+                </button>
+              ),
+            )}
+          </div>
+        </fieldset>
+      ))}
+      {d.product.modifiers.filter((m) => m.type === "choices").map((m) => (
+        <fieldset key={m.key}>
+          <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            {m.name}{m.mandatory ? " *" : ""}
+          </legend>
+          <div className="flex flex-wrap gap-1.5">
+            {m.choices.map((c) => (
+              <button key={c.key} type="button" aria-pressed={d.modifierValues[m.key] === c.key}
+                onClick={() => d.setModifier(m.key, c.key)}
+                className={`rounded-full border px-3 py-1 text-sm ${d.modifierValues[m.key] === c.key ? "border-foreground bg-foreground text-background" : "border-border"}`}>
+                {c.name}
+              </button>
+            ))}
+          </div>
+        </fieldset>
+      ))}
+      {d.product.modifiers.filter((m) => m.type === "text").map((m) => (
+        <label key={m.key} className="flex flex-col gap-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+          {m.name}{m.mandatory ? " *" : ""}
+          <input type="text" value={d.modifierValues[m.key] ?? ""} onChange={(e) => d.setModifier(m.key, e.target.value)}
+            className="rounded-md border border-border bg-background px-3 py-2 text-sm normal-case tracking-normal text-foreground" />
+        </label>
+      ))}
+      <div className="flex items-stretch gap-2">
+        {showQuantity && (
+          <div className="flex items-center rounded-full border border-border">
+            <button type="button" aria-label="Decrease quantity" disabled={d.quantity <= 1} onClick={() => d.setQuantity(d.quantity - 1)}
+              className="px-3 py-2 text-sm disabled:opacity-40">−</button>
+            <span className="min-w-6 text-center text-sm tabular-nums">{d.quantity}</span>
+            <button type="button" aria-label="Increase quantity" onClick={() => d.setQuantity(d.quantity + 1)} className="px-3 py-2 text-sm">+</button>
+          </div>
+        )}
+        <button
+          type="button"
+          disabled={!d.canAdd || d.adding}
+          onClick={() => d.add().then(() => onAdded?.()).catch(() => {})}
+          className="flex-1 rounded-full bg-primary py-2.5 text-sm font-semibold text-primary-foreground disabled:opacity-50"
+        >
+          {d.adding ? "Adding…" : d.isPreorder ? "Pre-order" : "Add to cart"}
+        </button>
+      </div>
+      {d.blockedReason && !d.canAdd && <p className="text-xs text-muted-foreground">{d.blockedReason}</p>}
+      {d.error && <p className="text-xs text-red-600">{d.error}</p>}
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/storefront/app/components/storefront/QuickAdd.tsx

@@ -3,25 +3,45 @@
 //   • options / choice mods → Quick Add: a picker on the card (bottom sheet on small screens)
 //   • free-text modifier    → the product page (the gallery can't collect the text)
 // Mount as the LAST ROW of the tile's text block (under name and price), as a direct child of the
-// tile root that carries `relative` — the picker anchors to that root and takes its width. Never
-// overlay it on the image, never wrap it in a narrower positioned box.
+// tile root that carries `relative flex flex-col` — the picker anchors to that root and takes its
+// width, and the control pins itself to the tile's bottom (mt-auto) so the action row lines up
+// across a grid row whether or not a neighbour carries swatches or a struck price. Never overlay
+// it on the image, never wrap it in a narrower positioned box.
 //   <QuickAdd product={p} />   Wire as-is; style via the tokens.
 import { useEffect, useRef, useState } from "react";
 import { useCart } from "../../hooks/storefront/useCart";
 import { useProductDetail } from "../../hooks/storefront/useProductDetail";
 import type { ProductSummary } from "../../wix/storefront/types";
+import OptionPicker from "./OptionPicker";
 
 export default function QuickAdd({ product }: { product: ProductSummary }) {
+  return (
+    // A tile is often one big <a>. A click inside the buy control must never become a navigation
+    // to the product page — this boundary cancels the link's default for everything below it
+    // (the button, the picker, the sheet). Still: keep the control OUTSIDE the tile's link.
+    <div
+      className="contents"
+      onClick={(e) => {
+        e.preventDefault();
+        e.stopPropagation();
+      }}
+    >
+      <QuickAddControl product={product} />
+    </div>
+  );
+}
+
+function QuickAddControl({ product }: { product: ProductSummary }) {
   const { addToCart, busy } = useCart();
   const [open, setOpen] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
   if (product.availability === "OUT_OF_STOCK" && !product.preorder) {
-    return <span className="text-sm text-muted-foreground">Out of stock</span>;
+    return <span className="mt-auto block pt-3 text-sm text-muted-foreground">Out of stock</span>;
   }
   if (product.quickAddable) {
     return (
-      <div>
+      <div className="mt-auto pt-3">
         <button
           type="button"
           disabled={busy}
@@ -39,7 +59,7 @@ export default function QuickAdd({ product }: { product: ProductSummary }) {
   // Options to pick, or a single variant that isn't plainly in stock (pre-order, partial stock):
   // the picker resolves it through useProductDetail, exactly as the PDP would.
   return (
-    <>
+    <div className="mt-auto pt-3">
       <button
         type="button"
         onClick={() => setOpen(true)}
@@ -48,11 +68,12 @@ export default function QuickAdd({ product }: { product: ProductSummary }) {
         {product.optionsSummary ? "Choose options" : product.preorder ? "Pre-order" : "Add to cart"}
       </button>
       {open && <QuickAddPicker product={product} onClose={() => setOpen(false)} />}
-    </>
+    </div>
   );
 }
 
-// The picker fetches the full product only when it opens — cards never carry PDP data.
+// The picker fetches the full product only when it opens — cards never carry PDP data. Its controls
+// are the shipped OptionPicker, the same component the PDP mounts.
 function QuickAddPicker({ product, onClose }: { product: ProductSummary; onClose: () => void }) {
   const d = useProductDetail({ slug: product.slug });
   const panelRef = useRef<HTMLElement>(null);
@@ -108,57 +129,7 @@ function QuickAddPicker({ product, onClose }: { product: ProductSummary; onClose
           </a>
         )}
 
-        {d.product && !needsPdp && (
-          <div className="flex flex-col gap-3">
-            {d.optionGroups.map((g) => (
-              <fieldset key={g.id}>
-                <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">{g.name}</legend>
-                <div className="flex flex-wrap gap-1.5">
-                  {g.choices.map((c) =>
-                    g.isColor && c.colorCode ? (
-                      <button key={c.choiceId} type="button" aria-label={c.name} title={c.name} aria-pressed={c.selected}
-                        disabled={!c.inStock} onClick={() => d.selectOption(g.name, c.name)}
-                        className={`h-8 w-8 rounded-full border-2 disabled:opacity-30 ${c.selected ? "border-foreground" : "border-border"}`}
-                        style={{ backgroundColor: c.colorCode }} />
-                    ) : (
-                      <button key={c.choiceId} type="button" aria-pressed={c.selected} disabled={!c.inStock}
-                        onClick={() => d.selectOption(g.name, c.name)}
-                        className={`rounded-full border px-3 py-1 text-sm disabled:line-through disabled:opacity-40 ${c.selected ? "border-foreground bg-foreground text-background" : "border-border"}`}>
-                        {c.name}
-                      </button>
-                    ),
-                  )}
-                </div>
-              </fieldset>
-            ))}
-            {d.product.modifiers.filter((m) => m.type === "choices").map((m) => (
-              <fieldset key={m.key}>
-                <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
-                  {m.name}{m.mandatory ? " *" : ""}
-                </legend>
-                <div className="flex flex-wrap gap-1.5">
-                  {m.choices.map((c) => (
-                    <button key={c.key} type="button" aria-pressed={d.modifierValues[m.key] === c.key}
-                      onClick={() => d.setModifier(m.key, c.key)}
-                      className={`rounded-full border px-3 py-1 text-sm ${d.modifierValues[m.key] === c.key ? "border-foreground bg-foreground text-background" : "border-border"}`}>
-                      {c.name}
-                    </button>
-                  ))}
-                </div>
-              </fieldset>
-            ))}
-            <button
-              type="button"
-              disabled={!d.canAdd || d.adding}
-              onClick={() => d.add().then(onClose).catch(() => {})}
-              className="rounded-full bg-primary py-2.5 text-sm font-semibold text-primary-foreground disabled:opacity-50"
-            >
-              {d.adding ? "Adding…" : d.isPreorder ? "Pre-order" : "Add to cart"}
-            </button>
-            {d.blockedReason && !d.canAdd && <p className="text-xs text-muted-foreground">{d.blockedReason}</p>}
-            {d.error && <p className="text-xs text-red-600">{d.error}</p>}
-          </div>
-        )}
+        {d.product && !needsPdp && <OptionPicker detail={d} onAdded={onClose} />}
       </section>
     </>
   );