@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-headless-fast/references/shared/DESIGN.md

@@ -0,0 +1,26 @@
+# Design floor — every vertical, every surface you author
+
+**A fallback, not an override.** These rules fill the gap when the user gave no design
+direction. The moment the brief specifies a palette, a mood, a reference — their intent wins.
+Two exceptions that hold regardless: the contrast floor (in `styles/global.css`, where you
+choose the tokens), and the anti-genericism intent — derive the look from *this* brand even
+when the user supplied the inputs.
+
+Token judgment (polarity, palette, contrast, type floors) lives in the `@theme` header in
+`styles/global.css` — you'll meet it when you set the tokens. This file governs the surfaces:
+
+- **Full-bleed, not boxed.** Don't wrap pages in a narrow centered shell (`max-w-4xl mx-auto`
+  around everything). Design for the viewport; use peripheral space intentionally.
+- **One primary CTA per page**, worded to the page's actual action — "Add to Cart",
+  "Book a Table", "Reserve Your Spot" — never "Submit" / "Click here" / "Learn more" as the
+  hero action.
+- **Icons render bare on the surface** — no circle/square/pill shell behind nav or card
+  glyphs.
+- **No emojis** in UI copy, headings, or empty states (unless the brief itself asks for
+  them).
+- **Vary the look across projects.** Repeating the same palette/layout on unrelated brands is
+  a failure mode, not a shortcut — two sites with the same vertical and different briefs
+  should look nothing alike.
+
+This constrains the *how*, not the *what* — the brief and the vertical decide what the pages
+are; INSTRUCTIONS decides which surfaces exist.

package/skills/wix-headless-fast/references/shared/app/styles/global.css

@@ -0,0 +1,52 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

package/skills/wix-headless-fast/references/shared/app/wix/config.ts

@@ -0,0 +1,15 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. On a Wix-managed non-Astro project
+//                         it equals the `appId` in wix.config.json.
+export const WIX_CLIENT_ID: string | null = null;
+
+// The Members vertical uses an explicit OAuthStrategy client only to drive the
+// custom credential form. In managed Astro it writes the resulting member
+// tokens into Astro's wixSession cookie, so subsequent ambient SDK calls use
+// that same member identity.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

package/skills/wix-headless-fast/references/shared/app/wix/media.ts

@@ -0,0 +1,27 @@
+// Wix media resolution — define once, use on EVERY image render path. Copy as-is.
+//
+// SDK media fields come back either as an already-absolute https URL, or as a
+// `wix:image://v1/<hash>/<file>#originWidth=…` identifier that a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The wix:image:// form must go through the SDK media module;
+// never hand-build a static.wixstatic.com URL (wrong format → 403).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import { media } from "@wix/sdk";
+
+type MediaLike =
+  | string
+  | null
+  | undefined
+  | { image?: string | null; url?: string | null };
+
+/** Resolve any Wix media value to a browser-loadable URL ("" when absent). */
+export function imgSrc(value: MediaLike, width = 600, height = 600): string {
+  const v =
+    typeof value === "object" && value !== null
+      ? (value.image ?? value.url ?? "")
+      : (value ?? "");
+  if (!v) return "";
+  if (typeof v === "string" && v.startsWith("wix:image://")) {
+    return media.getScaledToFillImageUrl(v, width, height, {});
+  }
+  return typeof v === "string" ? v : "";
+}

package/skills/wix-headless-fast/references/shared/app/wix/money.ts

@@ -0,0 +1,24 @@
+// Money formatting for API amounts that carry no formatted string. Copy as-is.
+//
+// Catalog prices come with a ready `formattedAmount` — use that directly. But eCom Cart V2
+// amounts are ConvertedMoney `{ amount, convertedAmount }` with NO formatted string, and the
+// currency lives on the cart, not on the money object. Never hardcode "$" or assume USD.
+export interface ConvertedMoneyLike {
+  amount?: string | null;
+  convertedAmount?: string | null;
+}
+
+/** Format a ConvertedMoney in the given currency, using the visitor's locale. */
+export function formatMoney(
+  money: ConvertedMoneyLike | null | undefined,
+  currencyCode: string | null | undefined,
+): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}

package/skills/wix-headless-fast/references/shared/app/wix/sdk.ts

@@ -0,0 +1,76 @@
+// The one auth seam for every Wix SDK call in this app. Copy as-is; do not rewrite.
+//
+// Two modes, switched by WIX_CLIENT_ID in ./config:
+//   null (ambient)  — a Wix-managed Astro project: `@wix/astro` authenticates raw SDK module
+//                     calls automatically, server-side AND in client islands. `wixModule()`
+//                     returns the module untouched.
+//   string (manual) — any other React setup (Vite SPA, non-Astro): one shared client is built
+//                     with OAuthStrategy, and `wixModule()` returns the module bound to it.
+//                     The strategy self-manages visitor tokens on every call (mints on first
+//                     use, renews on expiry) and persists them through the storage below.
+//
+// The visitor token IS the identity of the current cart / member session, so in manual mode
+// tokens persist to localStorage — never re-minted per load (a fresh anonymous mint is a NEW
+// visitor and silently empties the cart).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
+// docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
+import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
+import { WIX_CLIENT_ID } from "./config";
+
+const STORAGE_KEY = `wix-session-${WIX_CLIENT_ID ?? "ambient"}`;
+
+function browserTokenStorage(): TokenStorage {
+  return {
+    getTokens(): Tokens {
+      if (typeof window !== "undefined") {
+        try {
+          const raw = window.localStorage.getItem(STORAGE_KEY);
+          if (raw) return JSON.parse(raw) as Tokens;
+        } catch {
+          /* disabled/corrupt storage — fall through to empty */
+        }
+      }
+      return EMPTY_TOKENS;
+    },
+    setTokens(tokens: Tokens): void {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+      } catch {
+        /* storage full/disabled — the session just won't survive a reload */
+      }
+    },
+  };
+}
+
+const client = WIX_CLIENT_ID
+  ? createClient({
+      auth: OAuthStrategy({
+        clientId: WIX_CLIENT_ID,
+        tokenStorage: browserTokenStorage(),
+      }),
+    })
+  : null;
+
+/**
+ * Bind an SDK module to this app's auth. Usage (identical in both modes):
+ *   import { productsV3 } from "@wix/stores";
+ *   const products = wixModule(productsV3);
+ *   await products.queryProducts(...)
+ */
+export function wixModule<T>(module: T): T {
+  // The cast bridges the SDK's internal Descriptors constraint; the in/out type is identical.
+  return client
+    ? (client.use(module as unknown as Record<string, unknown>) as unknown as T)
+    : module;
+}
+
+/**
+ * The shared data client's manual-mode auth strategy, or null under ambient auth. The
+ * Members vertical deliberately owns a separate explicit client for its custom in-app login;
+ * app code reads that session through the members hooks instead.
+ */
+export function wixAuth(): IOAuthStrategy | null {
+  return client ? client.auth : null;
+}

package/skills/wix-headless-fast/references/shared/capabilities/media-upload/app/wix/media-upload/client.ts

@@ -0,0 +1,46 @@
+// Safe browser half of the optional Media Upload capability.
+// The browser supplies bytes only. It cannot choose a destination or elevate a Wix call:
+// the named policy is enforced by /api/wix/media-upload on the server.
+
+export type UploadedMedia = {
+  id: string;
+  url?: string;
+  uploadUrl: string;
+};
+
+type UploadPolicyRequest = {
+  policyId: string;
+  fileName: string;
+  mimeType: string;
+  sizeInBytes: number;
+};
+
+export async function uploadMedia(policyId: string, file: File | Blob, fileName?: string): Promise<UploadedMedia> {
+  const mimeType = file.type;
+  const request: UploadPolicyRequest = {
+    policyId,
+    fileName: fileName ?? (file instanceof File ? file.name : "upload"),
+    mimeType,
+    sizeInBytes: file.size,
+  };
+  const ticket = await fetch("/api/wix/media-upload", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request),
+  });
+  if (!ticket.ok) throw new Error(`Upload could not be authorized (${ticket.status})`);
+  const { uploadUrl } = (await ticket.json()) as UploadedMedia;
+
+  const uploaded = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": mimeType },
+    body: file,
+  });
+  const payload = (await uploaded.json().catch(() => null)) as
+    | { file?: { id?: string; url?: string }; id?: string; url?: string }
+    | null;
+  const media = payload?.file ?? payload;
+  if (!uploaded.ok || !media?.id) throw new Error(`Upload failed (${uploaded.status})`);
+
+  return { id: media.id, url: media.url, uploadUrl };
+}

package/skills/wix-headless-fast/references/shared/capabilities/media-upload/app-astro/pages/api/wix/media-upload.ts

@@ -0,0 +1,46 @@
+import type { APIRoute } from "astro";
+import { auth } from "@wix/essentials";
+import { files } from "@wix/media";
+import { mediaUploadPolicies } from "../../../wix/media-upload/policies.generated";
+
+const elevatedGenerateUploadUrl = auth.elevate(files.generateFileUploadUrl);
+
+type UploadRequest = {
+  policyId?: unknown;
+  fileName?: unknown;
+  mimeType?: unknown;
+  sizeInBytes?: unknown;
+};
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+
+export const POST: APIRoute = async ({ request }) => {
+  let body: UploadRequest;
+  try {
+    body = (await request.json()) as UploadRequest;
+  } catch {
+    return json({ error: "Expected JSON" }, 400);
+  }
+
+  if (
+    typeof body.policyId !== "string" ||
+    typeof body.fileName !== "string" ||
+    typeof body.mimeType !== "string" ||
+    typeof body.sizeInBytes !== "number" ||
+    !Number.isSafeInteger(body.sizeInBytes)
+  ) {
+    return json({ error: "Invalid upload request" }, 400);
+  }
+  const policy = mediaUploadPolicies.find((candidate) => candidate.id === body.policyId);
+  if (!policy) return json({ error: "Unknown upload policy" }, 404);
+  if (!policy.accept.includes(body.mimeType as never)) return json({ error: "File type is not allowed" }, 415);
+  if (body.sizeInBytes < 1 || body.sizeInBytes > policy.maxBytes) return json({ error: "File exceeds this policy's size limit" }, 413);
+
+  // Do not accept a folder id, labels, privacy setting, or any other destination choice from
+  // the browser. Add those as fixed policy fields only after the product actually needs them.
+  const result = await elevatedGenerateUploadUrl(body.mimeType, {
+    fileName: body.fileName.slice(0, 255),
+  });
+  return json({ uploadUrl: result.uploadUrl });
+};

package/skills/wix-headless-fast/references/shared/seed/images.mjs

@@ -0,0 +1,145 @@
+// Shared seed util: entity images by URL or by AI GENERATION (Wix AI / Runware via the
+// wixapis proxy). BUILD-TIME only — imported by the vertical seed scripts, never shipped.
+//
+// The contract every seed relies on:
+//   - RESILIENT: nothing here ever throws out of resolveItemImages — a failed image resolves
+//     to null and the entity stays text-only; the seed's exit code never depends on images.
+//   - PARALLEL: all images resolve in one concurrent wave (each generation is its own
+//     single-task request — the google model 504s when one body bundles ≥3 tasks).
+//   - PASS-2: seeds create entities first, then attach what this returns — an image is never
+//     a precondition for an entity.
+//
+// Generation costs 1 Wix AI credit per image, billed to the account behind the site.
+// Authoritative reference: wix-headless/references/IMAGE_GENERATION.md.
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename, extname } from "node:path";
+
+const API = "https://www.wixapis.com";
+// Order = cheap-and-permissive first (runware ~0.009 credits/img, ~5s, loosest content
+// filter), then google (best fidelity, ~0.14, ~25s; rejects steps/CFGScale and free-form
+// sizes), then bfl (strictest filter — refuses trademark-ish prompts). A refusal or failure
+// falls through to the next model.
+const MODELS = ["runware:400@1", "google:4@2", "bfl:5@1"];
+/** Allowed dimensions: 1024×1024 (square — entities), 1376×768 (16:9 hero), 1200×896 (4:3). */
+export const IMAGE_SIZES = { square: [1024, 1024], hero: [1376, 768], editorial: [1200, 896] };
+
+async function req(ctx, path, body, timeoutMs = 45_000) {
+  const res = await fetch(API + path, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`POST ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 300)}`);
+  return json;
+}
+
+/**
+ * Generate one image; returns its short-lived URL (import it immediately). Tries each model
+ * once — a per-model failure (bad params, 5xx, credit exhaustion, timeout) falls through to
+ * the next; throws only after all models failed.
+ * docs: no public reference for /runwareschemaless/v1/request — see wix-headless/references/IMAGE_GENERATION.md
+ */
+export async function generateImage(ctx, prompt, { width = 1024, height = 1024 } = {}) {
+  let lastErr;
+  for (const model of MODELS) {
+    try {
+      const r = await req(ctx, "/runwareschemaless/v1/request", [
+        {
+          taskType: "imageInference",
+          taskUUID: randomUUID(), // must be a real UUIDv4 — slugs 400
+          outputType: "URL",
+          outputFormat: "PNG",
+          positivePrompt: prompt,
+          width,
+          height,
+          model,
+          numberResults: 1,
+        },
+      ]);
+      const url = r?.data?.[0]?.imageURL;
+      if (url) return url;
+      lastErr = new Error(`no imageURL in response: ${JSON.stringify(r).slice(0, 200)}`);
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  throw lastErr;
+}
+
+const MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".avif": "image/avif" };
+
+/**
+ * Upload a LOCAL file (a path on this machine — the user's own asset) into Wix Media;
+ * returns { id, url } (permanent). Two steps per the Upload API: generate-upload-url, then
+ * PUT the bytes to it — the PUT response carries the file descriptor.
+ * docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/generate-file-upload-url.md
+ */
+export async function uploadImage(ctx, path, displayName) {
+  const ext = extname(path).toLowerCase();
+  const mimeType = MIME[ext];
+  if (!mimeType) throw new Error(`unsupported image extension: ${path}`);
+  const bytes = readFileSync(path); // throws loud on a wrong path (caught per-item by resolveItemImages)
+  // fileName's extension MUST match the real file type — a mismatch (slug.png for a .jpg) is
+  // rejected; keep the caller's display name, swap in the file's own extension.
+  const fileName = (displayName ?? basename(path)).replace(/\.[a-z0-9]+$/i, "") + ext;
+  const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", {
+    mimeType,
+    fileName,
+  });
+  const res = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": mimeType },
+    body: bytes,
+    signal: AbortSignal.timeout(120_000),
+  });
+  const json = await res.json().catch(() => ({}));
+  const f = json.file || json;
+  if (!res.ok || !f?.id) throw new Error(`upload failed (${res.status}): ${JSON.stringify(json).slice(0, 200)}`);
+  return { id: f.id, url: f.url };
+}
+
+/** Import an external/generated URL into Wix Media; returns { id, url } (permanent). */
+// docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file.md
+export async function importImage(ctx, url, displayName = "image.png") {
+  const r = await req(ctx, "/site-media/v1/files/import", { url, mimeType: "image/png", displayName });
+  const f = r.file || r;
+  if (!f?.id) throw new Error(`import-file returned no file id: ${JSON.stringify(r).slice(0, 200)}`);
+  return { id: f.id, url: f.url };
+}
+
+/**
+ * THE seed entry point. Resolves a batch of image specs to Wix Media files in ONE parallel
+ * wave. Each spec: { path } (LOCAL file — the user's own asset, uploaded) OR { url }
+ * (verified external URL — imported) OR { prompt } (generated, ~1 credit) — plus optional
+ * displayName, width, height. Returns an array aligned with the input: { id, url } per
+ * success, null per failure or empty spec. Never throws.
+ */
+export async function resolveItemImages(ctx, specs, { perImageBudgetMs = 120_000 } = {}) {
+  // unref: the budget timer must never keep the seed process alive after the work is done —
+  // a lingering timer delays the seed's exit (and the run's .seed-exit marker) by the budget.
+  const deadline = new Promise((r) => {
+    const t = setTimeout(() => r(null), perImageBudgetMs);
+    t.unref?.();
+  });
+  const results = await Promise.allSettled(
+    (specs ?? []).map(async (s) => {
+      if (!s || (!s.path && !s.url && !s.prompt)) return null;
+      const resolve = (async () => {
+        if (s.path) return uploadImage(ctx, s.path, s.displayName);
+        const source = s.url ?? (await generateImage(ctx, s.prompt, { width: s.width, height: s.height }));
+        return importImage(ctx, source, s.displayName ?? "image.png");
+      })();
+      // Hard per-image budget: even a pathological multi-model hang costs the seed at most
+      // perImageBudgetMs of wall clock (the wave is parallel, so it's paid once, not per item).
+      return Promise.race([resolve, deadline]);
+    }),
+  );
+  return results.map((r) => (r.status === "fulfilled" ? r.value : null));
+}

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

@@ -0,0 +1,149 @@
+# Storefront — playbook
+
+The commerce machinery ships as files — data layer, hooks, cart, checkout, SEO plumbing,
+typed end-to-end. **The presentation is yours**: you design and implement the product card,
+the grid, and the PDP surface on the shipped hooks/DTOs, plus the home page and the brand.
+You never write commerce code; you never skip designing the store.
+
+## The file map (deployed into `src/`)
+
+**Don't read the shipped files** — this table and the contracts below are everything you
+need. Open a shipped file's source **only** on a real fallback: a runtime error, a field this
+playbook doesn't cover, or when a *reference* component's pattern is explicitly worth reading
+(marked below). Files you edit: `SiteLayout.astro`, `styles/global.css`, and the two page
+imports you swap to your own components.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` | shared auth seam (deploy configures it — nothing to set by hand) |
+| `wix/media.ts` · `wix/money.ts` | `imgSrc()` / `formatMoney()` — already used by everything shipped |
+| `wix/storefront/types.ts` | the DTOs (`ProductSummary`, `ProductDetail`, `Cart`, `Category`) — contracts inlined below |
+| `wix/storefront/catalog.ts` | `fetchProducts`, `fetchProductsByCategory`, `fetchProductBySlug`, `fetchCategories`, `resolveVariant` |
+| `wix/storefront/cart.ts` · `cart-store.ts` | Cart V2 + shared cart state (module store — spans Astro islands) |
+| `hooks/storefront/useCart.ts` | cart state + actions — contract below |
+| `hooks/storefront/useShop.ts` | listing + live category filter — contract below |
+| `hooks/storefront/useProductDetail.ts` | option selection → variant resolution → add-to-cart — contract below |
+| `components/storefront/CartButton.tsx` · `CartDrawer.tsx` | header badge + slide-over cart — **wire as-is** (drawer once per page) |
+| `components/storefront/ShopView.tsx` · `ProductCard.tsx` · `ProductGrid.tsx` · `ProductDetailView.tsx` · `VariantPicker.tsx` | **REFERENCE implementations** — correct, plain, deliberately generic. Read for patterns if useful; **build your own instead of shipping them** (below) |
+| `styles/global.css` | **the design system**: Tailwind v4 + the `@theme` token block (colors, radii, fonts — same token family as the official Wix templates). Everything, shipped and yours, styles from these tokens |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `layouts/SiteLayout.astro` | the site chrome — **yours to brand**: header, footer, nav. Keep the `<slot name="seo-tags" />`, the global.css import, and the CartButton/CartDrawer mounts |
+| `pages/shop.astro` | SSR listing page — **keep its frontmatter** (the data fetching), swap the island import to YOUR shop component |
+| `pages/products/[slug].astro` | SSR PDP with owner-editable SEO — **keep its frontmatter and the SEO pieces** (`wixMetadata`, `loadSEOTagsServiceConfig`, `<SEO.Tags>`) exactly, swap the island import to YOUR detail component |
+
+## What you build — this is the design job, not optional polish
+
+You implement **four surfaces yourself**, styled with Tailwind utilities on the `@theme`
+tokens, designed to fit the brief (the business, the tone, the audience — a toy brand and a
+jewelry house should not get the same store):
+
+1. **The product card + grid** — your tile design (image treatment, badges, price/sale
+   presentation, hover behavior) and your grid rhythm (columns, density, maybe an editorial
+   featured tile). Keep skeleton-while-loading and an honest empty state (the reference
+   `ProductGrid` shows the pattern — `products === null` → skeletons, `[]` → empty message).
+2. **The shop surface** — category filter + your grid, on `useShop`.
+3. **The PDP surface** — gallery, price/sale, description, your option-selection UI (color
+   options = real swatches), quantity, add-to-cart — on `useProductDetail`, which owns ALL
+   selection/variant logic; you own how it looks.
+4. **The home page** — hero, featured products (fetch in frontmatter → your grid), brand story.
+
+Plus the **theme** (edit the `@theme` block in `styles/global.css` — one edit; a dark brand is
+flipped token values; add brand fonts as extra tokens) and the **chrome** (header/footer in
+`SiteLayout.astro`, one edit pass; mount the shipped `CartButton` in your header).
+
+### The contracts your components consume (everything you need — don't read the source)
+
+```ts
+// ProductSummary (grid tiles) — all display-ready: prices formatted, images https URLs:
+// { id, slug, name, price, maxPrice, compareAtPrice|null, ribbon|null,
+//   availability: "IN_STOCK"|"OUT_OF_STOCK"|"PARTIALLY_OUT_OF_STOCK", preorder: boolean,
+//   imageUrl, hoverImageUrl, optionsSummary /* "2 colors · 3 sizes" */, quickAddable: boolean }
+// price vs maxPrice differ → show a range. quickAddable → useCart().addToCart(product.id).
+
+// useShop({ initialProducts?, initialCategories? }) →
+// { products: ProductSummary[]|null /* null = loading → skeletons */, categories: Category[],
+//   activeCategoryId: string|null, setActiveCategoryId(id|null), loading, error }
+// Category = { id, slug, name }. Render the filter bar only when categories.length > 1.
+
+// useProductDetail({ initial? /* SSR */, slug? /* SPA */ }) →
+// { product: ProductDetail|null, notFound,
+//   optionGroups: [{ id, name, isColor, choices: [{ choiceId, name, colorCode|null, inStock, selected }] }],
+//   selectOption(optionName, choiceName),
+//   modifierValues, setModifier(key, value),          // product.modifiers: pills or text input; "*" = mandatory
+//   price, compareAtPrice,                            // live: variant price once resolved
+//   canAdd,                                           // gate the button; false until every option picked & in stock
+//   quantity, setQuantity, add(), adding, error }
+// ProductDetail adds: descriptionHtml (render as HTML), gallery: string[] (urls, main first),
+// options, modifiers, variants — but selection ALWAYS goes through the hook above.
+
+// useCart() →
+// { cart: { lines, itemCount, subtotal, currency }|null, busy, error, open,
+//   addToCart(productId, variantId?, qty?, extras?), updateQuantity(lineItemId, qty),
+//   removeLine(lineItemId), checkout(), openCart(), closeCart(), refresh() }
+```
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass).
+2. Write your components under `src/components/storefront/` (new file names — don't overwrite
+   the references), then **swap the island import** in `pages/shop.astro` and
+   `pages/products/[slug].astro` to yours — keep each page's frontmatter (data fetching, SEO
+   pieces) exactly as shipped. Primary-content islands mount `client:load` with the SSR props;
+   browser-state widgets (cart) are `client:only="react"` — the shipped mounts show this.
+3. Write `pages/index.astro` (home) on `SiteLayout`.
+
+### Wiring — React SPA (Vite etc.)
+
+Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite
+config plugins — deploy already added the dep). Write route wrappers in the project's router:
+`/shop` → your shop component; `/products/:slug` → your detail component
+(`useProductDetail({ slug })` — components fetch client-side when no `initial` is passed).
+Mount the shipped `CartButton` in the header and `CartDrawer` once. Deploy wrote the public
+client id into `wix/config.ts`; nothing else to configure.
+
+## Hard rules
+
+- **Data and commerce logic only through the shipped exports** — never rewrite their
+  internals or re-derive a request shape. Extend by calling the exports or adding a new
+  function in `wix/storefront/` for a genuine gap (API contracts: the `wix-docs` skill).
+- **Selection→cart goes through `useProductDetail`** — never add a product with options by
+  picking `variants[0]`, and never gate `canAdd` yourself.
+- Don't wrap shipped calls in your own API routes — they run client-side by design.
+- Theme via the `@theme` tokens; your markup uses Tailwind utilities on the same tokens. No
+  parallel theme files, no hardcoded palette values in components.
+- Checkout only through the shipped cart (`checkout()`) — never a hand-built checkout URL.
+- Live data or an honest empty state — never mock products, prices, reviews, or counts.
+- Keep the PDP page's SEO pieces (`wixMetadata` + `loadSEOTagsServiceConfig` + `<SEO.Tags>`)
+  exactly as shipped — owners edit those tags in their dashboard.
+
+## Point the user to their dashboard
+
+Give the owner the dashboard, products, and categories links — **the deploy step's JSON
+output already printed them ready-made** (`dashboardUrl`, `productsUrl`, `categoriesUrl`);
+copy, don't re-derive. Real payments additionally need a premium plan + a connected payment
+method (dashboard) — mention it, don't treat it as a code failure.
+
+## Seeding
+
+Per `seed/SEED.md` — a plain-data `plan.json` into `seed-store.mjs`, run from the project
+root. Independent of the frontend work; seed a catalog that exercises the UI (≥1 product with
+a color option, ≥1 on sale, an image per product) unless the brief says otherwise.
+
+## Verify (before declaring done)
+
+- [ ] `/shop` renders live products SSR (view-source shows product names) through **your**
+      grid/card; category bar filters when categories exist; empty catalog shows your honest
+      empty state.
+- [ ] Your PDP: color options render as swatches, add is disabled until every option is
+      picked (`canAdd`), the resolved variant's price shows, a sale shows the strikethrough.
+- [ ] Cart: add / quantity ± / remove work; badge count is live; subtotal shows; cart survives
+      a reload (same visitor token).
+- [ ] Checkout button redirects to Wix-hosted checkout.
+- [ ] PDP view-source carries the SEO tags (Astro).
+- [ ] Card/grid/PDP/home are YOUR designs on the tokens — not the shipped references; the
+      data-layer/hook/cart files are unedited.
+- [ ] Dashboard links handed to the owner.

package/skills/wix-headless-fast/references/storefront/app/components/storefront/CartButton.tsx

@@ -0,0 +1,26 @@
+// Header cart icon with a live count badge — mount once in your header, as-is.
+// Opens the CartDrawer (mount that once too, anywhere in the page).
+import { useCart } from "../../hooks/storefront/useCart";
+
+export default function CartButton() {
+  const { itemCount, openCart } = useCart();
+  return (
+    <button
+      type="button"
+      aria-label={`Cart, ${itemCount} items`}
+      onClick={openCart}
+      className="relative inline-flex items-center p-1.5 text-foreground transition-opacity hover:opacity-70"
+    >
+      <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6">
+        <path d="M6 2L3 6v14a2 2 0 002 2h14a2 2 0 002-2V6l-3-4z" />
+        <line x1="3" y1="6" x2="21" y2="6" />
+        <path d="M16 10a4 4 0 01-8 0" />
+      </svg>
+      {itemCount > 0 && (
+        <span className="absolute -right-1 -top-1 flex h-[18px] min-w-[18px] items-center justify-center rounded-full bg-primary px-1 text-[10px] font-bold text-primary-foreground">
+          {itemCount}
+        </span>
+      )}
+    </button>
+  );
+}