@wix/agent-skills 1.13.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-headless/references/BUILD-astro.md

@@ -51,13 +51,22 @@ The whole Setup window is a single message of sibling `Bash` calls — **emit th
      "navLinks": [ { "href": "/", "label": "Home" }, ... ],
      "loadedPacks": ["stores", "cms", ...],
      "packsWithComponents": ["stores", "ecom", ...],
-     "disabledPacks": ["gift-cards", ...]
+     "disabledPacks": ["gift-cards", ...],
+     "navPath": ".wix/nav.astro",
+     "footerPath": ".wix/footer.astro",
+     "homePath": ".wix/home.astro"
    }
    COMPOSE
    ```
 
    The compose-input shape is documented in `scripts/compose.mjs`'s header.
 
+   **The entire visible page is LLM-generated.** `compose.mjs` still writes the plumbing — `global.css`, `astro.config.mjs`, and `Layout.astro` (the `<html>`/`<head>` shell that imports the fonts, `global.css`, ClientRouter, and the `<Navigation/>`+`<Footer/>` components) — but the **header, footer, and home page are authored by an LLM**, not from templates (there are no `Navigation.astro` / `Footer.astro` / `index.astro` templates anymore). Between `emit-design-tokens.mjs` and `compose.mjs`, dispatch a **Default-tier** generator that reads the token vocabulary at `.wix/design-tokens.css` and authors three files, then pass their paths:
+   - `.wix/nav.astro` → `Navigation.astro` (site header). Contract: one `<header class="site-nav" transition:persist="site-nav">` with brand mark + real nav links (`/`, `/about`, `/faq`), a `<!-- nav:links -->` + `<!-- nav:actions -->` marker and an empty `<div class="nav-actions">` for later vertical patches, and a no-JS mobile toggle.
+   - `.wix/footer.astro` → `Footer.astro`. Contract: one `<footer class="site-footer">` with brand, a short tagline, and the nav links.
+   - `.wix/home.astro` → `index.astro` (full home page). Contract: frontmatter importing `Layout` + a `<Layout>…</Layout>` wrapper; one `<!-- home:<pack> -->` marker per loaded home-contributing pack; and **two decorative-image slots** — `hero` + one section (e.g. `about`). **Each slot is a DEDICATED, EMPTY placeholder element that holds no copy** — e.g. `<div class="hero-image" data-decorative-slot="hero" style="aspect-ratio:4/5"></div>` sitting *beside* the hero text, NOT the `data-decorative-slot` attribute slapped on the content-bearing `<section>`. The image patcher injects an `<img>` only into an empty slot element; if the slot wraps real copy it is skipped (the image never lands). Any element type works (`<div>`/`<figure>`/…) as long as it is its own empty element.
+   - **All three:** compose tokens as utility classes so they match the theme; write real copy (no `{{…}}`); keep `transition:persist` + the `site-nav`/`site-footer` classes (the View-Transitions + `global.css` styling target them). `compose.mjs` writes each verbatim and **errors if any path is missing** (`NO_NAV`/`NO_FOOTER`/`NO_HOME`). Manifest records `nav`/`footer`/`home` = `"llm-generated"`.
+
 **In the SAME message — the business Setup Step 4 batch** (frontend-blind; `SETUP.md` owns recipes/package set). These overlap the bridge's `compose.mjs` (~20 s) so it adds no serial wall:
 
 3. `Bash` × N — app installs, one curl per `pack.apps[*]` → `SETUP.md` § Step 4a. Packs with no `apps[*]` (`cms`, `ecom`, `gift-cards`) install nothing — skip them.

package/skills/wix-headless/references/shared/STYLING.md

@@ -46,7 +46,6 @@ These are layout/spacing/typography concerns that should always be utilities, ne
 > **Never reintroduce a named `--spacing-*` scale.** In Tailwind v4 the `--spacing-*` namespace also generates the width/sizing families (`max-w-*`, `w-*`, `min-w-*`, …), so any `--spacing-<key>` token shadows the matching `max-w-<key>`. The current fix works because the skill's spacing steps happen to equal Tailwind's numeric defaults — but if a brand ever needs genuinely *custom* spacing **values**, put them under a different namespace (e.g. `--rhythm-*`) or use arbitrary values (`py-[5.5rem]`); do not revive `--spacing-*`.
 
 **Width / reading columns:** `max-w-md`, `max-w-3xl`, `max-w-6xl`, `max-w-prose` now resolve correctly to the `--container-*` keys (no spacing collision), so use them freely; `container-reading` (the designer `@utility`) or an arbitrary `max-w-[48rem]` also work.
-
 If a designer's `global.css` contains rules like `.featured-section { padding-block: 6rem; }` or `.product-card-body { display: flex; flex-direction: column; gap: 0.5rem; }`, those are misplaced — they belong in markup as utilities (`py-24`, `flex flex-col gap-2`). Inventing such classes ships broken layouts: every consumer needs the designer to have pre-declared the class, and Tailwind v4 silently drops the references when the rule is missing.
 
 ## Required tokens — the component-CSS template contract

package/skills/wix-headless/scripts/compose.mjs

@@ -212,6 +212,14 @@ const loadedPacks = Array.isArray(input.loadedPacks) ? input.loadedPacks : [];
 const packsWithComponents = Array.isArray(input.packsWithComponents) ? input.packsWithComponents : [];
 const disabledPacks = Array.isArray(input.disabledPacks) ? input.disabledPacks : [];
 
+// Full-page LLM generation (this branch): the LLM authors the entire visible
+// page — header (Navigation.astro), footer (Footer.astro), and home page
+// (index.astro). compose writes each verbatim; there are no templates for them.
+const resolveIn = (p) => { const s = typeof p === "string" ? p.trim() : ""; return s ? (isAbsolute(s) ? s : join(projectDir, s)) : null; };
+const navPath = resolveIn(input.navPath);
+const footerPath = resolveIn(input.footerPath);
+const homePath = resolveIn(input.homePath);
+
 const brandName = brand.name ?? "Brand";
 
 // ── small color helper (derivation fail-safe only) ────────────────────────────
@@ -454,27 +462,16 @@ const navItems = navLinks
   .filter((l) => l && l.href != null && l.label != null)
   .map((l) => ({ href: String(l.href), label: String(l.label) }));
 
-// ── 4. Navigation.astro ──────────────────────────────────────────────────────────
+// ── 4. Navigation.astro (LLM-generated, verbatim) ─────────────────────────────
 {
-  let out = stripAstroHeader(readTemplate("Navigation.astro"));
-  out = out.replaceAll("{{shell.navBrandMark}}", shell.navBrandMark ?? brandName);
-  const links = navItems
-    .map((l) => `        <li class="site-nav-item"><a href="${escAttr(l.href)}">${l.label}</a></li>`)
-    .join("\n");
-  out = out.replace(/^\s*\{\{nav\.links\}\}\s*$/m, links);
-  writeProject("src/components/Navigation.astro", out);
+  if (!navPath || !existsSync(navPath)) die("NO_NAV", `LLM-generated header required via navPath (none at ${navPath ?? "<unset>"})`);
+  writeProject("src/components/Navigation.astro", readFileSync(navPath, "utf8"));
 }
 
-// ── 5. Footer.astro ──────────────────────────────────────────────────────────────
+// ── 5. Footer.astro (LLM-generated, verbatim) ─────────────────────────────────
 {
-  let out = stripAstroHeader(readTemplate("Footer.astro"));
-  out = out.replaceAll("{{brand.name}}", brandName);
-  out = out.replaceAll("{{shell.footerTagline}}", shell.footerTagline ?? "");
-  const links = navItems
-    .map((l) => `        <li><a href="${escAttr(l.href)}">${l.label}</a></li>`)
-    .join("\n");
-  out = out.replace(/^\s*\{\{nav\.links\}\}\s*$/m, links);
-  writeProject("src/components/Footer.astro", out);
+  if (!footerPath || !existsSync(footerPath)) die("NO_FOOTER", `LLM-generated footer required via footerPath (none at ${footerPath ?? "<unset>"})`);
+  writeProject("src/components/Footer.astro", readFileSync(footerPath, "utf8"));
 }
 
 // ── 6. index.astro ────────────────────────────────────────────────────────────────
@@ -485,13 +482,8 @@ const HOME_CONTRIBUTING = ["stores", "bookings", "gift-cards"]; // canonical ord
 const homePool = new Set([...loadedPacks, ...disabledPacks]);
 const homeMarkerPacks = HOME_CONTRIBUTING.filter((p) => homePool.has(p));
 {
-  let out = stripAstroHeader(readTemplate("index.astro"));
-  out = out.replaceAll("{{shell.heroHeadline}}", shell.heroHeadline ?? brandName);
-  out = out.replaceAll("{{shell.heroSub}}", shell.heroSub ?? "");
-  out = out.replaceAll("{{brand.name}}", brandName);
-  const markers = homeMarkerPacks.map((p) => `  <!-- home:${p} -->`).join("\n");
-  out = out.replace(/^\s*\{\{home-markers\}\}\s*$/m, markers);
-  writeProject("src/pages/index.astro", out);
+  if (!homePath || !existsSync(homePath)) die("NO_HOME", `LLM-generated home page required via homePath (none at ${homePath ?? "<unset>"})`);
+  writeProject("src/pages/index.astro", readFileSync(homePath, "utf8"));
 }
 
 // ── manifest (the orchestrator parses this off stdout) ────────────────────────
@@ -508,6 +500,9 @@ const manifest = {
   phase: "compose",
   data: {
     filesWritten,
+    nav: "llm-generated",
+    footer: "llm-generated",
+    home: "llm-generated",
     componentCssImports: packsWithComponents,
     homeMarkers: homeMarkerPacks.map((p) => `home:${p}`),
     tokensApplied: {

package/skills/wix-headless/scripts/patch-decorative-slots.mjs

@@ -2,10 +2,11 @@
 // Inject Image-Phase-1 decorative URLs into the page shells.
 //
 // The design-system Composer (index.astro) and the Phase 4 page designers write
-// `<div data-decorative-slot="<key>">…</div>` placeholders in src/pages/*.astro. Image Phase 1 returns a slot→URL map
-// in its JSON return; the orchestrator pipes that map (as JSON) into this
+// `<el data-decorative-slot="<key>">…</el>` placeholders in src/pages/*.astro
+// (any element — <div>, <section>, <figure>…). Image Phase 1 returns a slot→URL
+// map in its JSON return; the orchestrator pipes that map (as JSON) into this
 // script's stdin. This script reads the map + walks src/pages/*.astro,
-// then injects an <img> as the first child of each matching slot div —
+// then injects an <img> as the first child of each matching empty slot element —
 // pure string substitution, no LLM, no file rewrites.
 //
 // Usage:
@@ -23,9 +24,9 @@
 //     blocks mode or Image Phase 1 had no URLs to publish).
 //   - src/pages missing at <scaffold-dir> and in any single subdir one
 //     level down → exit 2 status="error".
-//   - For each `data-decorative-slot="<key>"` in src/pages/*.astro:
-//       * Key has no URL in the input map → leave the div alone.
-//       * Div already has a non-comment child → skip with a warning.
+//   - For each `data-decorative-slot="<key>"` element in src/pages/*.astro:
+//       * Key has no URL in the input map → leave the element alone.
+//       * Element already has a non-comment child → skip with a warning.
 //       * Otherwise inject <img …> as the first child.
 //   - Output JSON summary of patches/skips/warnings to stdout.
 
@@ -99,14 +100,19 @@ const patched = [];
 const skipped = [];
 const warnings = [];
 
-const SLOT_DIV_REGEX = /(<div[^>]*\bdata-decorative-slot="([^"]+)"[^>]*>)([\s\S]*?)(<\/div>)/g;
+// Match ANY element carrying data-decorative-slot, not just <div>. Full-page
+// LLM generation routinely puts the slot on a <section>/<figure>/<picture>;
+// the closing tag is matched by backreference (\2) to the opening tag name.
+// Slots are empty placeholders by contract, so the non-greedy body cannot
+// straddle a sibling element of the same tag.
+const SLOT_REGEX = /(<([a-zA-Z][\w-]*)[^>]*\bdata-decorative-slot="([^"]+)"[^>]*>)([\s\S]*?)(<\/\2>)/g;
 
 for (const file of candidates) {
   const original = readFileSync(file, "utf8");
   let modified = original;
   let fileChanged = false;
 
-  modified = modified.replace(SLOT_DIV_REGEX, (match, openTag, slotKey, inner, closeTag) => {
+  modified = modified.replace(SLOT_REGEX, (match, openTag, _tagName, slotKey, inner, closeTag) => {
     const url = urlMap[slotKey];
     if (!url) {
       skipped.push({ file, slot: slotKey, reason: "no URL for this slot in input map" });
@@ -121,7 +127,7 @@ for (const file of candidates) {
     }
 
     if (stripped.length > 0) {
-      warnings.push({ file, slot: slotKey, reason: "div has existing non-image child content; not patching to avoid clobber" });
+      warnings.push({ file, slot: slotKey, reason: "slot element has existing non-image child content; not patching to avoid clobber" });
       return match;
     }
 

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

@@ -1,27 +0,0 @@
----
-// ── Composer skeleton: src/components/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);
-//        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-6 py-16 flex flex-col md:flex-row md:items-start md:justify-between gap-8">
-    <div class="flex flex-col gap-3 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-3 text-sm">
-        {{nav.links}}
-      </ul>
-    </nav>
-  </div>
-  <div class="max-w-6xl mx-auto px-6 pb-8 text-xs">
-    <p>© {year} {{brand.name}}. All rights reserved.</p>
-  </div>
-</footer>

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

@@ -1,38 +0,0 @@
----
-// ── Composer skeleton: src/components/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
-//        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-6 flex items-center justify-between gap-6 py-4">
-    <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-4 md:gap-6 items-start md:items-center
-             bg-paper md:bg-transparent border-b md:border-0 border-rule px-6 md:px-0 py-4 md:py-0"
-    >
-      <ul class="flex flex-col md:flex-row gap-4 md:gap-6 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/index.astro

@@ -1,56 +0,0 @@
----
-// ── Composer skeleton: src/pages/index.astro ──────────────────────────────────
-// Home shell. Substitutions (see compose.mjs):
-//   {{shell.heroHeadline}}, {{shell.heroSub}} — brand-voice hero copy.
-//   {{shell.footerTagline}} is NOT used here.
-//   {{brand.name}} — used in the brand-story copy.
-//   {{home-markers}} — one `<!-- home:<pack> -->` marker per LOADED pack that
-//        contributes a home section (e.g. stores, gift-cards). Emit a marker
-//        ONLY for such packs; never emit a marker no pack will fill (e.g. no
-//        <!-- home:cms --> — CMS owns brand-story directly). Disabled packs
-//        (gift-cards) still get their marker; do NOT add hero CTAs / teasers
-//        pointing at disabled-pack routes.
-// Fixed bulk (keep literal): the Layout wrapper, hero/brand-story structure,
-// the data-decorative-slot="hero" and "about" placeholders (the orchestrator
-// injects <img> into these after Image Phase 1 — keep them empty).
-import Layout from '../layouts/Layout.astro';
----
-<Layout>
-  <section class="relative">
-    <div class="max-w-6xl mx-auto px-6 py-24 grid grid-cols-1 md:grid-cols-2 gap-16 items-center">
-      <div class="flex flex-col gap-6">
-        <h1 class="font-display text-4xl md:text-5xl leading-tight">{{shell.heroHeadline}}</h1>
-        <p class="text-lg text-mute max-w-prose">{{shell.heroSub}}</p>
-      </div>
-      <div
-        class="hero-image rounded-md"
-        data-decorative-slot="hero"
-        style="aspect-ratio: 4/5; background-color: var(--color-paper-warm);"
-      >
-        <!-- orchestrator injects <img src={decorativeImages.hero} …> here -->
-      </div>
-    </div>
-  </section>
-
-  {{home-markers}}
-
-  <section class="max-w-6xl mx-auto px-6 py-24 grid grid-cols-1 md:grid-cols-2 gap-16 items-center">
-    <div
-      class="about-image rounded-md order-last md:order-first"
-      data-decorative-slot="about"
-      style="aspect-ratio: 4/3; background-color: var(--color-paper-warm);"
-    >
-      <!-- orchestrator injects <img src={decorativeImages.about} …> here -->
-    </div>
-    <div class="flex flex-col gap-4 max-w-prose">
-      <hr class="editorial-rule w-16 ml-0" />
-      <h2 class="font-display text-3xl leading-tight">The story behind {{brand.name}}</h2>
-      <p class="text-ink leading-relaxed">
-        A short, brand-contextual paragraph about what makes {{brand.name}} distinct.
-      </p>
-      <p class="text-mute leading-relaxed">
-        A second paragraph adding warmth and detail to the brand story.
-      </p>
-    </div>
-  </section>
-</Layout>