@wix/agent-skills 1.7.0 → 1.9.0

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

@@ -1,15 +1,17 @@
 # Phase 3 Components — Back in Stock (Stores)
 
-Split across the stores `components` scope (TSX/util files) and the `components-css` sibling (CSS rules). The matching Phase 4 wiring lives in `PRODUCT_PAGES.md` (SSR probe import + new props on `<ProductPurchase>`).
+The stores `components` scope writes the TSX/util files; the CSS rules ship in the **pre-copied** `components-stores.css` template (no agent authors them). The matching page wiring lives in `PRODUCT_PAGES.md` (SSR probe import + new props on `<ProductPurchase>`). Both the components and that page wiring run inside the **same stores merged build agent** (the build wave), components first.
 
 ## Scope
 
 Files written for back-in-stock, by scope:
 
 **`components` scope** (see `./SHARED_WIRING.md`):
-- `src/utils/back-in-stock.ts` — SSR-elevated probe of the Wix back-in-stock service, plus the canonical Stores app id constant
 - `src/components/BackInStockForm.tsx` — React island that posts via `@wix/ecom`'s `backInStockNotifications.createBackInStockNotificationRequest`
 
+**Pre-copied by the orchestrator** (do NOT author — same treatment as `categories.ts`):
+- `src/utils/back-in-stock.ts` — SSR-elevated probe of the Wix back-in-stock service, plus the canonical Stores app id constant. Pre-copied into the project in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"). **Import** `getBackInStockEnabled`/the app-id constants from `../utils/back-in-stock`; never `Write` it yourself (racing the pre-copy trips the harness staleness guard).
+
 **`components-css` scope** (see `./COMPONENTS_CSS.md`):
 - `src/styles/components-stores.css` — appends the back-in-stock form CSS rules at the end of the file (see § 3 below)
 
@@ -45,9 +47,9 @@ This scope uses **template files** instead of inline code. For each file below:
 
 Do NOT modify logic, imports, the bare-fields request shape, or the app-id constants.
 
-### 1. `src/utils/back-in-stock.ts`
+### 1. `src/utils/back-in-stock.ts` — pre-copied, not owned by this scope
 
-Use template `templates/back-in-stock.ts`.
+> Pre-copied by the orchestrator in the build-wave pre-batch (BUILD-astro.md § "Step 4.5") — same treatment as `categories.ts`. **Import** from `../utils/back-in-stock`; do NOT write it yourself. The exports below are documented here so callers (the form island, the `[slug].astro` probe) know the surface.
 
 Exports:
 - `WIX_STORES_BACK_IN_STOCK_APP_ID` — string constant. Use this for the `catalogReference.appId` in the form.
@@ -150,7 +152,6 @@ The full components scope return must mention back-in-stock:
   "summary": "Wrote stores islands, scoped CSS, back-in-stock probe + form",
   "data": {
     "islands": ["ProductPurchase.tsx", "AddToCartButton.tsx", "BackInStockForm.tsx"],
-    "utils": ["back-in-stock.ts"],
     "scopedCssFile": "src/styles/components-stores.css",
     "backInStockWired": true
   },
@@ -159,7 +160,6 @@ The full components scope return must mention back-in-stock:
     "src/components/AddToCartButton.tsx",
     "src/components/ProductPurchase.tsx",
     "src/components/BackInStockForm.tsx",
-    "src/utils/back-in-stock.ts",
     "src/styles/components-stores.css"
   ],
   "errors": []

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

@@ -1,8 +1,8 @@
 # Phase 4 Category Pages — Stores
 
-Scope: `pages-categories`. Launched in **Step 7** alongside `pages-products` and `pages-home-and-nav`. This scope writes the dedicated category landing route and the shared `<CategoryRail/>`. The `categories.ts` helper that all three scopes import is **pre-copied by the orchestrator before this phase** (BUILD.md Step 7 pre-batch) — do NOT write it here.
+Scope: `pages-categories` — written by the stores **merged build agent** (the build wave) *before* its `pages-products` scope, so `<CategoryRail/>` is on disk before that scope mounts it. This scope writes the dedicated category landing route and the shared `<CategoryRail/>`. The `categories.ts` helper is **pre-copied by the orchestrator in the build-wave pre-batch** (BUILD-astro.md § "Step 4.5") — do NOT write it here.
 
-**Dispatch:** all three stores Phase-4 scopes are dispatched in parallel — Astro resolves the cross-file imports at build time (Step 8). The orchestrator does not need to serialize them. Each scope only needs its own declared files to exist by the time `astro build` runs; `categories.ts` is already on disk from the pre-batch.
+**Within-agent order:** the merged stores agent writes `components` → `pages-categories` (this scope) → `pages-products`. `pages-home-and-nav` is a *separate* serialized agent (it patches the shared shells) and resolves `<CategoryRail/>` at build time (Step 8). Each scope only needs its own declared files to exist by the time `astro build` runs.
 
 ## Scope
 
@@ -23,7 +23,7 @@ Files this agent MUST NOT touch:
 ## Inputs (from parent prompt)
 
 - **Phase 1 return data** — `categories: []`. Phase 1 does not seed categories (they're merchant-driven). This scope still writes the helper + rail + route — they're harmless when no categories exist, and they light up automatically once the merchant creates visible categories with items in the dashboard. `listStoreCategories()` queries the API live at SSR time (5-min TTL cache), so no redeploy is needed when categories are added later.
-- **Design tokens** — the full `designTokens` JSON is inlined in your prompt (same shape Designer returned). Page header / breadcrumbs / pill / pagination styling should follow `references/shared/STYLING.md` (utilities derived from tokens, semantic classes only for primitives).
+- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk). Page header / breadcrumbs / pill / pagination styling should follow `references/shared/STYLING.md` (utilities derived from tokens, semantic classes only for primitives).
 - **Designer output summary** — confirm `Layout.astro` already includes `<ClientRouter />`, `transition:persist` markers on nav/footer, and the `[data-nav-progress]` element + after-swap hook. If any of those is missing, return `status: "partial"` with `errors: [{ code: "DESIGNER_LAYOUT_MISSING_TRANSITIONS", path: "src/layouts/Layout.astro" }]`.
 
 ## Critical rules (all must be honored)
@@ -40,7 +40,7 @@ Files this agent MUST NOT touch:
 
 ## Writing the templates
 
-Read each template at `templates/stores/` and write it verbatim to the corresponding `src/` path, with three small adjustments. (`categories.ts` is **not** in this list — the orchestrator pre-copies it; you only import its helpers.)
+Read each template at `references/astro/templates/stores/` and write it verbatim to the corresponding `src/` path, with three small adjustments. (`categories.ts` is **not** in this list — the orchestrator pre-copies it; you only import its helpers.)
 
 | Template path | Site path |
 |---|---|

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

@@ -1,6 +1,6 @@
 # Phase 3 Components-CSS — Stores
 
-Sibling of the `components` scope. Launched in **Step 4.5** in the same concurrent batch — runs in parallel with the TSX/Astro work, ecom and gift-cards components, and Image Phase 2.
+**This stylesheet is pre-copied from the skill template by the orchestrator** (build-wave pre-batch, BUILD-astro.md § "Step 4.5") — there is no `components-css` subagent to dispatch. This file documents the CSS for reference so the stores `components` scope (in the merged build agent) knows the class-name surface it targets.
 
 ## What this scope owns
 
@@ -23,7 +23,7 @@ You only need:
 2. **`<SKILL_ROOT>/references/shared/STYLING.md`** — the styling-contract conventions (how to use `@apply`, the `@theme` token utilities, the no-default-Tailwind-colors rule, and the global-vs-scoped CSS ownership boundary).
 3. **`<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`** — the return JSON shape.
 4. **`src/styles/global.css`** in the project — read to audit for stores-class leaks (see § "Global-CSS leak audit" below).
-5. **Design tokens (inline in your prompt)** — the parent skill pastes the full `designTokens` JSON into your dispatch prompt. Use it directly; do NOT read `.wix/design-tokens.css` or `.wix/site.d.ts` from disk.
+5. **Design tokens (on disk)** — read the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) from `.wix/design-tokens.css` (gate-verified present before the wave). They are NOT inlined in your prompt.
 
 You do NOT need to read `INSTRUCTIONS.md`, `SHARED_WIRING.md`, `BACK_IN_STOCK.md`, the TSX templates, the back-in-stock util, or any other reference. Skipping those reads is the point of the split — they would consume tokens for context this scope doesn't use.
 
@@ -86,7 +86,7 @@ Write the adapted CSS to `src/styles/components-stores.css`. The first line must
 
 ## Coordination: design tokens
 
-Your parent prompt includes the design tokens JSON inline. Use it directly — do **not** read `.wix/design-tokens.css` or `.wix/site.d.ts` from disk and do not poll for them.
+Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave) — they are NOT inlined in your prompt.
 
 ## Return format
 

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

@@ -1,8 +1,8 @@
 # Phase 4 Home Page + Nav — Stores
 
-Scope: `pages-home-and-nav`. Launched in **Step 7**; imports the orchestrator-pre-copied `categories.ts` helper (and the rail `pages-categories` writes — resolved at build time). Patches the home page's stores-related placeholder data with live `productsV3` queries AND inserts the Shop submenu (categories list) into the persisted Navigation.
+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 (e.g. gift-cards) 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 shell-patching scopes so concurrent marker edits don't collide — BUILD.md Step 7.)
+> **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
 
@@ -21,7 +21,7 @@ Files this agent MUST NOT touch:
 ## 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** — the full `designTokens` JSON is inlined in your prompt 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.
+- **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.
 

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

@@ -1,10 +1,10 @@
 # Phase 4 Product Pages — Stores
 
-Scope: `product-pages`. Launched in **Step 7** after designer page scopes have written placeholder `.astro` files. This scope rewrites the product listing, product detail, and ProductCard component with live `productsV3` queries.
+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 (rewrites from designer output):
+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
@@ -12,17 +12,17 @@ Files this agent OWNS (rewrites from designer output):
 
 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 `pages-cart-checkout`
+- `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 `pages-categories`. **Import** from `../../components/CategoryRail.astro`; never `Write` it. If it's not on disk yet when you go to mount it, that means the orchestrator dispatched scopes out of order — return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "src/components/CategoryRail.astro" }]` (never defensively `Write` it yourself — `pages-categories` is the only writer, and racing it trips the harness staleness guard).
-- `src/utils/categories.ts` — pre-copied by the orchestrator before Phase 4 (BUILD.md Step 7 pre-batch). **Import** `listStoreCategories`/etc. from `../../utils/categories`; never `Write` it.
+- `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** — the full `designTokens` JSON is inlined in your prompt for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens (`class="py-4xl flex flex-col gap-md 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 output summary** — paths of existing `products/index.astro`, `products/[slug].astro`, `ProductCard.astro` with placeholder data.
+- **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-4xl flex flex-col gap-md 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)
 
@@ -68,9 +68,9 @@ Do NOT modify logic, imports, SDK calls, `wixMetadata` export, or prop-passing.
 
 Use template `templates/products/index.astro`.
 
-Preserves the designer's page structure (class names, layout) and replaces the placeholder products array with 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.
+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 written by `pages-categories`.** Both `<CategoryRail/>` and `listStoreCategories` come from files this scope must NOT write — they're owned by the `pages-categories` scope. Import paths: `../../components/CategoryRail.astro` and `../../utils/categories`. If either import fails to resolve, return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "<missing path>" }]` — that means the orchestrator dispatched scopes out of order.
+> **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.
 

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

@@ -1,8 +1,8 @@
 # Phase 3 Components — Stores (TSX/Astro)
 
-Launched in **Step 4.5** (after Phase 2 Design System completes, parallel to any running designer page scopes). Writes code that depends on the **design tokens** but NOT on Phase 4 page markup. Finishes before the Phase 4 Pages scopes run in Step 7.
+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 lives in a sibling scope.** `src/styles/components-stores.css` is owned by the `components-css` scope (see `./COMPONENTS_CSS.md`), which runs concurrently with this one in the same Step 4.5 batch. This scope does NOT write the CSS file. Reference contract class names from the design tokens here; the CSS sibling defines the rules.
+> **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
 
@@ -17,14 +17,15 @@ 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
-- Any `.astro` page — those are designed and later rewritten by other scopes
+- `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
 
-Your parent prompt includes the design tokens inline. Use it directly — do **not** read `.wix/design-tokens.css` + `.wix/site.d.ts` from disk and do not poll for it. The parent skill serializes your launch behind designer foundation specifically so the contract is already available in your prompt when you start.
+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.
 

package/skills/wix-headless/references/astro/templates/Footer.astro

@@ -1,6 +1,6 @@
 ---
 // ── Composer skeleton: src/components/Footer.astro ────────────────────────────
-// Substitutions (see COMPOSE.md § "5. Footer.astro"):
+// Substitutions (see compose.mjs):
 //   {{brand.name}} — brand name for the wordmark + copyright.
 //   {{shell.footerTagline}} — short brand-voice tagline from data.shell.
 //   {{nav.links}} — same inlined Navigation links array (mirror/subset);

package/skills/wix-headless/references/astro/templates/Layout.astro

@@ -2,7 +2,7 @@
 // ── Composer skeleton: src/layouts/Layout.astro ──────────────────────────────
 // Fully replaces the scaffold's bare stub. The <script> below and the View
 // Transitions wiring are LITERAL fixed bulk — do not re-author. Composer's only
-// substitutions (see COMPOSE.md § "3. Layout.astro"):
+// substitutions (see compose.mjs):
 //   {{components-css-imports}} — one `import '../styles/components-<pack>.css';`
 //        per pack in "Packs with components" (omit entirely when none).
 //   {{fonts.googleHref}} — the Google Fonts <link> href built from designTokens

package/skills/wix-headless/references/astro/templates/Navigation.astro

@@ -1,6 +1,6 @@
 ---
 // ── Composer skeleton: src/components/Navigation.astro ────────────────────────
-// Substitutions (see COMPOSE.md § "4. Navigation.astro"):
+// Substitutions (see compose.mjs):
 //   {{shell.navBrandMark}} — brand mark / wordmark text from data.shell.
 //   {{nav.links}} — one <a href={href}>{label}</a> per entry in the inlined
 //        Navigation links array, labels VERBATIM (no editorial rebrands). Render

package/skills/wix-headless/references/astro/templates/astro.config.mjs

@@ -3,7 +3,7 @@
 // scaffold's generated astro.config.mjs varies (integrations args, image.domains,
 // vite.server settings differ run to run). Composer must NOT overwrite it with
 // this file — it applies exactly two mutations to the scaffold's own config and
-// preserves everything else (see COMPOSE.md § "2. astro.config.mjs"):
+// preserves everything else (see compose.mjs):
 //
 //   (1) register the Tailwind v4 Vite plugin   → vite.plugins: [tailwindcss()]
 //   (2) fix the bare `process.env` reference    → globalThis guard (TS-safe)

package/skills/wix-headless/references/astro/templates/bookings/AvailabilityCalendar.tsx

@@ -0,0 +1,233 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { availabilityTimeSlots, eventTimeSlots } from "@wix/bookings";
+import type { SelectedSlot } from "./bookingDriver";
+
+// AvailabilityCalendar.tsx — client:only="react" island. A week calendar: a
+// 7-day strip with week navigation, then the picked day's time slots. This is
+// the usable shape — a flat list of every slot with time-only labels leaves the
+// visitor unable to tell which day a slot is on.
+//
+// SDK calls run ambiently (the @wix/astro visitor client), like the ecom
+// CartView island — no createClient/OAuthStrategy here. On an own/own-build SPA
+// acquire a visitor client (OAuthStrategy) and call the same functions on it.
+//
+// Branches on serviceType:
+//   APPOINTMENT → availabilityTimeSlots.listAvailabilityTimeSlots() (serviceId is
+//                 a single GUID string; slots carry scheduleId).
+//   CLASS       → eventTimeSlots.listEventTimeSlots() (serviceIds is an array;
+//                 slots carry eventInfo.eventId and NO scheduleId).
+// Re-export SelectedSlot from bookingDriver so the form/driver share one shape.
+export type { SelectedSlot } from "./bookingDriver";
+
+interface Props {
+  serviceId: string;
+  serviceName: string;
+  serviceType: "APPOINTMENT" | "CLASS";
+  onSlotSelected: (slot: SelectedSlot) => void;
+}
+
+const DAY_MS = 86_400_000;
+const HORIZON_WEEKS = 13; // how far "check next availability" probes forward
+
+const pad = (n: number) => String(n).padStart(2, "0");
+// Local date string YYYY-MM-DDThh:mm:ss (no Z) — availability expects local time.
+const localDateString = (d: Date) =>
+  `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+const tz = () => Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+const dateKey = (iso: string) => iso.slice(0, 10); // group slots by calendar day
+const timeLabel = (iso: string) =>
+  new Date(iso).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+
+const startOfDay = (d: Date) => { const n = new Date(d); n.setHours(0, 0, 0, 0); return n; };
+// Monday-start week containing `d`.
+const mondayOf = (d: Date) => {
+  const n = startOfDay(d);
+  const day = (n.getDay() + 6) % 7; // 0 = Monday
+  n.setDate(n.getDate() - day);
+  return n;
+};
+
+// Fetch one week of availability and group the slots by calendar day.
+const fetchWeek = async (
+  serviceId: string,
+  serviceType: "APPOINTMENT" | "CLASS",
+  weekStart: Date,
+): Promise<Record<string, SelectedSlot[]>> => {
+  const from = startOfDay(weekStart);
+  const to = new Date(from.getTime() + 7 * DAY_MS);
+  const timeZone = tz();
+  let raw: any[] = [];
+
+  if (serviceType === "CLASS") {
+    const result = await eventTimeSlots.listEventTimeSlots({
+      serviceIds: [serviceId], // CLASS API takes an array
+      fromLocalDate: localDateString(from),
+      toLocalDate: localDateString(to),
+      timeZone,
+      includeNonBookable: false,
+      cursorPaging: { limit: 100 },
+    });
+    raw = (result.timeSlots ?? []).map((s: any) => ({
+      serviceType: "CLASS" as const,
+      serviceId,
+      localStartDate: s.localStartDate,
+      localEndDate: s.localEndDate,
+      timezone: result.timeZone ?? timeZone,
+      eventId: s.eventInfo?.eventId, // session id — no scheduleId on event slots
+    }));
+  } else {
+    const result = await availabilityTimeSlots.listAvailabilityTimeSlots({
+      serviceId, // single GUID string — NOT an array
+      fromLocalDate: localDateString(from),
+      toLocalDate: localDateString(to),
+      timeZone,
+      bookable: true,
+      cursorPaging: { limit: 100 },
+    });
+    raw = (result.timeSlots ?? []).map((s: any) => ({
+      serviceType: "APPOINTMENT" as const,
+      serviceId,
+      localStartDate: s.localStartDate,
+      localEndDate: s.localEndDate,
+      timezone: result.timeZone ?? timeZone,
+      scheduleId: s.scheduleId,
+      locationId: s.location?._id, // the id field is _id, not .id
+      locationType: s.location?.locationType,
+    }));
+  }
+
+  const byDay: Record<string, SelectedSlot[]> = {};
+  for (const slot of raw) {
+    if (!slot.localStartDate) continue;
+    (byDay[dateKey(slot.localStartDate)] ||= []).push(slot);
+  }
+  return byDay;
+};
+
+export default function AvailabilityCalendar({ serviceId, serviceName, serviceType, onSlotSelected }: Props) {
+  const thisMonday = useMemo(() => mondayOf(new Date()), []);
+  const [weekStart, setWeekStart] = useState<Date>(thisMonday);
+  const [byDay, setByDay] = useState<Record<string, SelectedSlot[]>>({});
+  const [selectedDay, setSelectedDay] = useState<string | null>(null);
+  const [selectedKey, setSelectedKey] = useState<string | null>(null);
+  const [status, setStatus] = useState<"loading" | "ready" | "error" | "searching">("loading");
+
+  const days = useMemo(
+    () => Array.from({ length: 7 }, (_, i) => new Date(weekStart.getTime() + i * DAY_MS)),
+    [weekStart],
+  );
+  const atFirstWeek = weekStart.getTime() <= thisMonday.getTime();
+
+  const load = useCallback(async (start: Date) => {
+    setStatus("loading"); setSelectedKey(null);
+    try {
+      const grouped = await fetchWeek(serviceId, serviceType, start);
+      setByDay(grouped);
+      const firstDayWithSlots = Object.keys(grouped).sort()[0] ?? null;
+      setSelectedDay(firstDayWithSlots);
+      setStatus("ready");
+    } catch (err) {
+      console.error("[availability] list failed:", err);
+      setStatus("error");
+    }
+  }, [serviceId, serviceType]);
+
+  useEffect(() => { void load(weekStart); }, [weekStart, load]);
+
+  const shiftWeek = (deltaWeeks: number) =>
+    setWeekStart((prev) => startOfDay(new Date(prev.getTime() + deltaWeeks * 7 * DAY_MS)));
+
+  // Probe forward week-by-week for the next week that has any slots.
+  const checkNextAvailability = useCallback(async () => {
+    setStatus("searching");
+    let cursor = new Date(weekStart.getTime() + 7 * DAY_MS);
+    for (let i = 0; i < HORIZON_WEEKS; i++) {
+      try {
+        const grouped = await fetchWeek(serviceId, serviceType, cursor);
+        if (Object.keys(grouped).length > 0) {
+          setWeekStart(cursor); // triggers load() via the effect
+          return;
+        }
+      } catch { /* keep probing */ }
+      cursor = new Date(cursor.getTime() + 7 * DAY_MS);
+    }
+    setStatus("ready"); // nothing found within the horizon
+  }, [serviceId, serviceType, weekStart]);
+
+  const handleSelect = (s: SelectedSlot) => {
+    const id = s.serviceType === "CLASS" ? s.eventId : s.scheduleId;
+    if (!s.localStartDate || !id) return;
+    setSelectedKey(`${s.localStartDate}|${id}`);
+    onSlotSelected(s);
+  };
+
+  const weekLabel = `${days[0].toLocaleDateString([], { month: "short", day: "numeric" })} – ${days[6].toLocaleDateString([], { month: "short", day: "numeric" })}`;
+  const daySlots = selectedDay ? byDay[selectedDay] ?? [] : [];
+  const weekIsEmpty = status === "ready" && Object.keys(byDay).length === 0;
+
+  return (
+    <div className="availability-calendar">
+      <div className="availability-week-nav">
+        <button type="button" className="availability-nav-btn" onClick={() => shiftWeek(-1)} disabled={atFirstWeek} aria-label="Previous week">← Prev week</button>
+        <span className="availability-week-label">{weekLabel}</span>
+        <button type="button" className="availability-nav-btn" onClick={() => shiftWeek(1)} aria-label="Next week">Next week →</button>
+      </div>
+
+      <div className="availability-day-strip" role="group" aria-label="Pick a day">
+        {days.map((d) => {
+          const key = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+          const has = (byDay[key]?.length ?? 0) > 0;
+          const isSelected = key === selectedDay;
+          return (
+            <button
+              key={key}
+              type="button"
+              className={["availability-day", isSelected ? "availability-day--selected" : "", has ? "availability-day--has-slots" : "availability-day--empty"].filter(Boolean).join(" ")}
+              disabled={!has}
+              aria-pressed={isSelected}
+              onClick={() => { setSelectedDay(key); setSelectedKey(null); }}
+            >
+              <span className="availability-day-name">{d.toLocaleDateString([], { weekday: "short" })}</span>
+              <span className="availability-day-num">{d.getDate()}</span>
+            </button>
+          );
+        })}
+      </div>
+
+      {status === "loading" && <p className="availability-loading">Checking availability…</p>}
+      {status === "searching" && <p className="availability-loading">Searching for the next available time…</p>}
+      {status === "error" && (
+        <>
+          <p className="availability-error">Could not load availability — please try again.</p>
+          <button type="button" className="availability-nav-btn" onClick={() => void load(weekStart)}>Retry</button>
+        </>
+      )}
+      {weekIsEmpty && (
+        <div className="availability-empty">
+          <p>No availability this week.</p>
+          <button type="button" className="availability-nav-btn" onClick={() => void checkNextAvailability()}>Check next availability</button>
+        </div>
+      )}
+      {status === "ready" && daySlots.length > 0 && (
+        <div className="availability-slots" role="group" aria-label={`Available times for ${serviceName}`}>
+          {daySlots.map((s) => {
+            const id = s.serviceType === "CLASS" ? s.eventId : s.scheduleId;
+            const key = `${s.localStartDate}|${id}`;
+            const isSelected = key === selectedKey;
+            return (
+              <button
+                key={key}
+                type="button"
+                className={["time-slot", isSelected ? "time-slot--selected" : "time-slot--available"].join(" ")}
+                aria-pressed={isSelected}
+                onClick={() => handleSelect(s)}
+              >
+                <span className="time-slot-time">{timeLabel(s.localStartDate)}</span>
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}