@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-headless/references/astro/stores/HOME_AND_NAV.md

@@ -1,229 +0,0 @@
-# Phase 4 Home Page + Nav — Stores
-
-Scope: `pages-home-and-nav` — dispatched as its **own serialized shell-patcher agent** in the build wave (NOT merged into the stores private-files agent, because it patches the shared shells). Imports the orchestrator-pre-copied `categories.ts` helper and the `CategoryRail`/`ProductCard` the stores private agent writes — **resolved at build time, so no write-ordering against that agent.** Patches the home page's stores-related placeholder data with live `productsV3` queries AND inserts the Shop submenu (categories list) into the persisted Navigation at the `<!-- nav:links -->` marker. (The `CartBadge` mount at `<!-- nav:actions -->` is ecom's; you own only `<!-- nav:links -->`.) Read your seeded slice from `.wix/seeded.json` (`seeded.stores`).
-
-> **You patch the shared `Navigation.astro` + `index.astro` shells**, which other packs (ecom at `nav:actions`, gift-cards, blog) also patch at their own markers. **Touch only your markers and preserve every other scope's siblings — never rewrite either file.** (Flow is the conductor's job: it serializes the shell-patching agents so concurrent marker edits don't collide — BUILD-astro.md § "Step 4.5", the serialized shell chain.)
-
-## Scope
-
-Files this agent PATCHES (does NOT rewrite):
-
-- `src/pages/index.astro` — only the stores-related sections (featured products grid, category cards)
-- `src/components/Navigation.astro` — only at the `<!-- nav:links -->` marker; insert the Shop link + categories submenu
-
-Files this agent MUST NOT touch:
-- Any other part of `index.astro` — hero, copy, newsletter, decorative ornaments are designer-owned
-- Any part of `Navigation.astro` outside the `<!-- nav:links -->` marker — designer/ecom-owned (the marker model lets multiple verticals contribute siblings without conflict)
-- `src/utils/categories.ts` — pre-copied by the orchestrator; this scope only **imports** `listStoreCategories` from it. `src/components/CategoryRail.astro`, `src/pages/category/[slug].astro` — owned by `pages-categories`
-- Any other component, page, or CSS
-- `global.css`
-
-## Inputs (from parent prompt)
-
-- **Phase 1 stores return** — `products: [{id, name, slug, ...}]`. Needed for live query on home page; also useful for deciding how many to feature.
-- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk) for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens at the call site rather than inventing semantic classes. See `references/shared/STYLING.md` for the three styling categories.
-- **Designer output summary** — path of `src/pages/index.astro` and `src/components/Navigation.astro`, with notes on what placeholder data exists.
-- **Categories (lookup)** — if the designer used category links with hardcoded slugs, call `categoriesV3` SDK to discover real category slugs and rewrite `href`s.
-
-## Critical rules
-
-1. **Surgical edits only.** Use `Edit` tool, not `Write`. Preserve everything the designer wrote — hero, copy, decorative elements, section structure, class names.
-2. **Do NOT restructure layout.** If the designer didn't include featured products, don't add it.
-3. **Do NOT mutate categories in the catalog.** Read-only. Match designer's category slugs against real ones; rewrite `href` if matched; fall back to `/products` if not.
-4. **Never improvise category endpoint URLs.** Use `categoriesV3` SDK. If the SDK isn't available, fall back to `curl` with `POST /categories/v1/categories/query` body `{"query":{}}`. Improvised `/stores/v3/categories/...` URLs cause a multi-minute stall.
-5. **If another agent already wired the home page** (e.g., a previous run), leave it alone and note this in the return.
-6. **ProductCard is a template** — always accepts `{ product }`. Pass raw SDK product objects, never flat-map. See § 1a.
-
-## When to run the home-page patch
-
-Skip the home-page patch entirely if the home page has NO stores-consuming components:
-
-- No `ProductGrid` / `ProductCard` with placeholder products array
-- No category cards with hardcoded category slugs (e.g., `/products?category=...`)
-
-If the home page is purely editorial (hero + copy + newsletter), return with `featuredProductsWired: false` — there's nothing to patch.
-
-## Implementation
-
-### 1. Home page: featured products
-
-Find the placeholder products array in `src/pages/index.astro`. Replace with a server-side `productsV3` query; pass the raw product objects to `ProductCard`.
-
-> **WRONG:** `featured = products.map(p => ({name: p.name, price: ...}))` then `<ProductCard name={p.name} .../>`
-> **RIGHT:** `featured = featuredProducts ?? []` as `any[]`, then `<ProductCard product={p} />`
->
-> Flat-mapping strips fields that ProductCard needs (`media`, `actualPriceRange`, etc.) and crashes the home page (`product` is `undefined`).
-
-```astro
----
-// src/pages/index.astro (frontmatter additions only — keep existing imports)
-import { productsV3 } from "@wix/stores";
-
-// Wrap every SSR await in try/catch — see references/shared/IMPLEMENTER.md
-// § "SSR error guards" for the full rule.
-let featured: any[] = [];
-try {
-  const { items: featuredProducts } = await productsV3
-    .queryProducts({ fields: ["CURRENCY"] })
-    .limit(4)
-    .find();
-  featured = featuredProducts ?? [];
-} catch (err) {
-  console.error("[home] featured products query failed:", err);
-}
----
-```
-
-Then pass each raw product to `ProductCard`. The ribbon is fetched inside ProductCard itself — pages don't wire offers:
-```astro
-{featured.map((p) => <ProductCard product={p} />)}
-```
-
-> **Gift-card mirror filter.** After `featured = featuredProducts ?? []`, apply the same filter the listing template uses:
-> ```ts
-> featured = featured.filter((p) => p.ribbon?.name !== "Gift Card");
-> ```
-> The Wix Gift Card app, when enabled in the dashboard, auto-creates 5 DIGITAL Stores products tagged with the "Gift Card" ribbon. They must not appear in the home featured grid for the same reason they're filtered from `/products`: buying a mirror produces a dud line item that doesn't trigger gift-card issuance, and the home teaser block (gift-cards pack) is the right surface for gift cards on the home page.
-
-Do **NOT** flat-map products into `{name, price, slug, image}` — pass the raw SDK objects. ProductCard handles its own field extraction, image resolution, and ribbon (offer) rendering internally.
-
-Preserve every other prop the designer set on the grid. If `featured` is empty (query failed, or stock cleared), the grid renders with zero cards — the rest of the page stays up.
-
-### 1a. ProductCard interface (template — deterministic)
-
-ProductCard is a **template file** (`templates/ProductCard.astro`). The `product-pages` scope copies it deterministically. The interface is:
-
-```astro
-interface Props {
-  product: { _id?: string; name?: string; slug?: string; media?: ...; actualPriceRange?: ... };
-  index?: number;
-}
-const { product, index } = Astro.props;
-```
-
-The card fetches its own discount-rule offers internally via `fetchLiveOffers()` (memoized per-request), so pages don't pass an `offers` prop. Just `<ProductCard product={p} />`.
-
-**Do NOT flat-map.** ProductCard handles image resolution, price formatting, and ribbon rendering internally.
-
-**Verification:** After writing your Edit, grep `ProductCard.astro` for `Astro.props` and confirm the prop name in your `<ProductCard .../>` JSX matches `product`.
-
-### 2. Home page: category cards (slug matching)
-
-The designer may hardcode category links like `href="/products?category=rubber"`. These rely on Stores-app categories matching those slugs. Phase 1 does NOT create categories — they're merchant-driven, so on a fresh build the only category in the catalog is the auto-managed "All Products" (which the helper filters out). Expect zero real categories on first load; the matching logic below should degrade gracefully to `/products` and re-evaluate on each request as the merchant adds categories in the dashboard.
-
-Handle this:
-
-1. **Query real categories** via `@wix/stores` `categoriesV3`:
-   ```typescript
-   import { categoriesV3 } from "@wix/stores";
-   const { items: categories } = await categoriesV3.queryCategories().find();
-   ```
-   Fall back to `curl` with `POST https://www.wixapis.com/categories/v1/categories/query` body `{"query":{}}` if the SDK module is unavailable (headers per `AUTHENTICATION.md`).
-2. **Match by name or slug** — case-insensitive substring match is fine (e.g., designer's "rubber" card matches a real category "Rubber Ducks").
-3. **If a match exists** → rewrite the `href` to use the real category slug (and optionally real category name).
-4. **If no match exists** → render the card with `/products` (no filter) rather than a dead filter URL. Keep the visual card intact.
-5. **If fewer real categories exist than cards the designer rendered** → render only matching cards. Do NOT invent categories.
-
-> Never call `/stores/v3/categories/*` — category endpoints live under `/categories/v1/`. Improvising URLs caused a documented multi-minute stall in past runs.
-
-### 3. Navigation: Shop submenu
-
-The designer scaffolds `Navigation.astro` with a `<!-- nav:links -->` marker that vertical packs replace with their primary nav contributions. Stores contributes the Shop link (always) and a hover/focus submenu listing the merchant's visible categories (when any exist — empty by default, since Phase 1 does not seed them).
-
-Import `listStoreCategories` from `src/utils/categories.ts` (already on disk — pre-copied by the orchestrator). At the marker, insert:
-
-```astro
----
-// (frontmatter additions to Navigation.astro — keep existing imports)
-import { listStoreCategories } from "../utils/categories";
-
-const navCategories = await listStoreCategories();
----
-```
-
-Then replace the `<!-- nav:links -->` marker with:
-
-```astro
-<li class={`site-nav-item${navCategories.length > 0 ? ' has-submenu' : ''}`}>
-  <a
-    href="/products"
-    class="site-nav-link"
-    data-astro-prefetch="hover"
-    aria-current={isActive('/products') || isActive('/category') ? 'page' : undefined}
-    aria-haspopup={navCategories.length > 0 ? 'true' : undefined}
-  >Shop</a>
-  {navCategories.length > 0 && (
-    <ul class="site-nav-submenu" aria-label="Shop categories">
-      <li>
-        <a href="/products" class="site-nav-sublink" data-astro-prefetch="hover">All</a>
-      </li>
-      {navCategories.map((cat) => (
-        <li>
-          <a
-            href={`/category/${cat.slug}`}
-            class="site-nav-sublink"
-            data-astro-prefetch="hover"
-            aria-current={Astro.url.pathname === `/category/${cat.slug}` ? 'page' : undefined}
-          >{cat.name}</a>
-        </li>
-      ))}
-    </ul>
-  )}
-</li>
-<!-- nav:links -->
-```
-
-Keep the marker comment immediately after the inserted `<li>` so other vertical packs (gift-cards, etc.) can still contribute siblings.
-
-> **Empty-categories fallback.** `navCategories` is `[]` by default — Phase 1 does not seed categories, and `listStoreCategories()` only returns visible, non-empty, merchant-created categories. When empty, the submenu renders nothing and the link is just `Shop` with no dropdown. The aria-haspopup attribute is conditionally added so screen readers don't promise a menu that isn't there. As soon as the merchant creates a visible category with items in the dashboard, the submenu lights up automatically (≤ 5 min, the helper's TTL).
-
-> **`isActive` is already defined** in the designer-scaffolded Navigation.astro frontmatter (it returns whether a path matches the current URL). Reuse it; do not redefine.
-
-> **`data-astro-prefetch="hover"` is required** on every category link so hovering warms the prefetch cache before the click. Designer's Layout includes `<ClientRouter />` — without prefetch, each click waits a full network round-trip.
-
-> **CSS for submenu** comes from designer's `global.css` (`.site-nav-item`, `.site-nav-submenu`, `.site-nav-sublink`, hover/focus reveals). If those classes don't exist, return `status: "partial"` with `errors: [{ code: "DESIGNER_MISSING_NAV_SUBMENU_CSS", path: "src/styles/global.css" }]`.
-
-## Return format
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-pages-home-and-nav",
-  "scope": "pages-home-and-nav",
-  "summary": "Wired home page featured products; inserted Shop submenu with N categories into Navigation",
-  "data": {
-    "homePageHadPlaceholders": true,
-    "featuredProductsWired": true,
-    "featuredProductsCount": 4,
-    "categoryCardsFound": 3,
-    "categoryCardsMatched": 2,
-    "categoryCardsFallbackToProducts": 1,
-    "navSubmenuCategoryCount": 0
-  },
-  "files": [
-    "src/pages/index.astro",
-    "src/components/Navigation.astro"
-  ],
-  "errors": []
-}
-```
-
-## Scope boundaries (reinforced)
-
-- **Do NOT edit** home page layout, copy, hero text, newsletter section, or decorative SVGs.
-- **Do NOT add** new sections the designer didn't include.
-- **Do NOT mutate** categories in the catalog — read-only.
-- **Do NOT touch** `Navigation.astro` outside the `<!-- nav:links -->` marker. Other vertical packs use the same marker model and write siblings.
-- **Do NOT touch** `CartBadge.tsx` or `CartView.tsx` — owned by ecom.
-- **Do NOT rewrite** `src/utils/categories.ts` (pre-copied by the orchestrator — import only) or `src/components/CategoryRail.astro` (owned by `pages-categories`).
-- If home page already has a live query (another agent wired it), leave alone and note in return.
-
-## Anti-patterns
-
-| WRONG | CORRECT |
-|-------|---------|
-| Replace entire `index.astro` contents | Use `Edit` to patch only the stores-related sections |
-| Call `/stores/v3/categories/query` | Use `categoriesV3` SDK, or fall back to `/categories/v1/categories/query` |
-| Invent category slugs that don't exist | Match real categories; fall back to `/products` for unmatched |
-| Pass flat props (`name={p.name}`) when ProductCard expects `product={...}` object | ProductCard is a template — always `<ProductCard product={p} />` with the raw SDK object |
-| `featured = products.map(p => ({name: p.name, ...}))` — flat-mapping SDK results | Store raw products: `featured = featuredProducts ?? []` as `any[]` |

package/skills/wix-headless/references/astro/stores/PRODUCT_PAGES.md

@@ -1,215 +0,0 @@
-# Phase 4 Product Pages — Stores
-
-Scope: `product-pages` (the `pages-products` scope) — written by the stores **merged build agent** (the build wave) *after* its `components` and `pages-categories` scopes. This scope writes the product listing, product detail, and ProductCard component **once** — applying the designer's visual spec (`references/astro/designer/INSTRUCTIONS.md` → `store-pages`) together with live `productsV3` queries in a single pass. Read your seeded slice from `.wix/seeded.json` (`seeded.stores`).
-
-## Scope
-
-Files this agent OWNS (each written once, visual structure + live queries together):
-
-- `src/pages/products/index.astro` — product listing
-- `src/pages/products/[slug].astro` — product detail with `wixMetadata` + SEO tags
-- `src/components/ProductCard.astro` — reusable card used by listing + home
-
-Files this agent MUST NOT touch:
-- `src/components/ProductPurchase.tsx`, `src/components/AddToCartButton.tsx` — owned by `components`
-- `src/pages/cart.astro`, `src/pages/thank-you.astro` — owned by `cart-checkout`
-- `src/pages/index.astro`, `src/components/Navigation.astro` — owned by `pages-home-and-nav`
-- `src/components/CategoryRail.astro` — owned by the `pages-categories` scope, which your merged agent writes **before** this one. **Import** from `../../components/CategoryRail.astro`; never `Write` it here. By the time you mount it, the `pages-categories` step has already put it on disk. If it's somehow absent, you wrote your scopes out of order — return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "src/components/CategoryRail.astro" }]` (write `pages-categories` before `pages-products`; never defensively `Write` it from this scope).
-- `src/utils/categories.ts` — pre-copied by the orchestrator in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"). **Import** `listStoreCategories`/etc. from `../../utils/categories`; never `Write` it.
-- `global.css`, any other `.astro` page, any other component — owned by designers
-
-## Inputs (from parent prompt)
-
-- **Phase 1 return data** — `products: [{id, name, slug, variantId, price, inventory, sku}]` — use slugs when needed (rarely; `queryProducts` returns them already).
-- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk) for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens (`class="py-24 flex flex-col gap-4 font-display"`) at the call site rather than inventing semantic classes for layout/spacing/typography. Retained global semantic classes are limited to compound patterns (`offer-callout`, `cart-summary`), interactive primitives (`btn-primary`, `product-card`), and JS targets — see `references/shared/STYLING.md`.
-- **Designer visual spec** — the layout, contract classes, and decorative-slot conventions for `products/index.astro`, `products/[slug].astro`, `ProductCard.astro` (from `references/astro/designer/INSTRUCTIONS.md` → `store-pages`), applied in the same pass as the live queries.
-
-## Critical rules (all must be honored)
-
-1. **Use `productsV3`, not `products`** — V1 silently returns 0 on V3 catalogs.
-2. **Product detail MUST use `getProductBySlug()`**, not `queryProducts()`. `queryProducts` omits variant data (`options`, `variantsInfo`), making add-to-cart silently fail.
-3. **Product detail MUST export `wixMetadata`** — required for Wix sitemap, SEO editor, and dashboard deep links. Without it, the sitemap has zero product entries.
-4. **Mount `SeoTags` on the detail page** — pipe `product.seoData.tags` through `Layout`'s `head` slot so merchant SEO edits in the Wix dashboard reach the live site. `seoData` is returned by default — no `fields` flag needed.
-5. **Mount `ProductPurchase` with `client:load` and a single `product` prop, plus the back-in-stock probe + price props.** `<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} backInStockEnabled={backInStockEnabled} priceAmount={priceAmount} />`. The component destructures internally; passing flat props (`productId={product._id}`, `options={product.options}`, …) silently renders nothing because the new contract expects `product`. The `backInStockEnabled` boolean comes from `await getBackInStockEnabled()` (template imports it from `../../utils/back-in-stock`); `priceAmount` is the numeric price already computed in the frontmatter. See `BACK_IN_STOCK.md` for why both are needed.
-6. **SSR only — do NOT add `export const prerender = true` or `getStaticPaths()`.** The productsV3 SDK depends on request-context auth (tenant resolution, site headers). At prerender time there is no request, and `.queryProducts().limit()` short-circuits to `"is not a function"`. Keep `[slug].astro` server-rendered with `Astro.params.slug`.
-7. **No HTML comments in `.astro` frontmatter.** Build fails with "Legacy HTML single-line comments are not allowed".
-8. **Default to tokens-as-utilities for layout/spacing/typography.** When you need a section padding, a flex column, a typographic treatment — write Tailwind utilities derived from `@theme` tokens (`<section class="py-24 flex flex-col gap-4">`, `<h1 class="font-display text-4xl">`). Do NOT invent semantic classes like `.featured-section`, `.page-header`, `.products-header-image` — Tailwind v4 silently drops undeclared classes. Use a global semantic class only when one is published in designer `INSTRUCTIONS.md`'s always-required list (`product-card`, `product-card-ribbon`, `offer-callout` family). For one-off page decoration, write a co-located `<style>` block at the bottom of the same `.astro` file using `var(--color-foo)` token references.
-9. **Preserve designer classes.** When the designer used a published global semantic class on existing markup, keep it; don't rename. Add Tailwind utilities alongside if you need additional layout adjustment.
-
-## Wix Site Structure — `wixMetadata` + `@wix/astro-pages`
-
-`@wix/astro-pages` is already wired into the blank scaffold's `astro.config.mjs` as `wixPages()`. It injects a `/_wix/pages.json` endpoint enumerating every page and reading each page's `wixMetadata` export. Wix platform services use this JSON to:
-
-- Generate server-side sitemap entries for dynamic product URLs (via `@wix/auto_sdk_seo_seo-sitemap-entries`)
-- Power the dashboard SEO editor ("Edit SEO for Product pages")
-- Resolve deep links from dashboard / email / analytics surfaces back to the right headless URL
-
-> **Two different Stores appDefIds — do not confuse:**
-> - `215238eb-22a5-4c36-9e7b-e7c08025e04e` — for `catalogReference.appId` in cart operations (same value used for app install in Phase 1).
-> - `1380b703-ce81-ff05-f115-39571d94dfcd` — for **`wixMetadata.appDefId`** on Stores sub-pages (product, category).
->
-> Both are correct. They identify different entities.
-
-## Template files
-
-This scope uses **template files** instead of inline code. For each file below:
-
-1. Read the template from `<Agent location>/templates/<path>`
-2. Write it to the project at the target path
-3. Adapt class names only if the styling contract maps them differently than the defaults
-
-Do NOT modify logic, imports, SDK calls, `wixMetadata` export, or prop-passing. The templates encode non-negotiable Wix platform integrations (sitemap registration, inventoryItemsV3 OOS truth, SSR-only constraint, analytics payloads).
-
-## Implementation
-
-> Every Wix SDK `await` in the templates is already wrapped in try/catch — keep those guards when adapting. See `references/shared/IMPLEMENTER.md` § "SSR error guards" for the underlying rule and rationale.
-
-### 1. `src/pages/products/index.astro` — product listing
-
-Use template `templates/products/index.astro`.
-
-Applies the designer's page structure (class names, layout) and binds a guarded, **cursor-paginated** `productsV3.queryProducts({ fields: ["CURRENCY"] }).limit(24).skipTo(cursor).find()` (cursor read from `?cursor=` on the URL; Prev/Next anchors built from `result.cursors.next` / `.prev`). Mounts the shared `<CategoryRail/>` (written by `pages-categories`) above the grid, passing `activeSlug={null}` and the prev/next hrefs. Emits the `AddProductImpression` analytics event from a client-side script that reads a JSON payload serialized at SSR.
-
-> **Imports you must NOT write.** `<CategoryRail/>` (`../../components/CategoryRail.astro`) is written by the `pages-categories` scope your merged agent runs *before* this one; `listStoreCategories` (`../../utils/categories`) is pre-copied by the orchestrator. Both are on disk by the time you mount them. If either fails to resolve, return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "<missing path>" }]` — that means your agent wrote `pages-products` before `pages-categories`, or the pre-copy was skipped.
-
-> **Page size 24** — multiple of the 2/3/4-column grid, well under Wix's per-request cap of 100. Do not change without updating `CATEGORY_PAGES.md` to match.
-
-> **No client-side filter.** Do not ship every product and hide non-matching cards via JS — it doesn't scale and breaks SEO. Do not add `data-category-ids` on `<ProductCard>` or any DOM-hide script. Filtering is done by navigating to `/category/<slug>` (a real route), and `<ClientRouter />` from the designer's Layout handles the swap.
-
-> **Why the double-script pattern:** Listing page is server-rendered but `AddProductImpression` must fire in the browser. The server-computed payload is serialized into an inert JSON `<script>` (`is:inline`) and read by a separate processed `<script>` (bundled by Astro — has ES `import`). `define:vars` + inline-script combinations cannot do ES imports.
-
-> **Gift-card mirror filter (do not remove).** The template applies `productList = productList.filter(p => p.ribbon?.name !== "Gift Card")` after building the result list. When the dashboard's Wix Gift Card app is enabled, it auto-creates 5 mirror Stores products (one per denomination, `productType: "DIGITAL"`, ribbon name `"Gift Card"`). Buying a mirror yields a dud DIGITAL line item that does NOT trigger gift-card issuance — the customer-facing surface for gift cards is `/gift-cards` (gift-cards pack), not `/products`. The filter holds whether or not the gift-cards pack is loaded for this site, so a future site that drops gift-cards but still has the dashboard app stays clean.
-
-### 2. `src/components/ProductCard.astro` — reusable card
-
-Use template `templates/ProductCard.astro`.
-
-The template:
-- Accepts a single `{ product }` prop — the full Wix product object from `productsV3`
-- Resolves product images via `resolveWixImageUrl` (imported from the seeded shared util at `../utils/wix-image`)
-- Applies `product-card` contract class
-- Includes delegated click analytics (`ClickProduct` event via data attributes)
-
-Class from contract: `productCard` → `"product-card"`. If the designer already added the class, don't duplicate.
-
-### 3. `src/pages/products/[slug].astro` — product detail
-
-Use template `templates/products/[slug].astro`.
-
-The template:
-- Exports `wixMetadata` with the Stores sub-page appDefId (`1380b703-…`) and `STORES.PRODUCT.SLUG` token for platform expansion
-- Uses `getProductBySlug()` (NOT `queryProducts()` — it omits variant data)
-- Queries `inventoryItemsV3.queryInventoryItems({ filter: { productId } })` and builds a `variantId → { quantity, trackQuantity, preorderEnabled }` map. This is the AUTHORITATIVE OOS signal; `variantsInfo[].inventoryStatus.inStock` is a stale cached flag.
-- Pipes `product.seoData.tags` through Layout's `head` slot via `<SeoTags slot="head" tags={seoTags} />` (rendered only when any tag is visible)
-- Calls `await getBackInStockEnabled()` from `../../utils/back-in-stock` to learn whether the dashboard's "Start Collecting Requests" toggle is on for Wix Stores; passes the boolean and `priceAmount` to `<ProductPurchase>`. The back-in-stock subscribe form renders inside ProductPurchase's three OOS branches when the prop is true. See `BACK_IN_STOCK.md` for the app-id discrepancy and the bare-fields rule.
-- Mounts `<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} backInStockEnabled={backInStockEnabled} priceAmount={priceAmount} />` with the canonical `{ product }` contract
-- Wraps both SDK awaits in try/catch so an SDK error produces a 404 redirect (product fetch) or an empty inventory map (inventory fetch), never a torn page (the back-in-stock probe is internally wrapped — it returns `false` on any failure, so it doesn't need an outer try/catch)
-
-**Critical details on `wixMetadata`:**
-
-- **Required for Wix platform indexing.** Without it, the product detail route is invisible to Wix's sitemap generator, SEO editor, and deep-link resolver.
-- **`appDefId`: `1380b703-ce81-ff05-f115-39571d94dfcd`** is the Stores page-registration defId — do NOT confuse with the Stores install/catalog defId (`215238eb-...`) used in Phase 1 and `catalogReference.appId`.
-- **`pageIdentifier`: `"wix.stores.sub_pages.product"`** is the canonical Wix identifier — constant.
-- **`identifiers.slug`**: maps the Astro route param to Wix's identifier token. Route is `[slug].astro`, so key is `slug`. Value `"STORES.PRODUCT.SLUG"` tells Wix to expand with each product's slug.
-
-**Layout `head` slot** — the `Layout.astro` written by the Design System phase must accept a `head` slot and a `hasSeoTags` prop. When `hasSeoTags` is true, the Layout omits its default `<title>`/`<meta description>` and instead renders the `head` slot contents into `<head>`. This lets `SeoTags` entirely replace the default metadata. If the Layout signature doesn't match, the Design System brief is missing it — flag this in the return's `errors` array and continue with a fallback (non-merchant-editable) title.
-
-## Live offers (discount-rule indicators)
-
-The promotion ribbon on each product card is **owned by `ProductCard.astro` itself** — the component imports `fetchLiveOffers` + `offersForProduct` from `src/utils/discounts.ts` (shipped by the ecom `components` scope) and renders its own ribbon. Pages that mount `ProductCard` do NOT pass an `offers` prop and do NOT fetch offers themselves. This concentrates the wiring in one place — page-level wiring forced every page that renders ProductCard to remember it, and category pages would silently ship without ribbons.
-
-`fetchLiveOffers` is memoized per request via `auth.elevate`'s caching, so rendering N ProductCards in one page does NOT fan out N discount-rule queries.
-
-**Listing (`products/index.astro`)** — just `<ProductCard product={product} index={idx} />`. No offers wiring required.
-
-**Detail (`products/[slug].astro`)** — the detail page renders a richer offer callout above `<ProductPurchase>`. That callout still belongs to this scope (it's not part of the card). After the product is loaded:
-
-```ts
-import { fetchLiveOffers, offersForProduct } from "../../utils/discounts";
-const offers = await fetchLiveOffers();
-const productOffers = offersForProduct(offers, product._id);
-```
-
-```astro
-{productOffers.length > 0 && (
-  <div class="offer-callout">
-    {productOffers.map((o) => (
-      <div class="offer-callout-item">
-        <span class="offer-callout-badge">Offer</span>
-        <div>
-          <p class="offer-callout-name">{o.name}</p>
-          {o.offer && o.offer !== o.name && (
-            <p class="offer-callout-detail">{o.offer}</p>
-          )}
-        </div>
-      </div>
-    ))}
-    <p class="offer-callout-foot">Applied automatically at checkout.</p>
-  </div>
-)}
-
-<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} />
-```
-
-The `.offer-callout*` classes are owned by `src/styles/components-stores.css` (written by the stores Phase 3 components agent), NOT by the designer. Use `{o.offer}` for the body text — that's the dashboard-authored offer string (e.g. `"Buy 1 item\nAll products\n\nGet 1 item for free"`) which Wix formats with `\n` line breaks; the CSS includes `white-space: pre-line` so those render as line breaks.
-
-**Do NOT** hit `discountRules.queryDiscountRules` directly from this scope — always go through `fetchLiveOffers()`. The helper wraps the call with `auth.elevate()` (the endpoint requires `ECOM.DISCOUNT_RULES_READ`, visitor clients return nothing silently) and normalizes the scope-id field (`_id` vs `id`) which trips up naive matching.
-
-When the site has no active rules (first deploys, or the user hasn't created any in the dashboard yet), `offers` comes back as `[]`, `offersForProduct(...)` returns `[]`, the ribbon and callout both render nothing — no code path to guard for.
-
-## Analytics fired from this scope
-
-| Event | Fires from | When | Payload |
-|-------|------------|------|---------|
-| `AddProductImpression` | `products/index.astro` | Listing page load | `{ contents: [{id, name, price, currency, position}], origin: "Product Listing" }` |
-| `ClickProduct` | `ProductCard.astro` | Delegated click on any card | `{ id, name, price, currency, origin: "Product Listing" }` |
-| `ViewContent` | `products/[slug].astro` | Detail page load | `{ id, name, price, currency, origin: "Product Page" }` |
-
-`AddToCart` fires from `AddToCartButton.tsx` (written by `components`) — not this scope.
-
-## Return format
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-pages-products",
-  "scope": "product-pages",
-  "summary": "Wired product listing + detail + ProductCard to productsV3; wixMetadata + SeoTags mounted",
-  "data": {
-    "pagesWired": 2,
-    "wixMetadataExported": true,
-    "seoTagsMounted": true,
-    "useGetProductBySlug": true,
-    "analyticsEvents": ["AddProductImpression", "ClickProduct", "ViewContent"]
-  },
-  "files": [
-    "src/pages/products/index.astro",
-    "src/pages/products/[slug].astro",
-    "src/components/ProductCard.astro"
-  ],
-  "errors": []
-}
-```
-
-If any of `wixMetadataExported`, `seoTagsMounted`, `useGetProductBySlug` ends up `false`, set `status: "partial"` and populate `errors` with the specific issue. These three are non-negotiable for a merchant-grade site.
-
-## Anti-patterns
-
-| WRONG | CORRECT |
-|-------|---------|
-| `import { products }` from `@wix/stores` | `productsV3` |
-| Use `queryProducts()` on detail page | `getProductBySlug()` — `queryProducts` omits variant data |
-| `export const prerender = true` + `getStaticPaths()` on `[slug].astro` | SSR only — productsV3 needs request-context auth; prerender short-circuits it |
-| Pass flat props to `<ProductPurchase>` (`productId`, `options`, `variantsInfo`, …) | Pass the whole product: `<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} />` |
-| Hardcode `<title>` from `product.name` | Pipe `product.seoData.tags` through `SeoTags` slot, fall back to `product.name` only when tags are empty/disabled |
-| Omit `wixMetadata` export | Required — platform indexing breaks silently without it |
-| Add `fields: ["SEO_DATA"]` | `seoData` is returned by default — no such enum value exists |
-| Write `src/utils/wix-image.ts` inline | Import `resolveWixImageUrl` from `../utils/wix-image` — shared util already exposes it |
-| `ls src/` to find designer output | Parent prompt lists every existing `src/` file — read directly |
-| Rename designer class names | Keep them; use contract classes when ADDING new markup |
-| HTML `<!-- comment -->` in `.astro` frontmatter | `//` or `/* */` — frontmatter is TypeScript |
-| Mount React island without `client:load` | Options + cart state needs hydration |
-| Pass `"INVENTORY"` in the `fields` array | No such enum value exists for `productsV3`. Valid values: `URL`, `CURRENCY`, `INFO_SECTION`, `MERCHANT_DATA`, `PLAIN_DESCRIPTION`, `INFO_SECTION_PLAIN_DESCRIPTION`, `SUBSCRIPTION_PRICES_INFO`, `BREADCRUMBS_INFO`, `WEIGHT_MEASUREMENT_UNIT_INFO`, `VARIANT_OPTION_CHOICE_NAMES`, `MEDIA_ITEMS_INFO`, `DESCRIPTION`, `DIRECT_CATEGORIES_INFO`, `ALL_CATEGORIES_INFO`, `INFO_SECTION_DESCRIPTION`, `THUMBNAIL`, `PRODUCT_CHOICES_MEDIA_REFERENCES`. Passing an invalid value makes the query throw. |
-| Trust `variantsInfo[].inventoryStatus.inStock` as the OOS gate | It's a stale cached flag — a variant with real quantity 0 can still report `inStock: true`. Query `inventoryItemsV3.queryInventoryItems({ filter: { productId } })` at SSR and pass a `variantId → { quantity, trackQuantity, preorderEnabled }` map into `ProductPurchase`. The template already does this. |
-| Skip the `backInStockEnabled` prop on `<ProductPurchase>` | Always pass it (template already imports `getBackInStockEnabled`). When the prop is missing, the OOS subscribe form never renders even if the merchant has enabled collecting requests. |
-| Pass the formatted price string (`"$695"`) as `priceAmount` | Pass the numeric `priceAmount` already computed in frontmatter. The Wix back-in-stock service rejects formatted prices with `400 DECIMAL_GTE`. |

package/skills/wix-headless/references/astro/stores/SHARED_WIRING.md

@@ -1,165 +0,0 @@
-# Phase 3 Components — Stores (TSX/Astro)
-
-This is the **components** portion of the stores **merged build agent** (the build wave — `BUILD-astro.md` § "Step 4.5"). Your agent writes these islands **first**, then the stores pages (`pages-categories`, `pages-products`) that mount them — so the islands are on disk before the page code references them. The code here depends on the **design tokens** (read from `.wix/design-tokens.css` on disk) but NOT on page markup.
-
-> **CSS is pre-copied, not authored.** `src/styles/components-stores.css` ships from the skill template, copied by the orchestrator in the build-wave pre-batch (see `./COMPONENTS_CSS.md`). This scope does NOT write the CSS file. Reference its contract class names from the design tokens here; the pre-copied stylesheet defines the rules.
-
-## Scope
-
-Files this agent OWNS (creates fresh, no designer output to read):
-
-- `src/components/SeoTags.astro` — Renders `product.seoData.tags` into `<head>`
-- `src/components/AddToCartButton.tsx` — React island; optimistic add-to-cart
-- `src/components/ProductPurchase.tsx` — React island; option selectors + variant resolution + wraps AddToCartButton
-- `src/components/BackInStockForm.tsx` — React island; back-in-stock subscription form
-
-Files this agent MUST NOT touch:
-- `src/styles/components-stores.css` — owned by the **`components-css`** sibling scope (see `./COMPONENTS_CSS.md`). Reference its class names; do not write the file.
-- `src/utils/wix-image.ts` — **shared utility shipped by the build skill.** Import `resolveWixImageUrl` from `../utils/wix-image`; do NOT write your own copy (would shadow the shared util and drop other verticals' callers). The canonical source lives at `<SKILL_ROOT>/shared-utilities/wix-image.ts`; it's copied into projects by `seed-utilities.sh` during Setup.
-- `src/components/CartView.tsx`, `src/components/CartBadge.tsx`, `src/utils/analytics.ts`, `src/styles/components-ecom.css` — owned by ecom
-- `src/utils/back-in-stock.ts` — **pre-copied by the orchestrator** in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"), same as `categories.ts`. Import `getBackInStockEnabled`/the app-id constants from `../utils/back-in-stock`; never `Write` it (see `./BACK_IN_STOCK.md`).
-- Any `.astro` page — written by your agent's `pages-*` scopes (after the islands) or by another vertical
-- `src/styles/global.css` — owned by designer foundation
-- `src/layouts/Layout.astro` — owned by designer foundation (including the `components-stores.css` import line)
-- Any designed component (`ProductCard.astro`, `Navigation.astro`, etc.) — owned by designers
-
-## Coordination: design tokens
-
-Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave). The parent skill serializes your launch behind the designer foundation specifically so this file is already written when you start.
-
-Reference the ACTUAL class names from the contract in React components (e.g. `className="add-to-cart-btn"`, not `className="addToCartButton"` or an invented name). See `references/shared/IMPLEMENTER.md` § "Contract class-name adaptation" for the full rule.
-
-## Critical rules
-
-1. **Import `productsV3`, never `products`** — V1 silently returns 0 results on V3 catalogs (used in `ProductPurchase.tsx` type definitions).
-2. **Always include `variantId` in `catalogReference.options`** — even single-variant products have one. Without it, `addToCurrentCart` returns 200 OK but silently adds nothing.
-3. **No HTML comments in `.astro` frontmatter** — frontmatter is TypeScript; use `//` or `/* */`. Build-fails with "Legacy HTML single-line comments are not allowed".
-4. **Use brand-token Tailwind utilities on React islands** (e.g., `bg-bark`, `text-cream`), never default Tailwind colors (`bg-green-50`, `text-red-600`). See IMPLEMENTER.md § "Contract class-name adaptation" for the class-name rule itself.
-5. **Analytics is fire-and-forget** — see `references/shared/IMPLEMENTER.md` § "Fire-and-forget analytics".
-
-## Template files
-
-This scope uses **template files** instead of inline code. For each file below:
-
-1. Read the template from `<Agent location>/templates/<filename>`
-2. Write it to the project at the target path
-3. Adapt CSS class names if the design tokens maps them differently than the defaults
-
-Do NOT modify logic, imports, or component structure.
-
-## Implementation
-
-### 1. `src/styles/components-stores.css` — not owned by this scope
-
-> Owned by the **`components-css`** sibling scope. See `./COMPONENTS_CSS.md`. Reference the contract class names from the design tokens in your TSX/Astro files; the CSS sibling defines the rules.
-
-### 2. `src/utils/analytics.ts` — not owned by this scope
-
-> Import from it (`import { trackEvent } from "../utils/analytics"`) but do not write it. Shipped by the build skill as a seeded shared utility.
-
-### 3. `src/utils/wix-image.ts` — not owned by this scope
-
-> Import `resolveWixImageUrl` from `../utils/wix-image` but do not write it. Shipped by the build skill as a seeded shared utility that already exposes `resolveWixImageUrl(image, width?, height?)`. Writing your own copy shadows and breaks callers in other verticals (blog, cms).
-
-### 4. `src/components/SeoTags.astro`
-
-Use template `templates/SeoTags.astro`.
-
-Renders merchant-edited SEO from the Wix dashboard into `<head>`. Mounted on the product detail page (by `product-pages` scope) via `Layout`'s `head` slot.
-
-`product.seoData` is returned by default from `getProductBySlug` — no `fields` flag needed.
-
-### 5. `src/components/AddToCartButton.tsx`
-
-Use template `templates/AddToCartButton.tsx`.
-
-Optimistic add-to-cart button. Shows "Added ✓" immediately; fires API in background; reverts on failure. Dispatches `cart-updated` events so CartBadge can update badge count instantly.
-
-Uses `@wix/ecom` `currentCart.addToCurrentCart`. `WIX_STORES_APP_ID` is the Stores appDefId constant (`215238eb-22a5-4c36-9e7b-e7c08025e04e`) used in `catalogReference.appId`.
-
-**Modifier support** — accepts pre-flattened `modifierChoices` and `customTextFields` from ProductPurchase and merges them into `catalogReference.options` per the Wix Stores Catalog V3 contract. ProductPurchase owns the flattening; this component just passes them through.
-
-Class from contract: `addToCartButton` → `"add-to-cart-btn"`.
-
-### 6. `src/components/CartBadge.tsx` — not owned by this scope
-
-> Do not write this file. AddToCartButton dispatches `cart-updated` CustomEvents that CartBadge (owned by ecom) listens for.
-
-### 7. `src/components/ProductPurchase.tsx`
-
-Use template `templates/ProductPurchase.tsx`.
-
-Handles variant selection, quantity selector, stock awareness, and wraps `AddToCartButton`. Mounted on product detail pages (by `product-pages` scope) as:
-
-```tsx
-<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} />
-```
-
-**Prop contract — single `product` object.** The template accepts the full productsV3 product and destructures internally. This mirrors `ProductCard.astro`'s `{ product }` contract so both stores components take the same shape (prevents a shape mismatch where a fallback-written `[slug].astro` passes `product` as a whole while the component expects flat props).
-
-Key behaviors:
-- `hasMeaningfulOptions` — a product has meaningful options only when at least one option has >1 choice. Dummy single-choice options (e.g., "Type: Standard") are treated as no options.
-- Out of stock → renders just the message, no button.
-- No meaningful options → renders quantity + AddToCartButton with default variant ID.
-- Has options → renders pill selectors + quantity + AddToCartButton with resolved variant ID.
-- **Modifiers** — customization choices that do NOT create separate variants. Pills for `modifierRenderType === "TEXT_CHOICES"` / `"SWATCH_CHOICES"`, textarea for `"FREE_TEXT"`. Mandatory modifiers must have a value before add-to-cart is enabled. Selections flatten into `{ options: { [modifier.key]: choice.key }, customTextFields: { [modifier.freeTextSettings.key]: text } }` before being handed to AddToCartButton.
-- **OOS gating** — source of truth is `inventoryByVariant` (from `inventoryItemsV3`). `variantsInfo[].inventoryStatus.inStock` is a stale cached flag and is only used when the live map is empty. See PRODUCT_PAGES.md for the detail-page query that populates `inventoryByVariant`.
-
-Classes from contract (stores pack):
-
-- **Global** (CSS in foundation's `global.css`):
-  - `productPurchase` → `"product-purchase"` (outer wrapper — use on the root `<div>`)
-- **Scoped** (CSS in `components-stores.css`, owned by the `components-css` sibling scope — see `./COMPONENTS_CSS.md`):
-  - `optionGroup` → `"option-group"`
-  - `optionLabel` → `"option-label"`
-  - `optionChoices` → `"option-choices"`
-  - `optionPill` → `"option-pill"` (state modifier `.selected` for active choice)
-  - `quantitySelector` → `"quantity-selector"`
-  - `quantityBtn` → `"quantity-btn"`
-  - `quantityValue` → `"quantity-value"`
-  - `stockStatus` → `"stock-status"`
-
-**Do not invent new class names** — if a new interactive control needs a class, add it to the pack's `contractKeys.scoped` first.
-
-### 8. `src/components/CartView.tsx` — not owned by this scope
-
-> Do not write this file.
-
-## Return format
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-components",
-  "scope": "components",
-  "summary": "Wrote React islands and Astro components from templates (CSS handled by components-css sibling)",
-  "data": {
-    "islands": ["ProductPurchase.tsx", "AddToCartButton.tsx", "BackInStockForm.tsx"],
-    "astroComponents": ["SeoTags.astro"],
-    "globalContractClassesReferenced": ["addToCartButton", "productPurchase"],
-    "scopedContractClassesReferenced": ["optionGroup", "optionLabel", "optionChoices", "optionPill", "stockStatus", "quantitySelector", "quantityBtn", "quantityValue"]
-  },
-  "files": [
-    "src/components/SeoTags.astro",
-    "src/components/AddToCartButton.tsx",
-    "src/components/ProductPurchase.tsx",
-    "src/components/BackInStockForm.tsx"
-  ],
-  "errors": []
-}
-```
-
-## Anti-patterns
-
-| WRONG | CORRECT |
-|-------|---------|
-| Read designer `.astro` files | Not needed — this scope doesn't touch pages |
-| Import `products` from `@wix/stores` | Use `productsV3` |
-| Write `src/utils/wix-image.ts` | Import from it — shared util already exposes `resolveWixImageUrl` |
-| Hardcode `className="btn-primary"` | Use contract class `className="add-to-cart-btn"` |
-| Default Tailwind color utilities on React islands (`bg-green-50`, `bg-blue-500`) | Brand `@theme` utilities (`bg-bark`, `text-cream`) or contract class names |
-| `<!--` HTML comments in `.astro` frontmatter | `//` or `/* */` — frontmatter is TypeScript |
-| Omit `WIX_STORES_APP_ID` constant | Hardcoded `215238eb-22a5-4c36-9e7b-e7c08025e04e` in AddToCartButton for `catalogReference.appId` |
-| Introspect `node_modules/@wix/*` | All symbols are documented here; if missing, use docs-search REST (see `DOCS_SEARCH.md`) |
-| Write `CartView.tsx`, `CartBadge.tsx`, or `analytics.ts` | Not owned by this scope — do not write |
-| Pass flat props to `ProductPurchase` (`productId`, `options`, `variantsInfo`, …) | Pass the whole product: `<ProductPurchase product={product} inventoryByVariant={inventoryByVariant} />` |