@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-headless/references/astro/designer/INSTRUCTIONS.md

@@ -1,351 +0,0 @@
----
-name: page-designer
-description: "The page-design specification for Wix Managed Headless page routes: home, static (about/faq), store-pages, services-pages, blog-pages, contact-page. This is the visual-design guidance the merged build agents' `pages` scopes (vertical packs, BUILD-astro.md § 'Step 4.5' — the build wave) apply when they write each route ONCE with both visual design and live SDK data. It defines layout, contract classes, decorative-slot conventions, responsive rules, and anti-patterns — not a separate placeholder-writing pass. The design-system phase (tokens + global.css + Layout/Nav/Footer shells) is NOT here — it is split across DESIGN_SYSTEM.md (Designer) and scripts/compose.mjs (Composer)."
----
-
-# Page Designer — Scope-Based Page Design
-
-> **Single-write merged model (BUILD-astro.md § "Step 4.5" — the build wave — is authoritative).** Routes are written **once**, by the per-vertical merged build agents' `pages` scopes (after that agent writes its islands), with both visual design **and** live SDK queries in the same pass — there is no separate "write a design placeholder, then rewrite it with data" dispatch (that double-write was eliminated), and no separate Components→Pages wave (those are merged into one per-vertical agent). This doc is the **visual-design specification** the merged author applies: the layout, typography, color, spacing, contract classes, decorative slots, and component composition each route should have. Where a section below says "placeholder data," read it as *the data shape* the live query maps onto — and the safe fallback to render if a query returns empty. The merged scope binds real SDK data into this structure; it does not ship hardcoded arrays as the final output.
-
-Your prompt will contain a `Scope:` line naming exactly one of the page scopes below. **Read only the section for your scope. Do not read sections for other scopes — wastes context and blurs ownership.**
-
-You own **page-level visual output**: the layout, typography, color, spacing, and component composition of one route group. The same merged scope also binds the live SDK data into that structure (the per-vertical reference under `references/astro/<vertical>/` supplies the exact queries).
-
-> **The design-system phase is not in this doc.** Tokens (`DESIGN.md` / `data.design`), `global.css`, `astro.config.mjs`, `Layout.astro`, `Navigation.astro`, and `Footer.astro` are produced earlier in the run by a two-role split:
-> - **Designer** (`<SKILL_ROOT>/references/DESIGN_SYSTEM.md`) — authors `DESIGN.md` (the framework-agnostic token spec) and returns the brand-voice strings.
-> - **Composer** (`<SKILL_ROOT>/scripts/compose.mjs`, a deterministic script — self-documenting) — applies `DESIGN.md` to the astro skeletons and writes the 6 design-system files.
->
-> By the time the Phase 4 routes are written, the `@theme` token contract, the `.astro` shells, and `.wix/design-tokens.css` already exist. You consume them; you do not write them.
-
-## Self-Loading
-
-1. Read `../../shared/RETURN_CONTRACT.md` — structured return format.
-2. Read `../../shared/STYLING.md` — three styling categories (tokens-as-utilities, global semantic classes, co-located styles). Pages compose `@theme` tokens at call sites as Tailwind utilities; the design-token vocabulary on disk at `.wix/design-tokens.css` tells you which tokens this run published.
-
-No REST calls required. Page-design scopes are frontend-only — no `curl`, no MCP tool-discovery.
-
-**Every input you need (brand, the published design-token vocabulary, pages to design, pack home-section snippets) is inlined in your prompt.** Don't depend on mutable shared state.
-
-## Scope Routing
-
-| Scope | Phase | Output (files) |
-|-------|-------|----------------|
-| `home` | build wave | `src/pages/index.astro` (composes pack home-sections + brand hero/CTA into the Composer-written shell) |
-| `static` | build wave | `src/pages/about.astro`, `src/pages/faq.astro` |
-| `store-pages` | build wave | `src/pages/products/index.astro`, `src/pages/products/[slug].astro`, `src/components/ProductCard.astro`, `src/pages/cart.astro`, `src/pages/thank-you.astro` |
-| `services-pages` | build wave | `src/pages/services/index.astro`, `src/pages/services/[slug].astro`, `src/pages/booking-confirmation.astro` |
-| `blog-pages` | build wave | `src/pages/blog/index.astro`, `src/pages/blog/[slug].astro` |
-| `contact-page` | build wave | `src/pages/contact.astro` |
-
-If your prompt's `Scope:` line names `design-system`, you have the wrong doc — that work lives in `DESIGN_SYSTEM.md` (Designer) and `scripts/compose.mjs` (Composer). Stop and tell the parent.
-
-If your prompt is missing a `Scope:` line, stop and ask the parent — do not guess.
-
-**Disabled-pack route discipline.** Loaded packs with `disabled: true` (today: only `gift-cards`) ship dormant — their surfaces are runtime-gated and only appear once the user enables the matching app. Do NOT add hero CTAs, footer links, brand-story callouts, closing-CTA buttons, or ANY entry point pointing at a `disabled: true` pack's route in your page output. Users click through and the feature doesn't exist. The pack's own markers are the only acceptable touchpoint, and those get gated by the pack's runtime probe in Phase 4, not by you.
-
----
-
-## Page Designer Scopes (build wave, background)
-
-All page scopes share common inputs and rules. Scope-specific details follow.
-
-### Common inputs (from your prompt)
-
-- **Brand context** — name, vibe, aesthetic direction, colors, fonts, mood.
-- **Published token contract** — the design-token vocabulary (the DESIGN.md tokens, written into `@theme` by `compose.mjs`). Compose these tokens as Tailwind utilities; if a token you need is absent, flag it in your return (`MISSING_TOKEN`) — do not invent a class.
-- **Pages to design** — list of routes and their contract class associations.
-- **Pack home-section snippet** (home scope only) — section stubs from every loaded pack.
-- **Placeholder data instruction** — use plausible brand-contextual placeholder text, prices, images where live data is not yet available.
-
-### Common rules for all page scopes
-
-1. **Use contract classes.** Every component that corresponds to a contract key uses that class name. Do not invent replacements.
-2. **Use the Layout.** Every page wraps content in `<Layout>`:
-   ```astro
-   ---
-   import Layout from '../layouts/Layout.astro';
-   ---
-   <Layout title="Page Title">
-     <!-- page content -->
-   </Layout>
-   ```
-3. **Never empty — render real data, fall back gracefully.** Bind the live SDK query into the designed structure. When a query legitimately returns empty (collection not seeded, OOS, etc.), render a brand-contextual fallback (plausible copy / a tasteful empty state) so the page still looks complete and reviewable — never a blank section.
-4. **SDK queries belong in the route frontmatter.** The merged `pages` scope imports the relevant SDK (`@wix/stores`, `@wix/data`, `@wix/blog`, …) in the route's frontmatter and queries live data — see the per-vertical reference under `references/astro/<vertical>/` for the exact queries. Wrap every SSR `await` in try/catch with a safe fallback (an unguarded SSR throw truncates Astro's response stream mid-body). Do **not** ship hardcoded arrays as the final page output.
-5. **No React islands authored here.** Do not write `.tsx` components — Phase 3 Components writes the islands. Phase 4 routes **mount** the already-written islands (`client:load`, etc.) but never author them.
-6. **Scoped page styles allowed.** Pages may add `<style>` blocks for page-specific ornamental styling (section backgrounds, decorative elements, page-specific spacing adjustments). These are local to the page — do not override contract class rules from `global.css`.
-7. **Image placeholders — decorative slot convention.** Every decorative image (hero, about visual, page-header art) MUST be emitted as a `<div>` placeholder carrying a `data-decorative-slot="<key>"` attribute. **Use ONLY canonical slot keys from this fixed vocabulary:**
-
-    | Key | Where it lives | Required when |
-    |---|---|---|
-    | `hero` | Homepage hero image | Always |
-    | `about` | About-page (or home brand-story) editorial visual | Always |
-    | `productsHeader` | `/products` listing header decorative | Stores pack loaded |
-    | `cmsHeader` | `/about` or `/faq` page header decorative | CMS pack loaded (optional) |
-
-    Do NOT invent keys like `aboutFeature`, `background`, `heroAlt`, etc. The image agent receives this canonical list as its `decorativeSlots` input and generates exactly those keys — invented keys will not have images, and orphan generated images go unused. If a page needs more visual interest, use scoped CSS / SVG / brand-color blocks instead of additional generated images. The orchestrator runs a post-Phase-2 Edit pass that injects the actual `<img>` for each slot once Image Phase 1 finishes; your job is to make the slot visible. Rules:
-    - Use aspect-ratio + background-color on the placeholder so the page looks complete even if Image Phase 1 never completes.
-    - Keep decorative overlays (stamps, rules, frames) as siblings of the slot `<div>` — the orchestrator injects the `<img>` as the FIRST child of the slot, so anything you want to layer over it must stay outside the slot `<div>` (or inside with explicit z-index).
-    - Do NOT conditionally read any image-coordination file — Image Phase 1's slot→URL map flows to the orchestrator via its JSON return, and the orchestrator injects URLs into your slot placeholders. The slot mechanism is the contract; no file lookup is needed or correct.
-    - Do not use external placeholder services (picsum, unsplash, etc.).
-
-    Example:
-    ```astro
-    <section class="hero-section relative">
-      <div
-        class="hero-image"
-        data-decorative-slot="hero"
-        style="aspect-ratio: 4/5; background-color: var(--color-paper-warm);"
-      >
-        <!-- orchestrator injects <img src={decorativeImages.hero} …> here -->
-      </div>
-      <div class="hero-stamp">{/* decorative overlay, stays outside the slot */}</div>
-    </section>
-    ```
-8. **Comments in frontmatter.** Use `//` or `/* */` — never HTML `<!-- -->` comments in `.astro` frontmatter (it's TypeScript, not HTML). HTML comments in the template section are fine.
-9. **Responsive.** All pages must work at mobile (320px), tablet (768px), and desktop (1024px+). Use Tailwind responsive prefixes (`md:`, `lg:`) and Tailwind's numeric spacing scale (`gap-4`, `py-24`, …).
-10. **Use Tailwind utility classes in templates.** For layout, spacing, typography, and responsive design — use utility classes directly in the markup. Contract classes are still required for components referenced by Phase 3/4 agents. Mix both: `<div class="product-grid grid grid-cols-1 md:grid-cols-3 gap-6">`. Always use brand `@theme` tokens (e.g., `bg-bark`, `text-cream`) — never default Tailwind colors.
-11. **No duplicate files.** If two scopes list the same file (rare), the scope whose prompt explicitly names it as "owned" takes precedence. If unclear, write it and note the overlap in your return.
-12. **Do NOT write to `src/styles/components-<pack>.css` or `src/styles/global.css`** — `components-<pack>.css` is pre-copied from the skill template by the orchestrator (build-wave pre-batch); `global.css` is owned by the Composer. Writing to either causes double-write conflicts.
-
-### Scope: `home`
-
-Composes the home page from every loaded pack's `homeSection` snippet plus brand-specific hero and CTA sections.
-
-**Inputs (additional):**
-- `Pack home-section snippets` — one per loaded pack. Each names a section (e.g., "Featured products", "Brand story", "Latest posts", "Contact CTA") with a description and contract classes.
-
-**Structure:**
-1. **Hero section** — full-width, impactful brand moment. Uses `hero-section` contract class. Emit a `data-decorative-slot="hero"` placeholder per Common rule #7 — do not inline an Image Phase 1 URL; the orchestrator injects the `<img>` after Image Phase 1 completes.
-2. **Pack sections** — one section per loaded pack's `homeSection`, in a sensible order (typically: featured content first, then story, then CTA).
-3. **Optional closing CTA** — if no pack contributes a CTA section, add a minimal brand-appropriate closing.
-
-**Files:** `src/pages/index.astro`
-
-**Return:**
-```json
-{
-  "status": "complete",
-  "phase": "designer-home",
-  "scope": "home",
-  "data": {
-    "pagesDesigned": ["src/pages/index.astro"],
-    "contractClassesHonored": ["hero-section", "product-grid", "product-card", "brand-story", ...]
-  },
-  "files": ["src/pages/index.astro"]
-}
-```
-
-### Scope: `static`
-
-About and FAQ pages — content pages with similar layout demands.
-
-**Files:** `src/pages/about.astro`, `src/pages/faq.astro`
-
-**About page:**
-- Hero/header section with `about-hero` class
-- Body content with `about-body` class
-- Placeholder brand story text (2-3 paragraphs, brand-contextual)
-- Image placeholder for brand/team visual
-
-**FAQ page:**
-- Section wrapper with `faq-section` class
-- Individual Q&A items with `faq-item`, `faq-question`, `faq-answer` classes
-- 4-6 placeholder FAQ items contextual to the business type
-- Accordion or expandable pattern (CSS-only, using `<details>`/`<summary>` or checkbox hack)
-
-**Return:**
-```json
-{
-  "status": "complete",
-  "phase": "designer-static",
-  "scope": "static",
-  "data": {
-    "pagesDesigned": ["about", "faq"],
-    "contractClassesHonored": ["about-hero", "about-body", "faq-section", "faq-item", "faq-question", "faq-answer"]
-  },
-  "files": ["src/pages/about.astro", "src/pages/faq.astro"]
-}
-```
-
-### Scope: `store-pages`
-
-All store-facing pages designed together for visual coherence.
-
-**Files:** `src/pages/products/index.astro`, `src/pages/products/[slug].astro`, `src/components/ProductCard.astro`, `src/pages/cart.astro`, `src/pages/thank-you.astro`
-
-**Products listing (`/products`):**
-- Page heading
-- Product grid using `product-grid` class
-- Bind the live `productsV3` query (per `references/astro/stores/PRODUCT_PAGES.md`) into a grid of `ProductCard` components; render a brand-contextual empty state if the query returns nothing
-
-**Product detail (`/products/[slug]`):**
-- Product image (large) resolved from the live product record
-- Product info section with `product-detail` class
-- Purchase area with `product-purchase` class — price, variant selector, and Add to Cart button (`add-to-cart-btn` class) bound to the live product/variant data
-- Product description area
-
-**ProductCard component:**
-- Accepts a single `product` prop — the full Wix product object from `productsV3`
-- Uses `product-card` class
-- Image, name, price, link to `/products/${product.slug}`
-- Design the prop interface around the full product object: `{ product }` (the canonical `productsV3` shape — see `references/astro/stores/PRODUCT_PAGES.md`)
-
-**Cart (`/cart`):**
-- Two-column grid layout: `.cart-grid` — items column left, order summary right. Stacks vertically on mobile
-- Items column with `.cart-items`, `.cart-item`, `.cart-item.unavailable` (reduced opacity), `.cart-item-image`, `.cart-item-info`, `.cart-item-name`, `.cart-item-option`, `.cart-item-modifiers` classes
-- Quantity selector with `.cart-item-qty`, `.qty-btn`, `.qty-value` classes — include `:disabled` states (reduced opacity + `cursor: not-allowed`)
-- Price display with `.cart-item-actions`, `.cart-item-prices`, `.cart-item-full-price` (strikethrough for discounts), `.cart-item-unit-price`, `.cart-item-line-total` classes
-- Remove button with `.cart-item-remove` class (muted color, underline on hover)
-- Summary column with `.cart-summary` (sticky on desktop), `.cart-subtotal`, `.checkout-btn` (with `:disabled` state), `.cart-empty` classes
-- Unavailable item warning with `.cart-item-unavailable` class (red text)
-- Empty state with `.cart-empty` class (centered, muted text + "Browse Products" link)
-- **All cart CSS must be in `<style is:global>`** — `CartView` is a React island; scoped Astro styles do not reach its children
-- The live `CartView` island renders the items/summary at runtime; design the surrounding structure and an empty-cart fallback
-
-**Thank you (`/thank-you`):**
-- Confirmation message with `order-summary` class
-- Order details bound to the live order data (per the ecom cart/checkout reference)
-
-**Return:**
-```json
-{
-  "status": "complete",
-  "phase": "designer-store-pages",
-  "scope": "store-pages",
-  "data": {
-    "pagesDesigned": ["products/index.astro", "products/[slug].astro", "ProductCard.astro", "cart.astro", "thank-you.astro"],
-    "contractClassesHonored": <count>
-  },
-  "files": [
-    "src/pages/products/index.astro",
-    "src/pages/products/[slug].astro",
-    "src/components/ProductCard.astro",
-    "src/pages/cart.astro",
-    "src/pages/thank-you.astro"
-  ]
-}
-```
-
-### Scope: `services-pages`
-
-All bookings-facing pages designed together for visual coherence. **Canonical templates exist** at `<SKILL_ROOT>/references/astro/templates/bookings/` — adapt them (copy, headings, styling); do not re-author the SDK/booking-flow wiring (`references/astro/bookings/SERVICES_PAGES.md` is the wiring spec).
-
-**Files:** `src/pages/services/index.astro`, `src/pages/services/[slug].astro`, `src/pages/booking-confirmation.astro`
-
-**Services listing (`/services`):**
-- Page heading + optional brand tagline
-- Service grid using the `service-grid` class, one `ServiceCard` per service (`service-card` class — image/placeholder, name, tagline, duration + price row)
-- Bind the live `services.queryServices` query (per `references/astro/bookings/SERVICES_PAGES.md`); brand-contextual empty state if it returns nothing
-
-**Service detail (`/services/[slug]`):**
-- `container-reading` width (never a bare `max-w-<size>`); optional banner image **only when the service has media** (image-less is the common seed case — no fixed-ratio placeholder)
-- Title, tagline, duration + price row, description
-- "Book this service" section mounting the `ServiceBookingFlow` island (`client:only="react"`, threads `serviceType`) — the week calendar uses the `availability-*` classes (week strip + `availability-day`), slots use `time-slot` classes (`--available`/`--selected`), and the form uses the `booking-*` family
-
-**Booking confirmation (`/booking-confirmation`):**
-- `max-w-prose`, centered; "Thank you for booking" headline + the service name and time (read from the `service`/`startDate` query params) + a link back to `/services`. No re-fetch, no cancel UI (manage/cancel is out of scope).
-
-### Scope: `blog-pages`
-
-Blog feed listing and post detail designed together.
-
-**Files:** `src/pages/blog/index.astro`, `src/pages/blog/[slug].astro`
-
-**Blog listing (`/blog`):**
-- Page heading
-- Post grid/list using `blog-feed` class
-- 3 placeholder post cards using `blog-post-card` class (title, date, excerpt, cover image placeholder)
-
-**Blog post detail (`/blog/[slug]`):**
-- Post header with title, date, author, cover image placeholder
-- Body area with `blog-post` and `blog-post-body` classes
-- Meta section with `blog-post-meta` class (tags, share links)
-- Good reading typography (max-width prose container, comfortable line height)
-
-**Return:**
-```json
-{
-  "status": "complete",
-  "phase": "designer-blog-pages",
-  "scope": "blog-pages",
-  "data": {
-    "pagesDesigned": ["blog/index.astro", "blog/[slug].astro"],
-    "contractClassesHonored": ["blog-feed", "blog-post-card", "blog-post", "blog-post-body", "blog-post-meta"]
-  },
-  "files": ["src/pages/blog/index.astro", "src/pages/blog/[slug].astro"]
-}
-```
-
-### Scope: `contact-page`
-
-Contact page with form placeholder.
-
-**Files:** `src/pages/contact.astro`
-
-**Contact page:**
-- Page heading and descriptive text
-- Contact CTA section using `contact-cta` class (if on home, this mirrors the home CTA's visual language)
-- Form area — mount the `ContactForm.tsx` island (written by Phase 3 Components) styled to the brand, per `references/astro/forms/CONTACT_FORM.md`. Style a complete form layout (name, email, message fields, submit button) so the page reads as finished even before submissions wire up.
-- Optional: map embed placeholder, business hours, address (if brand context suggests it)
-
-**Return:**
-```json
-{
-  "status": "complete",
-  "phase": "designer-contact-page",
-  "scope": "contact-page",
-  "data": {
-    "pagesDesigned": ["contact.astro"],
-    "contractClassesHonored": ["contact-cta"]
-  },
-  "files": ["src/pages/contact.astro"]
-}
-```
-
----
-
-## Return Contract
-
-At the end of your work, emit a structured JSON block per `../../shared/RETURN_CONTRACT.md`. Do **not** write sidecar files to `.wix/logs/*`.
-
-The JSON block MUST be the **last** content in your message — the parent parses it as the last fenced JSON. No trailing prose after the closing ` ``` `.
-
-## Anti-Patterns (apply to all page scopes)
-
-| WRONG | CORRECT |
-|-------|---------|
-| Author a `.tsx` React island in a page scope | Phase 3 Components writes the islands; the route only **mounts** them (`client:load`) |
-| Ship hardcoded data arrays as the final page | Query live SDK data in frontmatter (per the vertical reference) and bind it; hardcoded shapes are only a fallback for empty queries |
-| Write `global.css` or `@theme` tokens | The Composer owns `global.css`; you consume the published token contract |
-| Invent global semantic classes for layout/spacing/typography (`.featured-section`, `.page-header`) | Use Tailwind utilities derived from `@theme` tokens at the call site (`<section class="py-24">`); see `../../shared/STYLING.md` |
-| Override `global.css` rules from page `<style>` blocks | Pages can add co-located styles for one-off decoration; never override Composer-owned global classes |
-| HTML `<!-- comment -->` in `.astro` frontmatter | Use `//` or `/* */` — frontmatter is TypeScript |
-| Use external placeholder image services (picsum, unsplash) | Use colored `<div>` placeholders with `data-decorative-slot` — the orchestrator injects Image Phase 1 URLs later |
-| Write `components-<pack>.css` | Phase 3 Components creates that file — page scopes must not write it |
-| Leave a section empty when a query returns nothing | Render a brand-contextual fallback / empty state so the page is always reviewable |
-| Use default Tailwind colors (`bg-blue-500`, `text-gray-200`) | Use brand `@theme` tokens (`bg-bark`, `text-cream`) — defaults expose that it's AI-generated |
-| Generic unstyled HTML | Brand-first design — every element reflects the aesthetic direction |
-| Fixed-width layouts | Responsive: mobile-first, breakpoints at 320/768/1024px |
-| `ls src/`, `Glob src/**` to discover files | Your prompt lists every file and class contract. Write directly. |
-| Read a shared file to get brand or verticals | Every field is in your prompt |
-| Hardcode an external `<img src="https://...">` for product/content images | Resolve entity images from the live record (`media.getScaledToFillImageUrl(...)`) in this same scope; **decorative** images use the `data-decorative-slot` mechanism |
-| Omit `data-decorative-slot` on hero/about/background placeholders | Every decorative image placeholder MUST carry a slot attribute — the orchestrator's injection pass depends on it (common rule #7) |
-| Add a hero CTA / footer link to a disabled-pack route | Disabled packs (gift-cards) are dormant — no entry points to their routes |
-| ProductCard with flat props (`name`, `price`, `slug` as separate props) | Single `product` object prop: `{ product }` — Phase 4 passes the full Wix product object |
-| Wrap CartBadge in `<a>` or add cart SVG icons in `nav-actions` | Leave `nav-actions` empty — CartBadge renders its own `<a>` link; nesting `<a>` tags produces duplicate icons |
-
-## Coordination with other agents
-
-| Agent | Relationship | Rule |
-|-------|-------------|------|
-| Composer (design-system) | Wrote `global.css`, `Layout.astro`, `Navigation.astro`, `Footer.astro`, the `@theme` tokens | You consume the token contract and wrap pages in its `Layout`; you never rewrite those files |
-| Phase 3 Components (stores/bookings/blog/forms) | Writes React islands referencing contract classes + `components-<pack>.css` | They own islands + scoped CSS; the route references contract classes in markup and mounts the islands, no overlap |
-| Per-vertical reference (`references/astro/<vertical>/`) | Supplies the exact SDK queries + wiring the merged route binds | Apply this design spec **and** that vertical's queries together in one write — there is no second pass |
-| Image agent (Image Phase 1) | Returns decorative URLs in `data.slots` | Emit `data-decorative-slot="<key>"` placeholders; the orchestrator injects the `<img>` once Image Phase 1 returns |
-| Image agent (Image Phase 2) | PATCHes entity images onto products/posts via REST | No direct interaction — images flow through product/post records that Phase 4 queries |
-
-## File ownership
-
-The merged Phase 4 `pages` scope owns each route file **end to end** — visual structure **and** data wiring, written in a single pass. There is no separate page-designer agent that writes a file for a later scope to rewrite; this doc is the visual-design spec the merged author applies alongside its vertical's SDK queries (`references/astro/<vertical>/`). Each route file therefore has exactly **one** writer (its `pages` scope), which removes the cross-phase double-write the older placeholder-then-rewrite model carried.
-
-The shared shells the route composes into — `Layout.astro`, `global.css` (Composer), and the marker-patched `Navigation.astro` / `index.astro` / `components-<pack>.css` (pre-copied or patched by the serialized shell-patcher agents) — are NOT owned by a private-file route scope (see "Coordination" above and BUILD-astro.md § "Step 4.5", the serialized shell chain).

package/skills/wix-headless/references/astro/ecom/CART_PAGES.md

@@ -1,119 +0,0 @@
-# Phase 4 Cart Pages — Ecom
-
-Scope: `cart-checkout` (the ecom `pages` scope) — the **pages** portion of the ecom **merged build agent** (the build wave), written *after* its `components`. Mounts `CartView` island on the cart page, wires the thank-you page, and mounts `CartBadge` in `Navigation.astro` (at the `<!-- nav:actions -->` marker). **Because it patches the shared `Navigation.astro` shell, the ecom build agent runs in the build wave's serialized shell chain** — never concurrent with the other Navigation/index patchers (stores `pages-home-and-nav`, gift-cards, blog), so concurrent marker edits can't collide (`BUILD-astro.md` § "Step 4.5").
-
-## Scope
-
-Files this agent OWNS (each written once — designer visual spec + live wiring together):
-
-- `src/pages/cart.astro` — mount `CartView.tsx` (client-only, no server-side cart fetch)
-- `src/pages/thank-you.astro` — read `orderId` from URL, fire `Purchase` event
-
-Files this agent PATCHES (does NOT rewrite) — only at its own marker:
-
-- `src/components/Navigation.astro` — mount `CartBadge` in the `nav-actions` area (`<!-- nav:actions -->`). Stores `pages-home-and-nav` patches the same file at `<!-- nav:links -->`; the serialized shell chain keeps these from colliding.
-
-Files this agent MUST NOT touch:
-- `src/components/CartView.tsx`, `src/components/CartBadge.tsx` — the ecom islands; written earlier in this same merged agent (the `components` scope)
-- Any product page, home page, or stores-specific component
-- `global.css`, any designed component
-
-## Critical rules
-
-1. **No server-side cart fetch** — cart is per-visitor and must not break SSR caching. `CartView` fetches its own data on mount.
-2. **Mount `CartView` with `client:load`** — no props needed, the island is self-contained.
-3. **Fire `Purchase` event in `thank-you.astro`** only when `?orderId=` is present.
-4. **Mount `CartBadge` in `Navigation.astro`** (not Layout.astro, not a page-specific header).
-5. **No HTML comments in `.astro` frontmatter** — frontmatter is TypeScript.
-6. **Preserve designer layout and classes.** Only mount islands and wire data; do not restructure markup.
-7. **Do NOT add static HTML alongside `<CartView>`** — the island handles empty/loading/cart states internally.
-
-## Implementation
-
-### 1. `src/pages/cart.astro`
-
-Use template `templates/cart.astro`.
-
-Mounts `CartView` as a client-only island. **No server-side cart fetch** — cart data is per-visitor and would break SSR caching. CartView fetches the cart client-side on mount. Key requirements:
-
-- **No `currentCart` import in frontmatter** — do not fetch cart data server-side
-- Mount `<CartView client:load />` — no props needed, the island fetches its own data
-- Preserve whatever the designer wrote around the mount (headings, breadcrumbs, section wrappers)
-- Do NOT add static HTML alongside `<CartView>` — the island handles empty/loading/cart states internally
-
-### 2. `src/pages/thank-you.astro`
-
-Use template `templates/thank-you.astro`.
-
-Wix redirects here after successful checkout with `?orderId=<id>`. Fires `Purchase` analytics event when orderId is present. Preserve whatever the designer wrote around the order confirmation content (headings, layout wrappers). The key requirements:
-
-- Read `orderId` from URL search params
-- Display order confirmation with the orderId
-- Fire `Purchase` event via the analytics helper (client-side script)
-- Only fire when `orderId` is present — refreshing without it should not re-fire
-
-### 3. Mount CartBadge in `Navigation.astro`
-
-Mount `CartBadge` inside the `nav-actions` area. The designer creates this with a `<slot name="actions" />` or similar placeholder. Because Navigation is in the shared Layout, the badge appears on every page.
-
-```astro
----
-// Add to Navigation.astro frontmatter:
-import CartBadge from "./CartBadge.tsx";
----
-
-<!-- Replace the nav-actions slot with the CartBadge island: -->
-<div class="nav-actions">
-  <CartBadge client:only="react" />
-</div>
-```
-
-Use `client:only="react"` — never SSR the badge. SSR would render `count: 0` (sessionStorage is a browser-only API), then hydration would read the cached count and flip to the real number, causing a visible blink on every page navigation. Skipping SSR means the badge renders once on the client with the cached count already populated. No flash.
-
-## Checkout flow summary
-
-CartView's `handleCheckout` runs:
-
-```
-Cart page → "Proceed to Checkout"
-  → currentCart.createCheckoutFromCurrentCart({ channelType: WEB })
-  → redirects.createRedirectSession({ ecomCheckout: { checkoutId }, callbacks: { thankYouPageUrl, cartPageUrl } })
-  → window.location.href = redirectSession.fullUrl
-  → User completes payment on Wix-hosted checkout
-  → Redirect back to /thank-you?orderId=<id>
-```
-
-**Going-live note** (emitted by the skill, not this agent):
-> Checkout is hosted by Wix and will show "we aren't accepting payments" until: (1) upgrade to premium eCommerce plan, (2) connect a payment provider.
-
-## Analytics fired from this scope
-
-| Event | Fires from | When | Payload |
-|-------|------------|------|---------|
-| `Purchase` | `thank-you.astro` | On mount when `?orderId=` is present | `{ id: orderId, origin: "Thank You Page" }` |
-
-`RemoveFromCart` and `InitiateCheckout` fire from `CartView.tsx` (owned by `ecom-shared`).
-
-## Return format
-
-```json
-{
-  "status": "complete",
-  "phase": "cart-checkout",
-  "scope": "cart-checkout",
-  "summary": "Mounted CartView (client-only fetch); wired Purchase event; mounted CartBadge in Navigation",
-  "data": {
-    "pagesWired": 2,
-    "cartViewMounted": true,
-    "purchaseEventWired": true,
-    "cartBadgeMounted": true,
-    "analyticsEvents": ["Purchase"]
-  },
-  "files": [
-    "src/pages/cart.astro",
-    "src/pages/thank-you.astro",
-    "src/components/Navigation.astro"
-  ],
-  "errors": []
-}
-```

package/skills/wix-headless/references/astro/ecom/CART_WIRING.md

@@ -1,103 +0,0 @@
-# Phase 3 Components — Ecom (TSX)
-
-This is the **components** portion of the ecom **merged build agent** (the build wave — `BUILD-astro.md` § "Step 4.5"). Your agent writes these islands **first**, then the ecom pages (`cart.astro`, `thank-you.astro`) that mount 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-ecom.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):
-
-- `src/components/CartView.tsx` — React island; full cart display + checkout redirect
-- `src/components/CartBadge.tsx` — React island; nav-wide cart count badge
-
-Files this agent MUST NOT touch:
-- `src/styles/components-ecom.css` — owned by the **`components-css`** sibling scope (see `./COMPONENTS_CSS.md`). Reference its class names; do not write the file.
-- Any `.astro` page — designed and later rewritten by other scopes
-- `src/styles/global.css` — owned by designer foundation
-- `src/layouts/Layout.astro` — owned by designer foundation
-- Any stores-specific component (AddToCartButton, ProductPurchase, etc.)
-
-## Coordination: design tokens
-
-Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave).
-
-For layout/spacing/typography, compose Tailwind utilities derived from `@theme` tokens at the call site (`<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-12">`). For published global semantic classes (`cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — the compound + interactive-state patterns), use the ACTUAL class name verbatim. Row-internal class names (`cart-item-qty`, `qty-btn`, etc.) come from the template — keep them as-is and live in `components-ecom.css`. See `references/shared/STYLING.md` and `references/shared/IMPLEMENTER.md` § "Styling: tokens-first, classes as exception".
-
-## 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/components/CartView.tsx`
-
-Use template `templates/CartView.tsx`.
-
-Full cart display with two-column layout, quantity editing, remove, unavailable item detection, and checkout redirect. **No server-side props** — cart is per-visitor and fetched client-side on mount to keep pages SSR-cache-friendly. Key behaviors:
-
-- **Always use `currentCart` APIs** — never the `cart` namespace that requires a cart ID
-- **Image resolution** — `resolveCartImage()` handles `wix:image://` strings (SDK returns image as a string, not an object)
-- **Description lines** — `formatDescriptionLine()` handles both `plainText` and `colorInfo` types
-- **Per-line price display** — `fullPrice` and `price` are per-unit (shown side by side; `fullPrice` is struck through when an automatic discount is applied to that line); `lineItemPrice` is total (shown below only when qty > 1)
-- **Clickable product link** — the image and product name link back to the product detail page. `item.url` shape varies by caller: the `@wix/ecom` SDK returns it as an absolute URL **string** (e.g. `https://<site>.wixsite.com/<name>/product-page/<slug>`), while REST returns an object `{ relativePath, url }`. `resolveProductHref` accepts both, extracts the slug after `/product-page/`, and rewrites to the headless `/products/<slug>` route. Link is suppressed on unavailable lines (nothing to navigate to for NOT_FOUND/NOT_AVAILABLE items).
-- **Cart-level totals + discount surfaces (API-sourced)** — `extractSummary()` reads `cart.priceSummary.{subtotal, discount, total}` and `cart.appliedDiscounts[].discountName` in one pass. Three distinct surfaces, each sourced directly from the API (no client-side amount math):
-   1. `cart-discount` row — amount + optional name — rendered when `priceSummary.discount` is populated (coupons, cart-level promos).
-   2. `cart-applied-discounts` row — name-only — rendered when `priceSummary.discount` is empty but `appliedDiscounts[].discountName` is populated. This is the common case for **line-item automatic discounts**, where Wix bakes the discount into each line's `price` (with `fullPrice` preserved for the strikethrough). The per-line savings amount already shows inline via the `cart-item-full-price`/`cart-item-unit-price` strikethrough; the summary row just names the promotion.
-   3. `cart-total` row — rendered when `priceSummary.total` differs from `priceSummary.subtotal`.
-  If `priceSummary.subtotal` is missing (some early-stage carts return an empty summary before checkout creation), the subtotal is computed client-side from `lineItemPrice.amount` — do not leave the slot blank. Do NOT aggregate line-item savings into a summary row; shoppers see the strikethrough inline and that is the API's canonical visualization.
-- **Availability** — `isItemUnavailable()` checks for `NOT_AVAILABLE` and `NOT_FOUND` status; hides qty selector, blocks checkout
-- **Optimistic UI** — quantity changes and item removal update local state immediately before the API responds. Quantity changes are debounced (300ms) so rapid clicks coalesce into a single request. On API error, the cart reconciles from the server via `loadCart()`
-- **Instant re-render via sessionStorage snapshot** — every successful cart fetch/update writes `{ lineItems, summary }` to `sessionStorage[CART_CACHE_KEY]`. On mount, CartView reads the snapshot synchronously and renders it before the authoritative fetch completes. Eliminates the empty/loading flash when re-navigating to `/cart`. Per-tab scope (sessionStorage not localStorage) so logout / shared-device scenarios can't leak stale carts to a different identity.
-- **Dispatches `cart-updated`** events so CartBadge updates instantly
-- **LineItem type** — local structural type mirroring the fields the component consumes. `_id` is declared `string | null | undefined` to match `@wix/ecom`'s `currentCart` return so `cart.lineItems as LineItem[]` type-checks cleanly. If you add new fields, mirror the SDK nullability or narrow at the use site.
-
-Class names used (template provides them — do not invent):
-- **Global semantic classes** (in `global.css`, designer-owned): `cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — compound patterns + interactive states
-- **Row-internal classes** (in `components-ecom.css`, written by this scope): `cart-item-qty`, `qty-btn`, `qty-value`, `cart-item-unavailable`, `cart-item-actions`, `cart-item-prices`, `cart-item-full-price`, `cart-item-unit-price`, `cart-item-line-total`, `cart-item-remove`, `cart-item-image-link`, `cart-item-name-link`, `cart-discount`, `cart-discount-name`, `cart-discount-amount`, `cart-applied-discounts`, `cart-applied-discounts-name`, `cart-item-option`, `cart-item-modifiers`
-- **Layout/spacing in markup as utilities**: `cart-grid` → `<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-12 md:gap-16 md:items-start">`; `cart-items` → `<div class="flex flex-col gap-6">`; `cart-item` → `<div class="flex gap-6 pb-6 border-b border-rule last:border-0">`; `cart-subtotal` → `<div class="flex justify-between items-baseline">`; `cart-item-image` → utilities; `cart-item-info` → utilities; `cart-item-name` → `class="font-display text-lg leading-tight"`
-
-### 2. `src/components/CartBadge.tsx`
-
-Use template `templates/CartBadge.tsx`.
-
-Mounted once in `Navigation.astro` (by the `cart-checkout` scope). Shows cart item count; listens for `cart-updated` custom event.
-
-**No `initialCount` prop.** Cart is per-visitor — server-rendering the count breaks SSR caching. On mount, CartBadge reads the sessionStorage snapshot that CartView maintains (same `CART_CACHE_KEY`) to seed the initial count without a visible zero-flash between page navigations, then fetches fresh from the SDK and reconciles. If no snapshot exists (first-ever page load), count starts at 0 like before.
-
-**Mount with `client:only="react"`, never `client:load`.** sessionStorage is browser-only, so SSR would render `count: 0`, then hydration would read the cache and flip to the real number — a visible blink on every page navigation. `client:only` skips SSR entirely; the badge renders once on the client with the cached count already populated.
-
-Contract keys: `cartBadge`, `cartBadgeCount`
-
-### 3. `src/utils/analytics.ts` — not owned by this scope
-
-> `analytics.ts` is a shared utility (canonical source `shared-utilities/analytics.ts`, seeded to `src/utils/analytics.ts`). Import from it (`import { trackEvent } from "../utils/analytics"`) but do not write it.
-
-### 4. `src/styles/components-ecom.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 files; the CSS sibling defines the rules.
-
-## Return format
-
-```json
-{
-  "status": "complete",
-  "phase": "ecom-components",
-  "scope": "components",
-  "summary": "Wrote CartView and CartBadge from templates (CSS handled by components-css sibling)",
-  "data": {
-    "islands": ["CartView.tsx", "CartBadge.tsx"]
-  },
-  "files": [
-    "src/components/CartView.tsx",
-    "src/components/CartBadge.tsx"
-  ],
-  "errors": []
-}
-```