skills/wix-headless-templates/storefront/INSTRUCTIONS.md

# Storefront — playbook

The commerce machinery ships as files — data layer, hooks, cart, checkout, SEO plumbing,
typed end-to-end. **The presentation doesn't ship — you build it** on the shipped hooks/DTOs:
the shop, category, and product (PDP) pages with their islands, the home page, and the brand.
The skeletons below carry each page's contract — including the SSR and SEO machinery, which must
be exact. You never write commerce code; you never skip designing the store.

## The file map (deployed into `src/`)

**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` | `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`, `SubscriptionPlan`) — contracts inlined below |
| `wix/storefront/catalog.ts` | `searchCatalog` (sort/filter/facets/search + cursor paging + result count, all server-side), `fetchFacets` / `fetchFacetData` (from search aggregations — the whole catalog, not a sample), `fetchProducts`, `fetchProductsByCategory`, `fetchProductBySlug`, `fetchCategories`, `fetchCategoryBySlug`, `fetchAllProductsCategoryId`, `fetchInventory` (stock left / pre-order per variant), `fetchBackInStockEnabled` + `requestBackInStock` (notify me), `resolveVariant`, `choiceAvailability` — 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 (add / quantity / remove / coupon / note / checkout; totals from the cart estimate) + 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` | 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 (lines with struck discounted prices and stock caps, promo code, note to seller, the totals breakdown, checkout) — **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 facet — an option or a choice modifier — 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 or a subscription plan — **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, choices unavailable with the current picks disabled), choice and text modifiers (with the merchant's character limit), the plan picker of a subscription product, an optional quantity stepper capped at the stock left ("Only N left"), the buy button gated by `useProductDetail` with its plain reason, "Pre-order" with the merchant's note when pre-orderable, "notify me" when sold out and the merchant collects requests — **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 |

Astro stack additionally gets:

| file | what it is |
|---|---|
| `layouts/SiteLayout.astro` | the site chrome — **yours to brand**: header, footer, nav. Keep the `<slot name="seo-tags" />`, the global.css import, and the CartButton/CartDrawer mounts |
| `pages/shop.astro` · `pages/category/[slug].astro` · `pages/products/[slug].astro` | **don't ship — YOU create them** (skeletons below): thin SSR pages that fetch server-side and mount your islands; the category and PDP pages carry the owner-editable SEO machinery, exactly as their skeletons show |

## What you build — this is the design job, not optional polish

You implement **three surfaces yourself** — each an SSR page plus its island, per the
skeletons below — styled with Tailwind utilities on the `@theme` tokens, designed to fit the
brief (the business, the tone, the audience — a toy brand and a jewelry house should not get
the same store):

1. **The shop page + `ShopView`** (skeletons below) — category links, the shipped
   `FilterPanel`, and your grid of your tiles: image treatment, badges, price/sale
   presentation, hover behavior, grid rhythm (columns, density, maybe an editorial featured
   tile), each tile carrying the shipped `QuickAdd`. `products === null` → skeleton tiles,
   `[]` → an honest empty state. Decompose into `ProductCard`/`ProductGrid` files if you like —
   your call, nothing prescribes it. **The category page** (`/category/[slug]`) mounts the same
   `ShopView` scoped to one category — one island, two pages.
2. **The PDP page + `ProductDetailView`** (skeletons below) — gallery, price/sale,
   description, your option-selection UI (color options = real swatches), quantity,
   add-to-cart — on `useProductDetail`, which owns ALL selection/variant logic; you own how it
   looks. This is the surface that most often looks generic — make the layout the brand's: an
   editorial split, a sticky buy column, a full-bleed gallery.
3. **The home page** — hero, featured products (fetch in frontmatter → your grid), brand story.

Plus the **theme** (edit the `@theme` block in `styles/global.css` — one edit; a dark brand is
flipped token values; add brand fonts as extra tokens) and the **chrome** (header/footer in
`SiteLayout.astro`, one edit pass; mount the shipped `CartButton` in your header).

### What a complete storefront shows (recommended defaults)

These are the recommended defaults for a store whose brief says nothing about them. They are
not requirements: when the user's prompt asks for something different — a cart page instead of a
drawer, no shop page, a particular layout or look — the prompt wins, and the item here that
conflicts with it is dropped without discussion. Look at the catalog before designing (categories,
assortment size, media, options, sales, ribbons) and design for this store, not for a stereotype
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 — 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
  shipped `QuickAdd` as the last row of every tile; each
  category reachable by a real link (`/category/<slug>`) — from the nav, the home page, or the
  shop's category row; loading, empty, no-results, and error states that look different.
- **Product page:** image, name, price, the first choice, and the buy button with `blockedReason`
  in the first screen **at 390px wide too** — on a phone the image is a bounded band
  (`max-h-[45vh]`), not a full-screen hero that pushes the price below the fold; every ribbon;
  every image reachable in the gallery; the main image follows the selection (`imageUrl` from the
  store when set, else the gallery's first); breadcrumbs (Home › the category path › the product)
  when the product has a main category.
- **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. 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.

Pre-order (`isPreorder`, the merchant's note), subscription plans (the picker), stock left, and
notify-me ship in the components and show only when the catalog has them. Product groups and
promotions are built only when the catalog has them — never fabricated; `wix-docs` has their
contracts.

### The contracts your components consume (everything you need — don't read the source)

```ts
// ProductSummary (grid tiles) — all display-ready: prices formatted, images https URLs:
// { id, slug, name, price, maxPrice, fromPrice: boolean, compareAtPrice|null,
//   discountNames: string[] /* automatic discount rule names — under the price */,
//   pricePerUnit: string|null /* "€2.50 / 100 g" as Wix formats it */,
//   ribbon|null, ribbons: string[], minPriceVariantId|null,
//   availability: "IN_STOCK"|"OUT_OF_STOCK"|"PARTIALLY_OUT_OF_STOCK", preorder: boolean,
//   hasSubscriptions: boolean, imageUrl, hoverImageUrl, optionsSummary /* "2 colors · 3 sizes" */,
//   swatches: string[] /* hex colors of a color option's choices — dots on the tile, not a picker */,
//   quickAddable: boolean }
// fromPrice → render "From {price}" (the cheapest variant is discounted and variants differ in
// price: the discounted top is only known on the PDP; maxPrice equals price then). Else
// price !== maxPrice → the product is a RANGE: render "price – maxPrice" (compareAtPrice is null
// then — never a struck price beside a range). Otherwise price is what the buyer pays (a discount
// already applied) and compareAtPrice, when present, is the labelled "was".
// ribbons = EVERY merchant ribbon, primary first — render all, one shared style; a ribbon is a
// label, never proof of a discount. The tile's buy control is the shipped <QuickAdd product={p} />:
// it reads quickAddable / minPriceVariantId / preorder / hasSubscriptions itself and routes to a
// direct add, an anchored option picker, or the product page — don't rebuild that decision in the tile.

// useShop({ initialProducts?, initialCategories?, initialCategoryId?, pageSize? /* 24 */ }) →
// { products: ProductSummary[]|null /* null = first load → skeletons; during a later change the
//   previous page stays here with loading: true — dim it, don't blank it */, total: number|null,
//   categories: Category[], activeCategoryId: string|null, setActiveCategoryId(id|null),
//   sort: keyof SORTS, setSort(sort), filters, setFilters({ minPrice?, maxPrice?, inStockOnly?, search? }),
//   facets: Facet[], priceRange: { min, max }|null, selectedChoiceIds, toggleChoice(choiceId),
//   clearFilters(), hasActiveFilters, loading, error, retry(), hasMore, loadMore(), loadingMore }
// Category = { id, slug, name, description, imageUrl /* "" when none */, parentId: string|null,
//   index /* order among siblings */, productCount: number|null, breadcrumbs: [{ id, name, slug }]
//   /* ancestors — filled by fetchCategoryBySlug only */ }.
// Facet = { id, name, kind: "option"|"modifier", isColor,
//   choices: [{ id, name, colorCode|null, count /* products carrying it */, childIds: string[] }] }.
// The shipped <FilterPanel shop={shop}>{…your grid…}</FilterPanel> renders total/sort/chips, the
// filter sidebar (md+) or sheet, and lays your results out beside it — hand it the whole hook result
// and put your grid + states inside it; don't build a second filter UI or a second sort control. Categories are LINKS (`/category/${c.slug}`) — a category page is a URL
// a shopper can share and a search engine can index; setActiveCategoryId is for a live scope
// switch on /shop, not a substitute for the links.
// Sort/filter/facets/search/paging run on Wix across the WHOLE catalog (a change restarts the list).
// Facet picks OR inside one facet and AND across facets ("Red or Blue, and Large") — the store
// groups them; you only call toggleChoice(choiceId). The price bounds bracket the product's whole
// range (its cheapest variant at least min, its dearest at most max).
// The selection is mirrored into the query string (?sort=&min=&max=&stock=1&q=&choice=…) and read
// back on load — a filtered gallery is a shareable link; nothing for you to wire.
// SORTS (exported next to useShop) is Record<sortKey, { label: string }> — the value is an
// OBJECT, so render entry.label, never the entry itself:
//   Object.entries(SORTS).map(([key, { label }]) => <option value={key}>{label}</option>)
// hasMore → render a "load more" control calling loadMore() (disabled while loadingMore).

// useProductDetail({ initial? /* SSR */, slug? /* SPA */ }) →
// { product: ProductDetail|null, notFound,
//   optionGroups: [{ id, key, name, isColor, choices: [{ choiceId, key, name, colorCode|null, imageUrl|null,
//                    inStock /* buyable WITH the other picks */, exists /* some variant has this combination */, selected }] }],
//   selectOption(optionId, choiceId),                 // by ids (option.id, choice.choiceId), never by name
//   imageUrl,                                         // the picked choice's own photo (last pick wins), else the variant's; null → keep the
//                                                     //   gallery's main image. Render it AS the main image so a colour pick swaps the photo
//   modifierValues, setModifier(key, value),          // product.modifiers: pills or a text input; "*" = mandatory;
//                                                     //   a text modifier carries title, maxChars|null, minChars|null
//   plans: [{ id, name, description, terms /* "every 2 months · 6 payments" */, price /* this variant's, "" until resolved */, selected }],
//   subscriptionPlanId, selectPlan(planId | ONE_TIME_PLAN), // only for a product with plans; product.allowOneTimePurchase → offer ONE_TIME_PLAN too
//   price, compareAtPrice, pricePerUnit,              // the RANGE ("From …" when fromPrice) until every option is picked, then the
//                                                     //   variant's price (+ labelled "was" when real), or its price on the picked plan
//   isPreorder, preorderMessage,                      // resolved variant is out of stock but pre-orderable → label the action "Pre-order", show the note
//   remaining, maxQuantity,                           // units left when counted (null otherwise); the stepper's ceiling (99999 when uncounted)
//   canAdd,                                           // gate the button; false until every option picked & in stock (or pre-orderable) & plan picked
//   blockedReason,                                    // "Choose Size" / "Out of stock" / "Add Engraving" / "Choose a plan" — render beside the
//                                                     //   button as neutral guidance (not error styling) while it's disabled; null when addable
//   quantity, setQuantity /* clamped to [1, maxQuantity] */, add(), adding, error,   // quantity resets to 1 when an option changes
//   canNotify, notify(email), notifying, notifyResult /* "created"|"already-subscribed"|null */, notifyError }
// ProductDetail adds: descriptionHtml (render as HTML), infoSections: [{ title, html }] (sections
// or accordions), gallery: string[] (urls, main first), breadcrumbs: [{ id, name, slug }] (the path
// to the main category, top-level first), categoryIds, options, modifiers, variants (each with
// choiceIds, sku, pricePerUnit, subscriptionPrices, quantity, preorderMessage), subscriptions:
// SubscriptionPlan[], allowOneTimePurchase — but selection ALWAYS goes through the hook above.

// useCart() →
// { cart: { lines, itemCount, subtotal, discount /* "" when none */, discounts: [{ name, amount }],
//   fees: [{ name, amount }], taxes: [{ name, amount }], pricesIncludeTax, total /* before shipping */,
//   coupon: { id, code }|null, note, currency }|null,
//   busy /* the DRAWER's flag: any cart operation in flight */, pendingProductId /* the product whose add
//   is in flight, else null — a card's add control disables on THIS, never on busy */, error, open,
//   // a line: { lineItemId, productName, quantity, unitPrice, linePrice, compareAtLinePrice|null,
//   //           availableQuantity|null /* the stepper's cap */, imageUrl, productUrl, descriptionLines,
//   //           status /* IN_STOCK | PARTIALLY_IN_STOCK | OUT_OF_STOCK | REMOVED_FROM_CATALOG */,
//   //           subscription /* "Monthly plan · every month · 12 payments" or "" */ }
//   addToCart(productId, variantId?, qty?, extras?), updateQuantity(lineItemId, qty),
//   removeLine(lineItemId), applyCoupon(code), removeCoupon(), setNote(text) /* on blur */,
//   checkout(), openCart(), closeCart(), refresh() }
// addToCart rejects on refusal (out of stock, digital product with no file) AND records
// .error, opening the drawer either way — so render .error in whatever surface you build for
// the cart, and never chain checkout() onto an add without awaiting it successfully. applyCoupon
// rejects with buyer copy for an unknown / expired / inapplicable code (also in .error).
```

### 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,
branches after (an early return above a hook changes hook order between renders and React
throws). The islands render on the server too (`client:load` SSRs), and by then the 200 and
headers are already sent — a render throw truncates the body mid-stream and surfaces to the
visitor as `ERR_HTTP2_PROTOCOL_ERROR`, not an error page. Render every state totally; nothing
in a render path may throw.

```astro
---
// src/pages/shop.astro — YOU create it. Products and categories are fetched SERVER-SIDE
// (SEO: view-source shows product names) and handed to the island as serialized DTO props;
// category switches then filter live on the client.
import SiteLayout from "../layouts/SiteLayout.astro";
import ShopView from "../components/storefront/ShopView";
import { fetchProducts, fetchCategories } from "../wix/storefront/catalog";
import type { Category, ProductSummary } from "../wix/storefront/types";

let products: ProductSummary[] = [];
let categories: Category[] = [];
try {
  [products, categories] = await Promise.all([fetchProducts({ limit: 24 }), fetchCategories()]);
} catch {
  // Guarded: an unhandled SSR throw truncates the response mid-stream; the island
  // renders your empty state instead.
}
---
<SiteLayout title="Shop">
  <!-- your page heading / intro, then: -->
  <ShopView client:load initialProducts={products} initialCategories={categories} />
</SiteLayout>
```

```astro
---
// src/pages/category/[slug].astro — YOU create it. A category is a Wix ITEM PAGE like a product:
// its own URL, its SEO owner-editable in the dashboard, registered in the sitemap. Same SEO
// machinery as the PDP with the CATEGORY identifiers. It mounts the SAME ShopView, scoped.
import SiteLayout from "../../layouts/SiteLayout.astro";
import ShopView from "../../components/storefront/ShopView";
import { fetchCategoryBySlug, fetchProductsByCategory, fetchCategories } from "../../wix/storefront/catalog";
import type { Category, ProductSummary } from "../../wix/storefront/types";
import { WIX_APPS } from "@wix/essentials";
import { SEO } from "@wix/seo/components";
import { loadSEOTagsServiceConfig } from "@wix/seo/services";
import { seoTags } from "@wix/seo";

export const wixMetadata = {
  appDefId: WIX_APPS.checkoutAndOrders.id,
  pageIdentifier: WIX_APPS.checkoutAndOrders.categoryPageMetadata.pageIdentifier,
  identifiers: { slug: WIX_APPS.checkoutAndOrders.categoryPageMetadata.identifiers.handle },
};

const slug = Astro.params.slug!;
const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
const pageUrl =
  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
    ? forwardedUrl
    : Astro.url.href;

let category: Category | null = null;
let products: ProductSummary[] = [];
let categories: Category[] = [];
let seoTagsServiceConfig = null;
try {
  category = await fetchCategoryBySlug(slug);
  if (category) {
    // A sub-category is its own SEO item type (the owner's settings differ per type).
    const itemType = category.parentId ? seoTags.ItemType.STORES_SUB_CATEGORY : seoTags.ItemType.STORES_CATEGORY;
    [products, categories, seoTagsServiceConfig] = await Promise.all([
      fetchProductsByCategory(category.id, { limit: 24 }),
      fetchCategories(),
      loadSEOTagsServiceConfig({ pageUrl, itemType, itemData: { slug } }),
    ]);
  }
} catch {
  // Guarded: an unhandled SSR throw truncates the response mid-stream.
}

// A missing or hidden category is a real 404 — never a fallback to all products.
if (!category) {
  return new Response(null, { status: 404 });
}
---
<SiteLayout title={category.name}>
  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
  <!-- your heading: category.breadcrumbs as links (Home › each ancestor → `/category/${b.slug}`) when
       it has any, category.name, category.description when present, category.imageUrl as a banner
       when it fits the design, then: -->
  <ShopView client:load initialProducts={products} initialCategories={categories} initialCategoryId={category.id} />
</SiteLayout>
```

```astro
---
// src/pages/products/[slug].astro — YOU create it. This is a Wix ITEM PAGE: the wixMetadata
// export + <SEO.Tags> are what let the site owner edit this page's title/description/OG in
// the dashboard and register the route in the sitemap. All three SEO pieces are REQUIRED,
// exactly as here.
import SiteLayout from "../../layouts/SiteLayout.astro";
import ProductDetailView from "../../components/storefront/ProductDetailView";
import { fetchProductBySlug } from "../../wix/storefront/catalog";
import { WIX_APPS } from "@wix/essentials";
import { SEO } from "@wix/seo/components";
import { loadSEOTagsServiceConfig } from "@wix/seo/services";
import { seoTags } from "@wix/seo";

export const wixMetadata = {
  appDefId: WIX_APPS.checkoutAndOrders.id,
  pageIdentifier: WIX_APPS.checkoutAndOrders.productPageMetadata.pageIdentifier,
  identifiers: { slug: WIX_APPS.checkoutAndOrders.productPageMetadata.identifiers.handle },
};

const slug = Astro.params.slug!;

// Behind Wix's proxy the request URL is the internal one — the real public page URL arrives
// on x-wix-forwarded-url, and the SEO service needs the public one.
const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
const pageUrl =
  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
    ? forwardedUrl
    : Astro.url.href;

let product = null;
let seoTagsServiceConfig = null;
try {
  [product, seoTagsServiceConfig] = await Promise.all([
    fetchProductBySlug(slug),
    loadSEOTagsServiceConfig({
      pageUrl,
      itemType: seoTags.ItemType.STORES_PRODUCT,
      itemData: { slug },
    }),
  ]);
} catch {
  // Guarded: an unhandled SSR throw truncates the response mid-stream.
}

if (!product) {
  return new Response(null, { status: 404 });
}
---
<SiteLayout title={product.name}>
  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
  <ProductDetailView client:load initial={product} />
</SiteLayout>
```

```tsx
// src/components/storefront/ShopView.tsx — YOU build it; shop.astro AND category/[slug].astro mount it.
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: {
  initialProducts?: ProductSummary[];   // SSR props from your page — pass straight to useShop;
  initialCategories?: Category[];       // omitted in a SPA (client fetch)
  initialCategoryId?: string | null;    // the category page passes its category's id
}) {
  const shop = useShop(props);
  const { products, categories, activeCategoryId, loading, error } = shop;
  // …you implement the render:
  //   • a category row when categories.length > 1: LINKS to `/category/${c.slug}` (plus "All" →
  //     /shop), the active one marked by activeCategoryId — real URLs, not only pills that
  //     swap state (setActiveCategoryId is fine for an additional live switch on /shop).
  //     Categories carry parentId / index: on /shop show the top-level ones (parentId === null);
  //     on a category page show its children when it has any (plus "Shop all" = itself), else
  //     its siblings — sorted by index, then name
  //   • <FilterPanel shop={shop}> … </FilterPanel> WRAPS your results — shipped: the toolbar
  //     (result count, sort), active chips, a filter sidebar on md+ (price slider, availability,
  //     the option facets, collapsible) beside your grid, a sheet under md. Your loading / empty /
  //     error states and your grid go inside it as children. Always mounted; it shows only the
  //     facets this catalog actually has. No sort control or filter UI of your own.
  //   • error → a short inline message (retry() re-runs the query)
  //   • products === null → skeleton tiles; loading with products present (a sort or filter
  //     change) → keep the grid and dim it (opacity, aria-busy), never blank it; [] → 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 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 — "From {price}" when fromPrice, else a range when
  //     price !== maxPrice, else price + labelled compareAtPrice; discountNames under the price
  //     when present ("Summer sale"), pricePerUnit beside it when present — 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.
  //     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 — 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)
}
```

```tsx
// 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: {
  initial?: ProductDetail | null;   // SSR (Astro); a SPA passes { slug } instead
  slug?: string;
}) {
  const d = useProductDetail(props);   // full contract above — selection lives HERE
  // …you implement the render. Handle in order:
  //   d.notFound  → a "doesn't exist (anymore)" message
  //   !d.product  → a loading placeholder
  //   else the product view, laid out for the brand:
  //     • gallery from d.product.gallery (urls, main first): show ONE primary
  //       image at full size, and the rest as a small thumbnail strip (or a
  //       scrollable row) that swaps the primary — never map the whole gallery
  //       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.
  //     • breadcrumbs when d.product.breadcrumbs.length: a <nav aria-label="Breadcrumb"> of
  //       Home › each crumb as a link to `/category/${crumb.slug}` › the product name (plain text)
  //     • name, EVERY ribbon (d.product.ribbons), live d.price (the range until every option
  //       is picked; the plan's price once a plan is picked) with d.compareAtPrice as a labelled
  //       "was" when present — never invent one; d.pricePerUnit beside the price when present;
  //       d.product.discountNames under it ("Summer sale") when present;
  //       descriptionHtml rendered as HTML, then d.product.infoSections as sections/accordions
  //     • <OptionPicker detail={d} showQuantity /> right under the price — the shipped option
  //       groups (swatches for a color option, choices unavailable with the current picks
  //       disabled), modifiers, the plan picker when d.plans.length, quantity capped at the stock
  //       left, "Only N left", the buy button gated by the hook with its plain reason, "Pre-order"
  //       and the merchant's pre-order note when it applies, "notify me" when sold out and the
  //       merchant collects requests, 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
  //       column `max-h-[45vh] md:max-h-none` with `object-contain`, thumbnails as a row under
  //       it, and the two-column split only from md (`md:grid md:grid-cols-2`); description and
  //       infoSections come AFTER the buy button, never between the price and the action.
}
```

### 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, choices unavailable with the current picks disabled, text modifiers with their limit,
   the plan picker, quantity capped at the stock left, the gated button with its reason, the
   "Pre-order" label and note, the notify-me form; 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 — plus the cart's contents: struck discounted
   lines, per-status copy, the stock cap on "+", promo code, note to seller (saved on blur), the
   totals breakdown (subtotal, discounts, fees, taxes unless prices include them, total).
4. `components/storefront/FilterPanel.tsx` — inline commits at once, the sheet stages until Apply;
   the price pair commits only when valid.

All under `templates/storefront/app/`.

### Wiring — Astro (default)

1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass).
2. Create the shop, category, and PDP pages and their islands per the skeletons above —
   frontmatter machinery exact, presentation yours. Primary-content islands mount `client:load` with the
   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`, `fetchInventory`, `fetchBackInStockEnabled`,
`requestBackInStock`, `resolveVariant`, `choiceAvailability` from `./js/wix/catalog.js`;
`fetchCart`, `addToCart`, `updateQuantity`, `removeLine`, `applyCoupon`, `removeCoupon`, `setNote`,
`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`, `selectPlan`, `maxQuantity`, `add()`,
`notify()`), and `./js/wix/cart-store.js` (the cart, `subscribeCart`/`getCartState`, `addLine`,
`updateLineQuantity`, `removeCartLine`, `applyCartCoupon`, `removeCartCoupon`, `setCartNote`,
`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
config plugins — deploy already added the dep). Write route wrappers in the project's router:
`/shop` → your shop component; `/category/:slug` → the same shop component with
`initialCategoryId` resolved from `fetchCategoryBySlug(slug)` (null → your 404 view);
`/products/:slug` → your detail component (`useProductDetail({ slug })` — components fetch
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. 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.
- 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
  inferred from `compareAtPrice`, no struck price beside a range (the DTO already withholds it);
  a `fromPrice` summary reads "From {price}", never a made-up top of the range.
- **Cart totals come from `cart`** (`subtotal`, `discounts`, `fees`, `taxes`, `total` — the
  estimate's) — never summed or hardcoded in the client; shipping says "calculated at checkout",
  tax too unless `cart.taxes` has rows or `cart.pricesIncludeTax` (the drawer already does).
- Your PDP page carries the SEO pieces (`wixMetadata` + `loadSEOTagsServiceConfig` +
  `<SEO.Tags>`) exactly as the skeleton shows — owners edit those tags in their dashboard.
- **Browsing, cart and checkout need no login.** They run on the Wix visitor session the
  shipped SDK client already holds. Don't gate the shop, the PDP or the cart behind sign-in,
  and don't add a members/auth flow unless the brief actually asks for accounts.
- **Call every hook before any conditional return.** A PDP that returns early for
  `notFound`/loading above its `useState`/`useEffect` changes hook order between renders and
  React throws. Hooks first, branches after.
- **Sort and filter at the source, not on a loaded page.** `useShop`'s sort/filters/search and
  `searchCatalog` run on Wix across the whole catalog before cursor paging; re-ordering the
  array a hook already returned only sorts the slice you happen to have. Never sort/filter
  client-side, and never raise the page limit instead of paging (`hasMore`/`loadMore`).

## Point the user to their dashboard

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` |
| Accept payments — connect a payment method | `wix-cashier/payments` |
| Upgrade the plan — online payments need premium | full URL: `https://www.wix.com/upgrade/website?metaSiteId={siteId}` |

Real payments need a connected payment method **and** a premium plan. Until both are done, a visitor who reaches hosted checkout sees **"We can't accept online payments. Contact us for help with your order."**
Hand both links above in the close; 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 — and, when the
brief wants them, a ribbon, a modifier (choices or free text), an info section, a pre-order item,
per-variant prices, a category description/image: all plain plan fields (see `seed/SEED.md`).

A fresh Stores install carries Wix's sample catalog (a dozen products such as "Baseball Cap" and
"Ceramic Flower Vase"), and the shop lists them next to the seeded ones. Never delete them, or
anything else on the site: the result's `preexisting[]` names what the shop lists, and the closing
message says so with the Manage products link so the owner removes them there — never release a store
that sells "Baseball Cap" without telling the owner.