@wix/agent-skills 1.19.2 → 1.20.1

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -107,6 +107,7 @@ export default function ProductCard({ product }) {
     promoBadge,       // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
     priceDisplay,     // the price the buyer pays (discounted when an automatic discount applies), or a min–max range
     compareAtDisplay, // struck "was" price | null — never beside a range (the PDP shows the real comparison)
+    teaser,           // plain-text description for the tile — plainDescription is HTML; never render it raw on a card
     colors,           // hex colour strings
     optionLabel,      // e.g. "3 sizes · 2 materials", or ""
     isQuickAddable,   // no product options and not sold out; does NOT check modifiers
@@ -234,24 +235,6 @@ export default function ProductDetail() {
 - Render the PDP gallery from `images` — every image reachable (thumbnails, arrows, or a swipeable rail), not just the first; a single-image product gets no empty strip.
 - `submit()` resets `adding` after completion and preserves the cart result: `undefined` on success, `null` on failure. Add failures live in `useCart().error`, not the PDP load `error`; the shipped drawer opens to display them.
 
-For an optional **add and check out** shortcut, check the add result before checkout:
-```jsx
-// Inside ProductDetail, with the other hooks above any conditional returns:
-const { checkout, loading: cartLoading } = useCart(); // named import from @/context/CartContext
-async function addAndCheckout() {
-  if (!d.product || !d.canAdd || d.adding || cartLoading) return;
-  const result = await d.submit();
-  if (result === null) return; // add failed; preserve its error and do not check out the old cart
-  await checkout();
-}
-// <button disabled={!d.canAdd || d.adding || cartLoading} onClick={addAndCheckout}>Add and check out</button>
-```
-This adds to the shopper's **current cart** and checks that cart out — so label it that way. A true
-**Buy Now** (skip the cart, buy just this item) needs a standalone cart handed to the redirect session;
-it is not shipped, and routing "Buy now" through the current cart is wrong (it would carry whatever the
-cart already holds). For direct `addToCart(...)` calls, use the same `result === null` check before checkout.
-A resolved promise alone does not mean success; a truthiness check also rejects successful `undefined`.
-
 ### Variant and modifier controls
 The product-detail example above provides both groups:
 ```js
@@ -265,7 +248,9 @@ The product-detail example above provides both groups:
 // Text modifier: d.setModifier(m.key, text)
 ```
 Retired option choices are filtered out. Respect each choice's `inStock` and modifier's
-`mandatory` flag; the hook supplies colour values and selection state without prescribing layout.
+`mandatory` flag. A choice with `isColorSwatch` renders as a **color swatch** filled with its
+`colorCode` and labelled by its name — not as a text pill; the hook supplies the values and selection
+state without prescribing the rest of the layout.
 
 ### Images
 `useProductCard` returns normalized `image`/`hoverImage`, and `useProductDetail` returns normalized
@@ -341,13 +326,26 @@ currency; `convertedAmount` is in display currency. Format
 back to `USD`). Use `summary.priceSummary.subtotal` (after discounts) with `cart.subtotal` as the
 fallback while `summary` is null, a Discount row only when `priceSummary.discount` is above zero, and
 line `pricing.totalPrice`; never sum lines yourself. Shipping and tax resolve at checkout — say
-"calculated at checkout", never a hardcoded charge, threshold, or a made-up zero.
+"calculated at checkout", never a hardcoded charge, threshold, or a made-up zero. The estimate's
+`priceSummary.delivery`, `tax`, and `additionalFees` read `"0"` when nothing was calculated (verified
+live), so a zero there is not "Free shipping" or "No tax" — don't render those rows from the estimate.
 
 Line `quantityInfo.confirmedQuantity` is the current quantity; `availableQuantity` caps increases
 when finite. `status` can be `IN_STOCK`, `PARTIALLY_IN_STOCK`, `OUT_OF_STOCK`, or
 `REMOVED_FROM_CATALOG`; surface unavailable lines and prevent checkout until resolved.
 
 ## Routes and provider
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No shipped source reads needed to wire this.** `CartDrawer` and `CartButton`
 are default exports that take **no props**. `CartProvider` is a named export accepting `children`;
 wire these exactly as shown below.
@@ -434,27 +432,30 @@ function Layout() {
 }
 ```
 
-## What a complete storefront shows
-
-The wiring above is necessary, not sufficient. These are defaults for when the brief doesn't say
-otherwise — whatever the user asked for in their prompt wins over any line here. Look at the
-catalog before designing — categories, assortment size, media, options, sales — and design for this
-store, not for a stereotype of its category. Then:
-
-- **Home:** what the store sells and one shopping action in the first screen; real products from
-  the catalog under truthful headings; not a repeat of the shop page.
-- **Shop:** a real product card — image, name, price, link — in the first screen; sort and the
-  filters the catalog supports; loading, empty, no-results, and error states that look different.
-- **Product page:** image, name, price, the first choice, and the buy button with `blockedReason`
-  in the first screen; every ribbon; every image reachable in the gallery.
-- **Cart:** the shipped drawer — it opens after every add, and checkout is a button in it.
-- **Overlays you build** (quick-add, mobile nav, filters): mount at the document root, lock
-  background scroll, close on Escape, return focus on close — as the shipped `CartDrawer` does.
-- **Copy:** nothing the merchant didn't supply — no invented reviews, scarcity, or delivery
-  promises; no Wix IDs or technical words in visible text.
-
-Pre-order ships (`isPreorder`). Subscriptions, product groups, promotions, and notify-me are built
-only when the catalog has them — never fabricated; consult the documentation skill for their endpoints.
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/shop` | `src/routes/shop.jsx` | `Shop` |
+| `/product/:slug` | `src/routes/product.$slug.jsx` | `ProductDetail` |
+
+```jsx
+// src/routes/shop.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Shop from "@/pages/Shop";
+
+export const Route = createFileRoute("/shop")({ component: Shop });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
 
 ## Missing capabilities
 For anything these interfaces do not cover, consult the official Wix API documentation using

package/skills/wix-vibe-headless/references/storefront/app/hooks/useProductCard.js

@@ -4,7 +4,7 @@
 // without touching the badge logic, price rules, or colour-dot extraction.
 //
 // Usage:
-//   const { isSoldOut, leftBadges, ribbons, promoBadge, priceDisplay, compareAtDisplay,
+//   const { isSoldOut, leftBadges, ribbons, promoBadge, priceDisplay, compareAtDisplay, teaser,
 //           colors, optionLabel, isQuickAddable, directAddVariantId, image, hoverImage } = useProductCard(product);
 //   // then render however you want; quick-add: addToCart(product.id, directAddVariantId) from useCart().
 
@@ -73,6 +73,11 @@ export function useProductCard(product) {
     // The variant a direct add sends (a product with no options still has one variant).
     const directAddVariantId = isQuickAddable ? minVariant?.id ?? null : null;
 
+    // plainDescription is an HTML string despite its name (<p>…</p>). A card wants plain text:
+    // strip the tags and cut at a word boundary, so no tile ever prints a literal "<p>".
+    const text = (product?.plainDescription || "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    const teaser = text.length > 140 ? `${text.slice(0, 140).replace(/\s+\S*$/, "")}…` : text;
+
     // Images: normalised through lib/storeImage so URLs are consistent across the tile,
     // the PDP gallery, and the cart. Hover image is the second gallery shot (if one exists).
     const image      = productImage(product);
@@ -87,6 +92,7 @@ export function useProductCard(product) {
       promoBadge,          // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
       priceDisplay,        // formatted price the buyer pays, or a min–max range
       compareAtDisplay,    // formatted struck "was" price | null (never beside a range)
+      teaser,              // plain-text description for the tile (tags stripped, ~140 chars) — never render plainDescription raw on a card
       colors,              // hex strings — render as dots; the tile shows up to however many you want
       optionLabel,         // "3 sizes · 2 materials" or empty string
       isQuickAddable,

package/skills/wix-vibe-headless/references/storefront/seed/SEED.md

@@ -41,6 +41,9 @@ const result = await seed.setupStore(ctx, {
 //   currency: { requested, actual, status, warnings } }
 ```
 
+A product `name` is at most **80 characters** — Wix rejects the whole batch over that, so keep
+names short and put the detail in `description`.
+
 The optional `currency` sets the site's payment currency before product creation. Pass it only when
 the user explicitly asked for a currency, or when it's obvious for the store — otherwise omit it. Do
 not infer a currency from the builder's country/region or the brief's language; when in doubt, leave

package/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs

@@ -174,6 +174,12 @@ function buildOptions(options = []) {
 function validateProducts(products) {
   const seen = new Map();
   for (const product of products) {
+    // Wix caps a product name at 80 characters and the bulk create rejects the WHOLE batch over it
+    // ("name has size 175, expected 80 or less"), so the 81st character costs the entire seed.
+    if (typeof product.name === "string" && product.name.length > 80) {
+      throw new Error(`Product "${product.name.slice(0, 48)}…": the name is ${product.name.length} characters and Wix allows 80. ` +
+        `Shorten it and move the detail into description. No products were created by this call.`);
+    }
     if (product.inStock !== undefined && typeof product.inStock !== "boolean") {
       throw new Error(`Product "${product.name}": inStock must be a boolean. No products were created by this call.`);
     }

package/skills/wix-headless-fast/install/pin-agents-md.mjs

@@ -1,57 +0,0 @@
-// Record what this project is in its agent instruction files, so a later session — which has
-// none of the build conversation and may never open SKILL.md — still knows the Wix site is the
-// source of truth and which skill answers which kind of question.
-//
-//   node <SKILL_ROOT>/install/pin-agents-md.mjs --vertical <name> [--stack astro]
-//
-// Run from the project root. Kept out of deploy.mjs on purpose: "copy a vertical's files" and
-// "record the project's ground rules" are separate concerns with separate reasons to change.
-// APPENDS to each file — a template's or the user's own content is never overwritten — and is
-// idempotent via the heading sentinel, so re-running fast-path.mjs writes at most once.
-// Project facts that live in the repo (site id, app id) are NOT copied here; they would go
-// stale against wix.config.json, which is the one place that owns them.
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-const argv = process.argv.slice(2);
-const flag = (n, d) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : d; };
-
-const vertical = flag("vertical");
-const stack = flag("stack", "astro");
-// "astro" means the Wix-managed flavour (ambient auth), which is worth naming. Any other stack
-// is echoed as given rather than mapped, so adding one can't silently mislabel the project.
-const frontend = stack === "astro" ? "Wix-managed Astro" : stack.charAt(0).toUpperCase() + stack.slice(1);
-
-const SENTINEL = "## This app — a Wix Headless frontend";
-const note = `
-${SENTINEL}
-
-A ${frontend} frontend for a live Wix site; \`wix.config.json\` identifies the site. Built on
-the **${vertical}** Wix business solution — more can be added to this same app. **The Wix site
-owns the content and commerce** — read and write it through the Wix APIs, never hardcode what
-it holds.
-
-The Wix skills are installed at \`.agents/skills/\` — read them from that exact path:
-
-- **\`wix-headless-fast\`** — the code already deployed in \`src/\` and how to extend it. Every
-  business solution it ships sits under \`references/<solution>/\`: \`INSTRUCTIONS.md\` is that
-  solution's playbook, \`seed/\` creates its content. To add one to this app, run from the
-  project root:
-  \`node .agents/skills/wix-headless-fast/install/deploy.mjs <solution> --stack ${stack}\`
-- **\`wix-docs\`** — the Wix API reference. Confirm any endpoint, request shape, field, or enum
-  here before writing code against it, frontend or backend. Never infer a contract from
-  generated SDK types or \`node_modules\`.
-- **\`wix-manage\`** — recipes for managing the live site itself, as opposed to changing this
-  codebase. No recipe for the task? Fall back to \`wix-docs\`.
-`;
-
-// Both files, independently — a project may have either, both, or neither, and agents differ
-// in which one they read.
-const pinned = ["AGENTS.md", "CLAUDE.md"].map((name) => {
-  const file = join(process.cwd(), name);
-  const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
-  const wrote = !existing.includes(SENTINEL);
-  if (wrote) appendFileSync(file, (existing && !existing.endsWith("\n") ? "\n" : "") + note);
-  return { file: name, wrote, created: wrote && !existing };
-});
-console.log(JSON.stringify({ event: "agents_md", pinned }));