@wix/agent-skills 1.6.0 → 1.7.0

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

@@ -1,6 +1,8 @@
 # Phase 4 Home Page + Nav — Stores
 
-Scope: `pages-home-and-nav`. Launched in **Step 7** after `pages-categories` has written the shared rail and `categories.ts` helper. 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`. 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.
+
+> **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.)
 
 ## Scope
 
@@ -12,14 +14,14 @@ Files this agent PATCHES (does NOT rewrite):
 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`, `src/components/CategoryRail.astro`, `src/pages/category/[slug].astro` — owned by `pages-categories`; this scope only **imports** `listStoreCategories` from `categories.ts`
+- `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 `.wix/site.json.designTokens` 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** — 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.
 - **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.
 
@@ -28,7 +30,7 @@ Files this agent MUST NOT touch:
 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 `<prefix>CallWixSiteAPI` with `POST /categories/v1/categories/query` body `{"query":{}}`. Improvised `/stores/v3/categories/...` URLs caused a multi-minute stall historically.
+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.
 
@@ -72,7 +74,7 @@ try {
 ---
 ```
 
-Then pass each raw product to `ProductCard`. The ribbon is fetched inside ProductCard itself — pages no longer wire offers:
+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} />)}
 ```
@@ -116,7 +118,7 @@ Handle this:
    import { categoriesV3 } from "@wix/stores";
    const { items: categories } = await categoriesV3.queryCategories().find();
    ```
-   Fall back to `CallWixSiteAPI` with `POST /categories/v1/categories/query` body `{"query":{}}` if the SDK module is unavailable.
+   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.
@@ -128,7 +130,7 @@ Handle this:
 
 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).
 
-Read `src/utils/categories.ts` (already on disk — written by `pages-categories`) and import `listStoreCategories`. At the marker, insert:
+Import `listStoreCategories` from `src/utils/categories.ts` (already on disk — pre-copied by the orchestrator). At the marker, insert:
 
 ```astro
 ---
@@ -213,7 +215,7 @@ Keep the marker comment immediately after the inserted `<li>` so other vertical
 - **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` or `src/components/CategoryRail.astro` — owned by `pages-categories`.
+- **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
@@ -224,4 +226,4 @@ Keep the marker comment immediately after the inserted `<li>` so other vertical
 | 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[]` |
+| `featured = products.map(p => ({name: p.name, ...}))` — flat-mapping SDK results | Store raw products: `featured = featuredProducts ?? []` as `any[]` |

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

@@ -14,12 +14,14 @@ 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/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.
 - `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 `.wix/site.json.designTokens` 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`.
+- **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.
 
 ## Critical rules (all must be honored)
@@ -72,7 +74,7 @@ Preserves the designer's page structure (class names, layout) and replaces the p
 
 > **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.** The previous "ship every product, hide non-matching cards via JS" pattern is gone — it doesn't scale and breaks SEO. Do not reintroduce `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.
+> **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.
 
@@ -210,4 +212,4 @@ If any of `wixMetadataExported`, `seoTagsMounted`, `useGetProductBySlug` ends up
 | 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`. |
+| 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/{stores → astro/stores}/SHARED_WIRING.md

@@ -94,7 +94,7 @@ Handles variant selection, quantity selector, stock awareness, and wraps `AddToC
 <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 the regression observed in an earlier run where a fallback-written `[slug].astro` passed `product` as a whole when the component expected flat props).
+**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.
@@ -159,6 +159,6 @@ Classes from contract (stores pack):
 | 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, call `<prefix>SearchWixSDKDocumentation` |
+| 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} />` |
+| Pass flat props to `ProductPurchase` (`productId`, `options`, `variantsInfo`, …) | Pass the whole product: `<ProductPurchase product={product} inventoryByVariant={inventoryByVariant} />` |

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

@@ -0,0 +1,27 @@
+---
+// ── Composer skeleton: src/components/Footer.astro ────────────────────────────
+// Substitutions (see COMPOSE.md § "5. Footer.astro"):
+//   {{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);
+//        one <a href={href}>{label}</a> per entry, labels VERBATIM. No cart,
+//        login, or account links.
+// Fixed bulk (keep literal): transition:persist, the year expression.
+const year = new Date().getFullYear();
+---
+<footer class="site-footer" transition:persist="site-footer">
+  <div class="max-w-6xl mx-auto px-lg py-3xl flex flex-col md:flex-row md:items-start md:justify-between gap-xl">
+    <div class="flex flex-col gap-sm max-w-prose">
+      <span class="font-display text-lg text-ink">{{brand.name}}</span>
+      <p class="text-sm">{{shell.footerTagline}}</p>
+    </div>
+    <nav>
+      <ul class="flex flex-col gap-sm text-sm">
+        {{nav.links}}
+      </ul>
+    </nav>
+  </div>
+  <div class="max-w-6xl mx-auto px-lg pb-xl text-xs">
+    <p>© {year} {{brand.name}}. All rights reserved.</p>
+  </div>
+</footer>

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

@@ -0,0 +1,132 @@
+---
+// ── 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"):
+//   {{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
+//        .fonts (display + body families). Omit the <link> if fonts are system.
+//   {{brand.name}} — default <title>.
+import '../styles/global.css';
+{{components-css-imports}}
+import { ClientRouter } from 'astro:transitions';
+import Navigation from '../components/Navigation.astro';
+import Footer from '../components/Footer.astro';
+
+interface Props {
+  title?: string;
+  description?: string;
+  hasSeoTags?: boolean;
+}
+const { title, description, hasSeoTags = false } = Astro.props;
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'/%3E" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link rel="stylesheet" href="{{fonts.googleHref}}" />
+    {!hasSeoTags && (
+      <>
+        <title>{title ? `${title} · {{brand.name}}` : "{{brand.name}}"}</title>
+        {description && <meta name="description" content={description} />}
+      </>
+    )}
+    <slot name="head" />
+    <ClientRouter />
+  </head>
+  <body>
+    <div class="nav-progress" data-nav-progress aria-hidden="true"></div>
+    <Navigation />
+    <main><slot /></main>
+    <Footer />
+    <script>
+      // Persisted rail aria-current sync + top loading bar + rail-anchored
+      // scroll across listing-to-listing navigation. Stores pack relies on
+      // all three; do not split into separate scripts.
+      function syncCategoryRail() {
+        const path = window.location.pathname;
+        const activeSlug = path.startsWith("/category/")
+          ? path.slice("/category/".length).replace(/\/$/, "")
+          : path === "/products" || path === "/products/"
+            ? ""
+            : null;
+        if (activeSlug === null) return;
+        const pills = document.querySelectorAll<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        for (const pill of pills) {
+          const slug = pill.dataset.categorySlug ?? "";
+          if (slug === activeSlug) pill.setAttribute("aria-current", "page");
+          else pill.removeAttribute("aria-current");
+        }
+      }
+      // Eager click feedback — flip aria-current before the network call.
+      document.addEventListener("click", (event) => {
+        const target = event.target as HTMLElement | null;
+        const pill = target?.closest<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        if (!pill) return;
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        const pills = document.querySelectorAll<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        for (const p of pills) p.removeAttribute("aria-current");
+        pill.setAttribute("aria-current", "page");
+      }, true);
+      const progress = document.querySelector<HTMLElement>("[data-nav-progress]");
+      function startProgress() {
+        if (!progress) return;
+        progress.dataset.state = "loading";
+        document.body.dataset.navigating = "true";
+      }
+      function endProgress() {
+        if (!progress) return;
+        progress.dataset.state = "done";
+        delete document.body.dataset.navigating;
+        window.setTimeout(() => {
+          if (progress.dataset.state === "done") delete progress.dataset.state;
+        }, 320);
+      }
+      // Anchor the persisted rail across listing-to-listing navigation. The
+      // page-header above the rail differs between /products and /category/[slug]
+      // (breadcrumbs, lede, optional image), so naive scroll preservation reads
+      // as a jump. Capture rail.getBoundingClientRect().top before the swap and
+      // re-equalize after.
+      const isListing = (p: string) =>
+        p === "/products" || p === "/products/" || p.startsWith("/category/");
+      let railAnchorTop: number | null = null;
+      document.addEventListener("astro:before-preparation", (event: any) => {
+        const from = window.location.pathname;
+        const to = event?.to?.pathname ?? from;
+        const rail = document.querySelector<HTMLElement>("[data-category-rail]");
+        railAnchorTop =
+          rail && isListing(from) && isListing(to)
+            ? rail.getBoundingClientRect().top
+            : null;
+        startProgress();
+      });
+      document.addEventListener("astro:after-swap", () => {
+        syncCategoryRail();
+        if (railAnchorTop !== null) {
+          const rail = document.querySelector<HTMLElement>("[data-category-rail]");
+          if (rail) {
+            const delta = rail.getBoundingClientRect().top - railAnchorTop;
+            if (Math.abs(delta) > 0.5) {
+              window.scrollBy({ top: delta, left: 0, behavior: "instant" as ScrollBehavior });
+            }
+          }
+        }
+        railAnchorTop = null;
+        endProgress();
+      });
+      document.addEventListener("astro:page-load", endProgress);
+      syncCategoryRail();
+    </script>
+  </body>
+</html>

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

@@ -0,0 +1,38 @@
+---
+// ── Composer skeleton: src/components/Navigation.astro ────────────────────────
+// Substitutions (see COMPOSE.md § "4. Navigation.astro"):
+//   {{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
+//        each inside a <li class="site-nav-item">.
+// Fixed bulk (keep literal): transition:persist, the <!-- nav:links --> marker,
+// the empty <div class="nav-actions"> mount, the mobile hamburger toggle.
+---
+<header class="site-nav" transition:persist="site-nav">
+  <nav class="max-w-6xl mx-auto px-lg flex items-center justify-between gap-lg py-md">
+    <a href="/" class="font-display text-lg tracking-tight">{{shell.navBrandMark}}</a>
+
+    <input type="checkbox" id="nav-toggle" class="peer hidden" aria-hidden="true" />
+    <label
+      for="nav-toggle"
+      class="md:hidden inline-flex flex-col gap-[5px] cursor-pointer"
+      aria-label="Toggle navigation"
+    >
+      <span class="block h-[2px] w-6 bg-ink"></span>
+      <span class="block h-[2px] w-6 bg-ink"></span>
+      <span class="block h-[2px] w-6 bg-ink"></span>
+    </label>
+
+    <div
+      class="hidden peer-checked:flex md:flex absolute md:static top-full left-0 right-0 md:right-auto
+             flex-col md:flex-row gap-md md:gap-lg items-start md:items-center
+             bg-paper md:bg-transparent border-b md:border-0 border-rule px-lg md:px-0 py-md md:py-0"
+    >
+      <ul class="flex flex-col md:flex-row gap-md md:gap-lg items-start md:items-center">
+        {{nav.links}}
+        <!-- nav:links -->
+      </ul>
+      <div class="nav-actions"></div>
+    </div>
+  </nav>
+</header>

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

@@ -0,0 +1,41 @@
+// ── Composer skeleton: astro.config.mjs ───────────────────────────────────────
+// UNLIKE the other skeletons, this one is a MERGE TARGET, not a clobber. The
+// 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"):
+//
+//   (1) register the Tailwind v4 Vite plugin   → vite.plugins: [tailwindcss()]
+//   (2) fix the bare `process.env` reference    → globalThis guard (TS-safe)
+//
+// The shape below is the canonical post-mutation result for a typical scaffold —
+// use it as the reference for what those two edits should produce.
+// @ts-check
+import { defineConfig } from "astro/config";
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+import react from "@astrojs/react";
+import cloudProviderFetchAdapter from "@wix/cloud-provider-fetch-adapter";
+import tailwindcss from "@tailwindcss/vite"; // (1) added by Composer
+
+// (2) `process.env` guarded so strict `tsc --noEmit` does not fail with
+//     "Cannot find name 'process'" without an @types/node dependency.
+const isBuild =
+  (/** @type {any} */ (globalThis)).process?.env?.NODE_ENV === "production";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  ...(isBuild && { adapter: cloudProviderFetchAdapter({}) }),
+
+  image: {
+    domains: ["static.wixstatic.com"],
+  },
+
+  vite: {
+    plugins: [tailwindcss()], // (1) merge into any existing vite config
+  },
+
+  output: "server",
+});