@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -0,0 +1,109 @@
+// useProductDetail — all PDP logic, no markup: load product by slug, pre-select first in-stock
+// choice per option, resolve the buyer's selections to a Wix variant, gate add-to-cart on stock +
+// mandatory modifiers, and build the addToCart payload. The data paths here (variant resolution,
+// modifier keys, stock gating) are the bug-prone part — keep them verbatim; the PDP page only
+// renders what this returns.
+import { useState, useEffect, useMemo } from "react";
+import { getProductBySlug } from "@/rest/wix-store-catalog";
+import { storeImage } from "@/lib/storeImage";
+import { useCart } from "@/context/CartContext";
+
+export function useProductDetail(slug) {
+  const { addToCart } = useCart();
+  const [product, setProduct] = useState(null);
+  const [notFound, setNotFound] = useState(false);
+  // A missing product (notFound) and a failed request (error) need different pages: one is a dead
+  // link, the other is worth retrying. Without the split, a network blip reads as "product deleted".
+  const [error, setError] = useState(null);
+  const [adding, setAdding] = useState(false);
+  const [selectedOptions, setSelectedOptions] = useState({});
+  const [modifierValues, setModifierValues] = useState({});
+  const [quantity, setQuantity] = useState(1);
+  const [reloadKey, setReloadKey] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setProduct(null);
+    setNotFound(false);
+    setError(null);
+    getProductBySlug(slug)
+      .then((p) => {
+        if (cancelled) return;
+        if (!p) return setNotFound(true);
+        setProduct(p);
+        const initial = {};
+        (p.options || []).forEach((o) => {
+          const first = o.choicesSettings?.choices?.find((c) => c.inStock !== false);
+          if (first) initial[o.id] = first.choiceId;
+        });
+        setSelectedOptions(initial);
+      })
+      .catch((e) => { if (!cancelled) setError(e?.message || "Couldn't load this product."); });
+    return () => { cancelled = true; };
+  }, [slug, reloadKey]);
+
+  const options = product?.options || [];
+  const modifiers = product?.modifiers || [];
+  const variants = product?.variantsInfo?.variants || [];
+
+  const variant = useMemo(() => {
+    if (options.length === 0) return variants[0] || null;
+    if (!options.every((o) => selectedOptions[o.id])) return null;
+    return variants.find((v) => (v.choices || []).every((c) =>
+      selectedOptions[c.optionChoiceIds?.optionId] === c.optionChoiceIds?.choiceId)) || null;
+  }, [options, variants, selectedOptions]);
+
+  const inStock = variant ? variant.inventoryStatus?.inStock !== false : true;
+  const canAdd = useMemo(() => {
+    if (options.length > 0 && !variant) return false;
+    if (variant && !inStock) return false;
+    return modifiers.filter((m) => m.mandatory).every((m) =>
+      m.modifierRenderType === "FREE_TEXT" ? !!modifierValues[m.freeTextSettings?.key] : !!modifierValues[m.key]);
+  }, [options, variant, inStock, modifiers, modifierValues]);
+
+  const price = variant?.price?.actualPrice?.formattedAmount || product?.actualPriceRange?.minValue?.formattedAmount || "";
+
+  // A colour choice carries `linkedMedia` — the shots of the product in that colour. Picking "Dark
+  // Green" should move the gallery to the green photo, so resolve the selection to a URL here; only
+  // colour-style choices have linked media, so the first hit across the options is the right one.
+  const focusMediaUrl = useMemo(() => {
+    for (const o of options) {
+      const choice = (o.choicesSettings?.choices || []).find((c) => c.choiceId === selectedOptions[o.id]);
+      const url = storeImage(choice?.linkedMedia?.[0]);
+      if (url) return url;
+    }
+    return null;
+  }, [options, selectedOptions]);
+
+  const selectOption = (optionId, choiceId) => setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
+  const setModifier = (key, value) => setModifierValues((s) => ({ ...s, [key]: value }));
+
+  async function submit() {
+    const modifierChoices = {}, customTextFields = {};
+    modifiers.forEach((m) => {
+      const k = m.modifierRenderType === "FREE_TEXT" ? m.freeTextSettings?.key : m.key;
+      if (!k || !modifierValues[k]) return;
+      (m.modifierRenderType === "FREE_TEXT" ? customTextFields : modifierChoices)[k] = modifierValues[k];
+    });
+    setAdding(true);
+    try {
+      // addToCart reports its own failures through the cart context (it opens the drawer with the
+      // reason), so nothing is swallowed by leaving this unguarded beyond resetting the button.
+      // Coerce the quantity: the shipped stepper lets the field sit empty mid-edit, and a keyboard
+      // submit from that state would otherwise post "" as the quantity.
+      await addToCart(product.id, variant?.id, Math.max(1, Number(quantity) || 1), {
+        modifierChoices: Object.keys(modifierChoices).length ? modifierChoices : undefined,
+        customTextFields: Object.keys(customTextFields).length ? customTextFields : undefined,
+      });
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return {
+    product, notFound, error, retry: () => setReloadKey((k) => k + 1),
+    options, modifiers,
+    selectedOptions, selectOption, modifierValues, setModifier,
+    quantity, setQuantity, variant, inStock, canAdd, adding, price, submit, focusMediaUrl,
+  };
+}

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

@@ -0,0 +1,98 @@
+// useShop — all catalog-listing logic, no markup: load the category menu, load a page of products for
+// the active category, append the next page on demand, sort client-side, and surface a failure instead
+// of leaving the page on a spinner. The Shop page only renders what this returns.
+//
+// Load-bearing:
+// • paging is CURSOR-based. Keep the cursor from the previous response and pass it back; a cursor
+//   follow-up reuses the original filter, so the category is fixed for the life of that cursor.
+//   Changing category starts a fresh query, never a cursor continuation.
+// • queryCategories returns the auto-created "all-products" system category alongside real ones, and
+//   `visible` does not flag it — filter it by slug or the menu shows a duplicate of everything.
+// • sorting is done here on the loaded page, not by the API: with cursor paging the server would
+//   re-sort per page, so a sort applied across pages already fetched is the honest option. Say so in
+//   the UI if the catalog is larger than one page.
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { queryProducts, queryProductsByCategory, queryCategories } from "@/rest/wix-store-catalog";
+
+const SYSTEM_CATEGORY_SLUG = "all-products";
+export const SORTS = {
+  featured: { label: "Featured" },
+  priceAsc: { label: "Price: low to high" },
+  priceHigh: { label: "Price: high to low" },
+  name: { label: "Name: A–Z" },
+};
+
+// Prices arrive formatted for display ("$12.00"), so read the numeric value for sorting from the
+// amount when it's there and fall back to digits in the formatted string.
+function priceOf(product) {
+  const min = product?.actualPriceRange?.minValue;
+  const n = Number(min?.amount ?? String(min?.formattedAmount || "").replace(/[^\d.]/g, ""));
+  return Number.isFinite(n) ? n : 0;
+}
+
+export function useShop({ pageSize = 24 } = {}) {
+  const [categories, setCategories] = useState([]);
+  const [activeCategory, setActiveCategory] = useState(null); // null = everything
+  const [products, setProducts] = useState(null);             // null = first load
+  const [cursor, setCursor] = useState(null);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [error, setError] = useState(null);
+  const [sort, setSort] = useState("featured");
+
+  useEffect(() => {
+    queryCategories({ limit: 100 })
+      .then(({ categories: list }) =>
+        setCategories((list || []).filter((c) => c.visible !== false && c.slug !== SYSTEM_CATEGORY_SLUG)))
+      .catch(() => setCategories([]));   // a store without categories is normal, not an error
+  }, []);
+
+  const load = useCallback(async (categoryId) => {
+    setProducts(null);
+    setCursor(null);
+    setError(null);
+    try {
+      const res = categoryId
+        ? await queryProductsByCategory(categoryId, { limit: pageSize })
+        : await queryProducts({ limit: pageSize });
+      setProducts(res.products);
+      setCursor(res.nextCursor);
+    } catch (e) {
+      setError(e?.message || "Couldn't load products.");
+      setProducts([]);
+    }
+  }, [pageSize]);
+
+  useEffect(() => { load(activeCategory?.id ?? null); }, [activeCategory, load]);
+
+  const loadMore = async () => {
+    if (!cursor || loadingMore) return;
+    setLoadingMore(true);
+    try {
+      const res = activeCategory
+        ? await queryProductsByCategory(activeCategory.id, { limit: pageSize, cursor })
+        : await queryProducts({ limit: pageSize, cursor });
+      setProducts((prev) => [...(prev || []), ...res.products]);
+      setCursor(res.nextCursor);
+    } catch (e) {
+      setError(e?.message || "Couldn't load more products.");
+    } finally {
+      setLoadingMore(false);
+    }
+  };
+
+  const sorted = useMemo(() => {
+    if (!products) return null;
+    const copy = [...products];
+    if (sort === "priceAsc") copy.sort((a, b) => priceOf(a) - priceOf(b));
+    else if (sort === "priceHigh") copy.sort((a, b) => priceOf(b) - priceOf(a));
+    else if (sort === "name") copy.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
+    return copy;
+  }, [products, sort]);
+
+  return {
+    categories, activeCategory, setActiveCategory,
+    products: sorted, loading: products === null, error,
+    hasMore: !!cursor, loadMore, loadingMore,
+    sort, setSort, retry: () => load(activeCategory?.id ?? null),
+  };
+}

package/skills/wix-vibe-headless/references/storefront/app/lib/storeImage.js

@@ -0,0 +1,27 @@
+// storeImage — turn a Wix Stores image value into a URL the browser can load.
+// Wix returns these protocol-relative (`//static.wixstatic.com/...`), which resolves against the
+// current page. That works on https pages and breaks on anything else, so normalise it once here
+// instead of at each call site — product media, PDP gallery items, and cart line items all carry the
+// same shape. Returns null for a missing value so callers can render a placeholder.
+export function storeImage(value) {
+  const url = typeof value === "string" ? value : value?.image?.url || value?.url;
+  if (!url) return null;
+  if (url.startsWith("//")) return `https:${url}`;
+  return url;
+}
+
+// The main catalog image for a product (grid tiles, cart fallbacks).
+export function productImage(product) {
+  return storeImage(product?.media?.main?.image?.url);
+}
+
+// Every gallery image for a product, main first, de-duplicated — `media.itemsInfo.items` repeats the
+// main image, and video items carry no `image.url`. Returns [{ url, altText }].
+export function productGallery(product) {
+  const items = product?.media?.itemsInfo?.items || [];
+  const urls = [productImage(product), ...items.map((i) => storeImage(i))];
+  const seen = new Set();
+  return urls
+    .map((url, i) => ({ url, altText: items[i - 1]?.altText || product?.name || "" }))
+    .filter(({ url }) => url && !seen.has(url) && seen.add(url));
+}

package/skills/wix-vibe-headless/references/storefront/app/pages/ProductDetail.jsx

@@ -0,0 +1,139 @@
+// PDP — thin view over useProductDetail (all logic lives in the hook). plainDescription is HTML
+// despite the name; render via dangerouslySetInnerHTML. Styled with base44 design tokens (shadcn Tailwind classes).
+//
+// The price shown follows the selection: once options resolve to a variant the hook returns that
+// variant's price, so a picked size can cost more than the "from" figure the grid tile showed.
+import { useMemo } from "react";
+import { Link, useParams } from "react-router-dom";
+import { useProductDetail } from "@/hooks/useProductDetail";
+import { productGallery } from "@/lib/storeImage";
+import ProductGallery from "@/components/ProductGallery";
+import VariantPicker from "@/components/VariantPicker";
+
+export default function ProductDetail() {
+  const { slug } = useParams();
+  const d = useProductDetail(slug);
+  // Memoised so the gallery keeps its selected image across re-renders (see ProductGallery).
+  const images = useMemo(() => productGallery(d.product), [d.product]);
+
+  if (d.error) {
+    return (
+      <Centered>
+        <p className="m-0">{d.error}</p>
+        <button onClick={d.retry} className="border border-border bg-card text-foreground rounded-sm py-2 px-4 cursor-pointer text-sm">Try again</button>
+      </Centered>
+    );
+  }
+  if (d.notFound) {
+    return (
+      <Centered>
+        <p className="m-0">We couldn't find that product.</p>
+        <Link to="/shop" className="text-primary">Back to shop</Link>
+      </Centered>
+    );
+  }
+  if (!d.product) return <ProductDetailSkeleton />;
+
+  const compareAt = d.product?.compareAtPriceRange?.minValue?.formattedAmount;
+
+  return (
+    <main className="max-w-[1200px] mx-auto p-4">
+      <nav aria-label="Breadcrumb" className="mb-4 text-sm text-muted-foreground">
+        <Link to="/shop" className="text-muted-foreground hover:text-foreground">Shop</Link>
+        <span aria-hidden="true"> / </span>
+        <span className="text-foreground">{d.product.name}</span>
+      </nav>
+
+      <div className="grid gap-8 [grid-template-columns:repeat(auto-fit,minmax(320px,1fr))]">
+        <ProductGallery images={images} name={d.product.name} focusUrl={d.focusMediaUrl} />
+
+        <div>
+          <h1 className="font-display m-0 mb-2">{d.product.name}</h1>
+
+          <div className="flex items-baseline gap-2 mb-4">
+            <p className="text-[22px] font-semibold m-0">{d.price}</p>
+            {compareAt && compareAt !== d.price && (
+              <span className="text-muted-foreground line-through">{compareAt}</span>
+            )}
+          </div>
+
+          {d.product.plainDescription && (
+            <div className="text-muted-foreground leading-relaxed mb-6"
+              dangerouslySetInnerHTML={{ __html: d.product.plainDescription }} />
+          )}
+
+          <VariantPicker
+            options={d.options} modifiers={d.modifiers}
+            selectedOptions={d.selectedOptions} selectOption={d.selectOption}
+            modifierValues={d.modifierValues} setModifier={d.setModifier}
+          />
+
+          {/* Tell the buyer WHY the button is dead: an unresolvable combination reads as a broken page. */}
+          {d.options.length > 0 && !d.variant && (
+            <p className="text-[13px] text-muted-foreground m-0 mt-1">Pick an option from each list to continue.</p>
+          )}
+
+          <div className="flex items-stretch gap-3 mt-4">
+            <QuantityStepper value={d.quantity} onChange={d.setQuantity} disabled={!d.inStock} />
+            <button disabled={!d.canAdd || d.adding} onClick={d.submit}
+              className="flex-1 h-12 px-6 bg-primary text-primary-foreground border-none rounded-md text-[15px] font-semibold cursor-pointer transition-opacity hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed">
+              {d.adding ? "Adding…" : d.inStock ? "Add to cart" : "Out of stock"}
+            </button>
+          </div>
+        </div>
+      </div>
+    </main>
+  );
+}
+
+// Segmented −/+ stepper, height-matched to the Add-to-cart button so the row reads as one control.
+// A native number input is avoided on purpose: its spinners are ~10px, OS-rendered (so they ignore
+// the app's tokens), effectively untappable, and they accept "e"/"+"/"1e5" plus scroll-wheel edits.
+// The value stays typeable — inputMode="numeric" brings up a keypad — but only digits survive, and
+// blur restores 1 when the field is left empty. `tabular-nums` keeps the width steady across digits.
+function QuantityStepper({ value, onChange, disabled }) {
+  const set = (n) => onChange(Math.max(1, n));
+  return (
+    <div data-disabled={disabled || undefined}
+      className="inline-flex items-stretch h-12 rounded-md border border-input bg-background overflow-hidden data-[disabled]:opacity-50">
+      <StepButton label="Decrease quantity" disabled={disabled || value <= 1} onClick={() => set(value - 1)}>−</StepButton>
+      <label className="sr-only" htmlFor="pdp-qty">Quantity</label>
+      <input id="pdp-qty" type="text" inputMode="numeric" autoComplete="off" disabled={disabled}
+        value={value} aria-live="polite"
+        onChange={(e) => { const n = e.target.value.replace(/\D/g, ""); onChange(n === "" ? "" : Math.max(1, Number(n))); }}
+        onBlur={(e) => { if (!e.target.value) set(1); }}
+        className="w-12 text-center bg-transparent text-foreground font-semibold tabular-nums border-x border-input outline-none focus-visible:ring-2 focus-visible:ring-primary/40 disabled:cursor-not-allowed" />
+      <StepButton label="Increase quantity" disabled={disabled} onClick={() => set(Number(value || 0) + 1)}>+</StepButton>
+    </div>
+  );
+}
+
+function StepButton({ children, label, onClick, disabled }) {
+  return (
+    <button type="button" onClick={onClick} disabled={disabled} aria-label={label}
+      className="w-11 grid place-items-center text-lg leading-none text-muted-foreground bg-transparent border-none cursor-pointer transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-transparent">
+      {children}
+    </button>
+  );
+}
+
+function ProductDetailSkeleton() {
+  return (
+    <main className="max-w-[1200px] mx-auto p-4" aria-busy="true">
+      <div className="grid gap-8 [grid-template-columns:repeat(auto-fit,minmax(320px,1fr))]">
+        <div className="aspect-square bg-muted rounded-lg animate-pulse" />
+        <div className="flex flex-col gap-3">
+          <div className="h-7 w-2/3 bg-muted rounded-sm animate-pulse" />
+          <div className="h-6 w-24 bg-muted rounded-sm animate-pulse" />
+          <div className="h-4 w-full bg-muted rounded-sm animate-pulse mt-3" />
+          <div className="h-4 w-5/6 bg-muted rounded-sm animate-pulse" />
+          <div className="h-11 w-full bg-muted rounded-sm animate-pulse mt-6" />
+        </div>
+      </div>
+    </main>
+  );
+}
+
+function Centered({ children }) {
+  return <div className="p-12 flex flex-col items-center gap-3 text-center text-muted-foreground">{children}</div>;
+}

package/skills/wix-vibe-headless/references/storefront/app/pages/Shop.jsx

@@ -0,0 +1,75 @@
+// Shop / catalog page — thin view over useShop (all logic lives in the hook). Category menu, sort,
+// cursor paging, plus the loading / empty / failed states a seeded-separately catalog needs.
+// Styled with base44 design tokens (shadcn Tailwind classes).
+import { useShop, SORTS } from "@/hooks/useShop";
+import ProductGrid from "@/components/ProductGrid";
+
+export default function Shop() {
+  const s = useShop();
+  const showCategories = s.categories.length > 0;
+
+  return (
+    <main className="max-w-[1200px] mx-auto p-4">
+      <div className="flex flex-wrap items-end justify-between gap-3 mb-4">
+        <h1 className="font-display m-0">{s.activeCategory?.name || "Shop"}</h1>
+        {s.products?.length > 0 && (
+          <label className="flex items-center gap-2 text-sm text-muted-foreground">
+            Sort
+            <select value={s.sort} onChange={(e) => s.setSort(e.target.value)}
+              className="py-1.5 px-2 border border-input rounded-sm bg-background text-foreground text-sm">
+              {Object.entries(SORTS).map(([key, { label }]) => <option key={key} value={key}>{label}</option>)}
+            </select>
+          </label>
+        )}
+      </div>
+
+      {showCategories && (
+        <nav aria-label="Categories" className="flex flex-wrap gap-2 mb-6">
+          <CategoryChip active={!s.activeCategory} onClick={() => s.setActiveCategory(null)}>All</CategoryChip>
+          {s.categories.map((c) => (
+            <CategoryChip key={c.id} active={s.activeCategory?.id === c.id} onClick={() => s.setActiveCategory(c)}>
+              {c.name}
+            </CategoryChip>
+          ))}
+        </nav>
+      )}
+
+      {s.error ? (
+        <div role="alert" className="flex flex-col items-center gap-3 py-16 text-center">
+          <p className="m-0 text-muted-foreground">{s.error}</p>
+          <button onClick={s.retry}
+            className="border border-border bg-card text-foreground rounded-sm py-2 px-4 cursor-pointer text-sm">Try again</button>
+        </div>
+      ) : (
+        <>
+          <ProductGrid
+            products={s.products}
+            loading={s.loading}
+            empty={s.activeCategory ? `Nothing in ${s.activeCategory.name} yet.` : "No products yet."}
+            emptyHint={s.activeCategory
+              ? "Pick another category, or add products to this one from your Wix dashboard."
+              : "Add products in your Wix dashboard and they'll appear here — no redeploy needed."}
+          />
+
+          {s.hasMore && (
+            <div className="flex justify-center mt-8">
+              <button onClick={s.loadMore} disabled={s.loadingMore}
+                className="border border-border bg-card text-foreground rounded-sm py-2.5 px-6 cursor-pointer text-sm font-semibold disabled:opacity-60 disabled:cursor-wait">
+                {s.loadingMore ? "Loading…" : "Load more"}
+              </button>
+            </div>
+          )}
+        </>
+      )}
+    </main>
+  );
+}
+
+function CategoryChip({ active, onClick, children }) {
+  return (
+    <button onClick={onClick} aria-pressed={active}
+      className={`py-1.5 px-3 cursor-pointer text-sm rounded-sm border ${
+        active ? "border-primary bg-primary text-primary-foreground" : "border-border bg-card text-foreground"
+      }`}>{children}</button>
+  );
+}

package/skills/wix-vibe-headless/references/storefront/{wix-store-cart.js → app/rest/wix-store-cart.js}

@@ -8,7 +8,7 @@ const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
 
 /**
  * Wix eCom Cart — key fields for building a cart UI.
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/get-cart.md
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md
  *
  *   id {string}, currency {string},
  *   lineItems[].id {string} — lineItemId for update/remove (NOT catalogItemId),

package/skills/wix-vibe-headless/references/storefront/{wix-store-catalog.js → app/rest/wix-store-catalog.js}

@@ -13,14 +13,35 @@ import { wixApiRequest } from "./wix-client.js";
  *   actualPriceRange.minValue.formattedAmount {string} — lowest price with currency symbol,
  *   actualPriceRange.maxValue.formattedAmount {string} — highest price with currency symbol,
  *   compareAtPriceRange.minValue.formattedAmount {string} — strikethrough price (present when on sale),
+ *   actualPriceRange/compareAtPriceRange .minValue.amount {string} — the same figures unformatted
+ *     ("129.00"). Use these for arithmetic: a percent-off badge can't be computed from "€129.00",
  *   inventory.availabilityStatus {string} — "IN_STOCK"|"OUT_OF_STOCK"|"PARTIALLY_OUT_OF_STOCK",
+ *   inventory.preorderStatus {string} — "ENABLED"|"DISABLED". ENABLED + OUT_OF_STOCK is a pre-order,
+ *     which is buyable — label it "Pre-order" rather than "Sold out",
+ *     NB: inventory carries no stock COUNT. "Limited stock" (from PARTIALLY_OUT_OF_STOCK) is the most
+ *     precise scarcity signal a tile can show; "Only 2 left" needs per-variant inventory, i.e. a
+ *     getProductBySlug call per product,
+ *   ribbon {object} — { id, name } merchant-set badge: "New", "Sale", "Best Seller". This is the
+ *     catalogue's own label, so prefer it over anything derived — a "new" badge computed from
+ *     createdDate flags every product at once right after seeding,
+ *   additionalRibbons {array} — further { id, name } badges,
+ *   createdDate / updatedDate {string} — ISO timestamps,
+ *   variantSummary.variantCount {number} — how many variants exist, without fetching them,
  *   options {array} — product options e.g. Size, Color:
  *     [{ id, name, optionRenderType "TEXT_CHOICES"|"COLOR_CHOICES"|"SWATCH_CHOICES",
- *        choicesSettings.choices [{ choiceId, key, name, inStock, visible, linkedMedia }] }],
+ *        choicesSettings.choices [{ choiceId, key, name, inStock, visible, choiceType, colorCode,
+ *                                   linkedMedia }] }],
+ *     A COLOR/SWATCH option's choices carry choiceType "ONE_COLOR" and colorCode "#395E55" — render
+ *     those as real colour swatches, not text pills. linkedMedia [{ image.url }] holds that colour's
+ *     photos, so selecting a swatch can move the gallery to the matching shot. visible false is a
+ *     retired choice the merchant no longer sells: filter it out. (TEXT_CHOICES choices are
+ *     choiceType "CHOICE_TEXT" with no colorCode.)
  *   modifiers {array} — non-variant customizations (engraving, gift wrap):
  *     [{ id, name, mandatory, modifierRenderType "TEXT_CHOICES"|"FREE_TEXT",
  *        key, choicesSettings.choices, freeTextSettings.key }],
- *   plainDescription {string} — HTML product description,
+ *   plainDescription {string} — product description as an HTML string (contains <p>, <br>,
+ *     <strong>…) despite the "plain" name — NOT plain text. Render with innerHTML /
+ *     dangerouslySetInnerHTML; strip tags only for plain-text contexts (meta description, teaser),
  *   variantsInfo.variants {array} — returned only by getProductBySlug:
  *     [{ id, visible, choices [{ optionChoiceIds: { optionId, choiceId } }],
  *        price: { actualPrice, compareAtPrice }, media, inventoryStatus: { inStock } }]
@@ -28,6 +49,8 @@ import { wixApiRequest } from "./wix-client.js";
  *     match all selected { optionId, choiceId } pairs, then pass variant.id to addToCart.
  *
  * Category: { id, name, slug, visible, description, image, itemCounter, parentCategory.id }
+ *   NB: queryCategories includes the auto-created system category { slug: "all-products" } —
+ *   filter it out of a category menu (see INSTRUCTIONS.md). `visible` does not flag it.
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories
  */
 

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

@@ -0,0 +1,111 @@
+# Storefront — seeding
+
+Seed a Wix Stores catalog by **calling `seed-store.js`** — don't hand-write the REST calls. It's
+a build-time module (run via `exec_tool`, not shipped in the app) that abstracts every Wix Stores
+seed operation. Load it and call **`setupStore` — the one-call path** — with plain data.
+
+```js
+// build-time exec_tool
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const fs = require("fs");
+// exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
+const seed = (() => { const m = { exports: {} };
+  new Function("module", "exports", "require", fs.readFileSync("/app/.agents/skills/wix-vibe-headless/references/storefront/seed/seed-store.js", "utf8"))(m, m.exports, require);
+  return m.exports; })();
+const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+
+// ONE call: install (+ wait for V3) → create products → categories → attach images, ids kept
+// in memory (no hand-threading). Categories map name -> product NAMES. Pass an imageUrl per product
+// to attach its image; omit it to skip images.
+// imageUrl must be the FINAL https://media.base44.com/... url from the COMPLETED generate_image
+// result — not a still-generating /__generating__/<id>.png placeholder (Wix can't fetch that).
+// generate_image runs in the background while you build, so the urls are ready by seed time.
+const result = await seed.setupStore(ctx, {
+  products: [
+    { name: "The Glam Rocker", description: "Sequin-studded velvet legend…", price: 49.99, quantity: 12, imageUrl: imageUrls[0] },
+    // a product with buyer choices — see "Options, variants and sale prices" below
+    { name: "The Understudy", description: "…", price: 245, quantity: 8, imageUrl: imageUrls[1],
+      options: [{ name: "Color", type: "color", choices: [{ name: "Ink", colorCode: "#1B1B2F" }, { name: "Bone", colorCode: "#EDE6D6" }] }] },
+    // a product on sale — compareAtPrice drives the strikethrough + the tile's percent-off badge
+    { name: "Encore Jacket", description: "…", price: 68, compareAtPrice: 129, quantity: 5, imageUrl: imageUrls[2] },
+  ],
+  categories: { "Legends": ["The Glam Rocker"], "Rising Stars": [] },   // omit if the brief names none
+});
+// result: { products:[{id,slug,revision,name}], categories:[{id,name}], imagesAttached }
+```
+
+**Seeding is additive — never delete or overwrite existing content.** Don't clean up, don't remove
+"sample" data, don't reset. Just add.
+
+## Options, variants and sale prices
+
+The shipped storefront renders colour options as real swatches, shows a size/colour summary on each
+tile, and puts a percent-off badge on a discounted product. A catalog of plain single-price products
+leaves all of that invisible, so **seed a catalog that exercises it**: unless the brief says
+otherwise, give at least one product a colour option and put one product on sale. Keep it truthful
+to the business — a ceramics studio has glaze colours, a bakery does not.
+
+```js
+options: [
+  { name: "Color", type: "color", choices: [{ name: "Ink", colorCode: "#1B1B2F" }, { name: "Bone", colorCode: "#EDE6D6" }] },
+  { name: "Size",  type: "text",  choices: ["Small", "Medium", "Large"] },   // or [{ name: "Small" }, …]
+]
+```
+
+- `type: "color"` → `SWATCH_CHOICES` with each choice's `colorCode`, which the PDP draws as a swatch.
+  Any other `type` → text pills. Give every colour choice a `colorCode`.
+- Variants are expanded for you: the full cross-product of the options, each carrying the product's
+  `price`, `compareAtPrice` and `quantity`. Two options with 2 and 3 choices means 6 variants — keep
+  option counts small.
+- `compareAtPrice` (> `price`) is the "was" price: strikethrough on the PDP and a `−N%` badge on the
+  tile, computed from the two amounts. It works with or without options.
+
+Two things this module does **not** seed, so don't try:
+
+- **Ribbons** ("New", "Best Seller"). The tile renders `product.ribbon` when it's there, but ribbons
+  are set in the Wix dashboard — tell the merchant that's where to add them.
+- **Per-choice linked media** (`linkedMedia`), which is what makes picking a colour swap the gallery
+  photo. Seeded swatches select and price correctly; the gallery just doesn't follow the colour until
+  the merchant links photos to choices in the dashboard.
+
+## Escape hatch — individual functions
+Reach for the functions below only when the one-call `setupStore` doesn't fit (partial re-seed, custom
+ordering, mid-flow checks). `setupStore` is built from them, in this order:
+
+```js
+await seed.installStoresApp(ctx);                                     // install + wait for the V3 catalog
+const products = await seed.bulkCreateProducts(ctx, [                 // → [{id,slug,revision}], in stock by `quantity`
+  { name: "The Glam Rocker", description: "…", price: 49.99, quantity: 12 },
+]);
+const cats = await seed.createCategories(ctx, ["Legends"]);           // sequential → [{id,name}]
+await seed.addProductsToCategories(ctx, { [cats[0].id]: [products[0].id] });
+// images: use the FINAL https://media.base44.com/... url only (never a /__generating__/ placeholder)
+await seed.attachProductImages(ctx, products.map((p, i) => ({ id: p.id, url: imageUrls[i], altText: p.slug })));
+```
+
+## Functions
+| fn | does |
+|---|---|
+| `setupStore(ctx, {products, categories?})` | **one-call**: install+wait → products → categories → images |
+| `installStoresApp(ctx)` | install the Wix Stores app on the site (waits for the V3 catalog) |
+| `bulkCreateProducts(ctx, products)` | one bulk create → `[{id,slug,revision}]`; products come out in stock with the `quantity` you pass |
+| `createCategories(ctx, names)` | sequential (shared tree 409s on concurrent) → `[{id,name}]` |
+| `addProductsToCategories(ctx, {catId:[pid]})` | sequential add-items |
+| `attachProductImages(ctx, [{id,url,altText}])` | one bulk media attach; no revision to pass. Wix re-hosts each url server-side; the media can take a little while to appear on read-back (propagation) — normal, not a failure |
+
+## Reference
+If a call returns a shape you didn't expect, or you need an operation this module doesn't cover,
+use the **`wix-docs`** skill to search + read the live Wix API reference — never guess. The
+authoritative source recipe is `wix-headless/references/inline-recipes/setup-online-store.md`.
+
+Read a method's page before writing its call: it carries the exact body shape, the required
+permission scope, and the response envelope.
+- Install a Wix app onto the site: https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/install-app.md
+- Import an image into Wix Media: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file.md
+- Create Category: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/create-category.md
+- Bulk Update Categories: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-update-categories.md
+- Bulk Add Items To Category: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-add-items-to-category.md
+- Bulk Create Products With Inventory: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-create-products-with-inventory.md
+- Bulk Update Products: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-update-products.md
+- Bulk Create Inventory Items: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/bulk-create-inventory-items.md
+- Query Products: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md