@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-vibe-headless/references/storefront/app/components/CartButton.jsx

@@ -1,20 +0,0 @@
-// Header cart trigger — an icon button with a live item-count badge. Drop into the app header; opens the CartDrawer.
-// Icon-only by design (no "Cart" text): reads the header's currentColor, so it inherits the brand automatically.
-import { useCart } from "@/context/CartContext";
-
-export default function CartButton() {
-  const { itemCount, setIsOpen } = useCart();
-  return (
-    <button onClick={() => setIsOpen(true)} aria-label={`Open cart${itemCount ? `, ${itemCount} item${itemCount > 1 ? "s" : ""}` : ""}`}
-      className="relative inline-flex items-center justify-center w-10 h-10 p-0 cursor-pointer bg-transparent text-current border-none rounded-sm">
-      <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
-        <path d="M6 2 3 6v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V6l-3-4Z" />
-        <path d="M3 6h18" />
-        <path d="M16 10a4 4 0 0 1-8 0" />
-      </svg>
-      {itemCount > 0 && (
-        <span className="absolute -top-0.5 -right-0.5 min-w-[18px] h-[18px] px-[5px] py-0 inline-flex items-center justify-center text-[11px] font-semibold bg-primary text-primary-foreground rounded-full">{itemCount}</span>
-      )}
-    </button>
-  );
-}

package/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx

@@ -1,167 +0,0 @@
-// Slide-over cart. Reads everything from useCart(); mutate by lineItem.id (NOT catalogItemId),
-// check out via the context (redirect-session URL). Styled with base44 design tokens (shadcn Tailwind classes).
-//
-// Load-bearing beyond the styling:
-// • prices come from the SERVER cart. In Cart V2 each line total is `pricing.totalPrice`, a
-//   ConvertedMoney { amount, convertedAmount } with NO formatted string — format it yourself with the
-//   cart's currency (see formatCartMoney). Never compute a total in the client: tax, shipping and
-//   promotions are resolved server-side. The V2 cart has no `subtotalAfterDiscounts`/`discount` —
-//   the after-discount subtotal and the cart-level discount come from the estimate the context keeps
-//   in `summary.priceSummary`; the raw cart `subtotal` is the fallback while it's unknown.
-// • `quantityInfo.availableQuantity` caps the stepper, so exceeding stock is refused here rather than
-//   at checkout.
-// • `status` is flagged per line here because checkout() refuses the whole cart when any item isn't
-//   IN_STOCK — showing it on the row is what makes that refusal understandable.
-import { useEffect, useRef } from "react";
-import { useCart } from "@/context/CartContext";
-import { storeImage } from "@/lib/storeImage";
-
-// Cart V2 money is a ConvertedMoney { amount, convertedAmount } with NO formatted string — format it
-// with the cart's currency (buyer's display currency when present, else the site currency).
-function formatCartMoney(money, cart) {
-  const value = money?.convertedAmount ?? money?.amount;
-  const currency = cart?.customerInfo?.currencyCode ?? cart?.businessInfo?.currencyCode ?? "USD";
-  return value == null ? "" : new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
-}
-
-export default function CartDrawer() {
-  const { cart, summary, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading, error, clearError } = useCart();
-  const lineItems = cart?.lineItems ?? [];
-  // Totals come from the estimate the context keeps next to the cart (after-discount subtotal, the
-  // cart-level discount). While it's unknown, or if it failed, fall back to the cart's raw subtotal.
-  // Delivery and tax are NOT in here — they resolve at checkout, and the footer says so.
-  const subtotal = formatCartMoney(summary?.priceSummary?.subtotal ?? cart?.subtotal, cart);
-  const discountAmount = Number(summary?.priceSummary?.discount?.convertedAmount ?? summary?.priceSummary?.discount?.amount ?? 0);
-  const discount = discountAmount > 0 ? formatCartMoney(summary.priceSummary.discount, cart) : "";
-  const unavailable = lineItems.filter((li) => li.status && li.status !== "IN_STOCK");
-
-  // The overlay contract, verified in the browser rather than assumed from CSS: Escape closes (the
-  // backdrop click is pointer-only), the page behind stops scrolling, focus moves into the panel on
-  // open and returns to whatever opened it on close.
-  const panelRef = useRef(null);
-  useEffect(() => {
-    if (!isOpen) return;
-    const opener = document.activeElement;
-    const previousOverflow = document.body.style.overflow;
-    document.body.style.overflow = "hidden";
-    panelRef.current?.focus();
-    const onKey = (e) => e.key === "Escape" && setIsOpen(false);
-    document.addEventListener("keydown", onKey);
-    return () => {
-      document.removeEventListener("keydown", onKey);
-      document.body.style.overflow = previousOverflow;
-      if (opener instanceof HTMLElement) opener.focus();
-    };
-  }, [isOpen, setIsOpen]);
-
-  if (!isOpen) return null;
-
-  return (
-    <div onClick={() => setIsOpen(false)} className="fixed inset-0 z-50 bg-black/40 flex justify-end">
-      <aside ref={panelRef} tabIndex={-1} onClick={(e) => e.stopPropagation()} role="dialog" aria-modal="true" aria-label="Your cart"
-        className="w-[min(420px,100%)] h-full flex flex-col bg-background text-foreground border-l border-border font-body outline-none">
-        <header className="flex justify-between items-center p-4 border-b border-border">
-          <strong className="font-display">Your cart{lineItems.length ? ` (${lineItems.length})` : ""}</strong>
-          <button onClick={() => setIsOpen(false)} aria-label="Close cart"
-            className="border-none bg-transparent cursor-pointer text-xl text-muted-foreground">×</button>
-        </header>
-
-        {error && (
-          <div role="alert" className="m-4 mb-0 p-3 rounded-sm border border-destructive/40 bg-destructive/10 text-sm">
-            <div className="flex items-start gap-2">
-              <span className="flex-1">{error}</span>
-              <button onClick={clearError} aria-label="Dismiss"
-                className="border-none bg-transparent cursor-pointer text-muted-foreground leading-none">×</button>
-            </div>
-          </div>
-        )}
-
-        <div className="flex-1 overflow-y-auto p-4">
-          {lineItems.length === 0 ? (
-            <div className="h-full flex flex-col items-center justify-center text-center gap-3 py-10">
-              <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5"
-                className="text-muted-foreground/40" aria-hidden="true">
-                <path d="M6 2 3 6v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V6l-3-4Z" /><path d="M3 6h18" />
-                <path d="M16 10a4 4 0 0 1-8 0" />
-              </svg>
-              <p className="m-0 text-muted-foreground">Your cart is empty.</p>
-              <button onClick={() => setIsOpen(false)}
-                className="border border-border bg-card text-foreground rounded-sm py-2 px-4 cursor-pointer text-sm">Continue shopping</button>
-            </div>
-          ) : lineItems.map((item) => {
-            const image = storeImage(item.attributes?.image?.url);
-            const paid = formatCartMoney(item.pricing?.totalPrice, cart);
-            const isOut = item.status && item.status !== "IN_STOCK";
-            const stock = item.quantityInfo?.availableQuantity;
-            const qty = item.quantityInfo?.confirmedQuantity;
-            const atStockLimit = Number.isFinite(stock) && qty >= stock;
-            return (
-              <div key={item.id} className="flex gap-3 py-3 px-0 border-b border-border">
-                <div className="w-16 h-16 shrink-0 rounded-sm bg-card overflow-hidden">
-                  {image && <img src={image} alt={item.name?.original || ""} className="w-full h-full object-cover" />}
-                </div>
-                <div className="flex-1 flex flex-col gap-1 min-w-0">
-                  <span className="font-semibold truncate">{item.name?.original}</span>
-                  {/* V2 nests these under `attributes` — a top-level lineItem.descriptionLines no longer exists */}
-                  {item.attributes?.descriptionLines?.map((dl, i) => (
-                    <small key={i} className="text-muted-foreground">
-                      {dl.name?.original}: {dl.plainText?.original || dl.colorInfo?.original}
-                    </small>
-                  ))}
-                  {isOut ? (
-                    <small className="text-destructive">
-                      {item.status === "PARTIALLY_IN_STOCK" ? "Not enough stock" : "No longer available"}
-                    </small>
-                  ) : atStockLimit ? (
-                    <small className="text-muted-foreground">Only {stock} left</small>
-                  ) : null}
-                  <div className="flex items-center gap-2 mt-1">
-                    <QtyButton disabled={loading || qty <= 1} label="Decrease quantity"
-                      onClick={() => updateQuantity(item.id, qty - 1)}>−</QtyButton>
-                    <span className="min-w-5 text-center" aria-label={`Quantity ${qty}`}>{qty}</span>
-                    <QtyButton disabled={loading || atStockLimit} label="Increase quantity"
-                      onClick={() => updateQuantity(item.id, qty + 1)}>+</QtyButton>
-                    <button onClick={() => removeItem(item.id)} disabled={loading}
-                      className="ml-auto border-none bg-transparent cursor-pointer text-muted-foreground text-[13px] underline disabled:opacity-50">Remove</button>
-                  </div>
-                </div>
-                <div className="flex flex-col items-end shrink-0">
-                  <span className="font-semibold">{paid}</span>
-                </div>
-              </div>
-            );
-          })}
-        </div>
-
-        {lineItems.length > 0 && (
-          <footer className="p-4 border-t border-border flex flex-col gap-3">
-            {discount && (
-              <div className="flex justify-between items-baseline text-sm">
-                <span className="text-muted-foreground">Discount</span>
-                <span>−{discount}</span>
-              </div>
-            )}
-            {subtotal && (
-              <div className="flex justify-between items-baseline">
-                <span className="text-muted-foreground">Subtotal</span>
-                <strong className="text-[17px]">{subtotal}</strong>
-              </div>
-            )}
-            <p className="m-0 text-[12px] text-muted-foreground">Shipping and taxes are calculated at checkout.</p>
-            <button disabled={loading || unavailable.length > 0} onClick={checkout}
-              className="w-full p-3 bg-primary text-primary-foreground border-none rounded-sm text-[15px] font-semibold cursor-pointer disabled:cursor-not-allowed disabled:opacity-60">
-              {loading ? "Working…" : unavailable.length > 0 ? "Remove unavailable items to continue" : "Checkout"}
-            </button>
-          </footer>
-        )}
-      </aside>
-    </div>
-  );
-}
-
-function QtyButton({ children, onClick, disabled, label }) {
-  return (
-    <button onClick={onClick} disabled={disabled} aria-label={label}
-      className="w-7 h-7 cursor-pointer leading-none bg-card text-foreground border border-border rounded-sm disabled:opacity-40 disabled:cursor-not-allowed">{children}</button>
-  );
-}

package/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx

@@ -1,83 +0,0 @@
-// Cart state — mirrors the Wix SERVER cart (never a local copy). Wrap the app in <CartProvider>;
-// every component reads useCart(). Data wiring is correct as-is — do not restyle or re-derive it.
-import { createContext, useContext, useState, useEffect, useCallback } from "react";
-import {
-  getCurrentCart,
-  estimateCurrentCart,
-  addToCart as apiAdd,
-  removeFromCart as apiRemove,
-  updateCartItemQuantity as apiQty,
-  checkout as apiCheckout,
-} from "@/rest/wix-store-cart";
-
-const CartContext = createContext(null);
-
-export function CartProvider({ children }) {
-  const [cart, setCartState] = useState(null);
-  // The calculated summary (after-discount subtotal, cart-level discount) — from the estimate, never
-  // summed in the client. Refreshed with every cart change; null while unknown or when the estimate
-  // fails, in which case surfaces fall back to cart.subtotal.
-  const [summary, setSummary] = useState(null);
-  const [isOpen, setIsOpen] = useState(false);
-  const [loading, setLoading] = useState(false);
-  // The cart helpers throw on refusal with a buyer-readable reason — an empty cart, or line items
-  // whose status isn't IN_STOCK. Hold the message so the drawer can show it; without
-  // this the rejection is unhandled and the shopper sees the spinner stop with nothing said.
-  const [error, setError] = useState(null);
-
-  // Every cart write goes through here so the summary always describes the cart on screen.
-  const setCart = useCallback((next) => {
-    setCartState(next);
-    if (!next?.lineItems?.length) { setSummary(null); return; }
-    estimateCurrentCart().then((s) => setSummary(s)).catch(() => setSummary(null));
-  }, []);
-  const refreshCart = useCallback(async () => setCart(await getCurrentCart()), [setCart]);
-  useEffect(() => {
-    refreshCart();
-    const onVisible = () => document.visibilityState === "visible" && refreshCart();
-    document.addEventListener("visibilitychange", onVisible);
-    return () => document.removeEventListener("visibilitychange", onVisible);
-  }, [refreshCart]);
-
-  const itemCount = (cart?.lineItems ?? []).reduce((n, li) => n + (li.quantityInfo?.confirmedQuantity || 0), 0);
-
-  // Every mutation runs through here so a rejection always lands somewhere visible. `run` keeps the
-  // cart untouched on failure — the server stays the source of truth — and re-reads it for anything
-  // that may have changed underneath (an item selling out between page load and checkout).
-  const run = async (fn, { reread = false } = {}) => {
-    setLoading(true);
-    setError(null);
-    try {
-      return await fn();
-    } catch (e) {
-      setError(e?.message || "Something went wrong. Please try again.");
-      setIsOpen(true); // Surface refusals even when adding from a card or PDP with the drawer closed.
-      if (reread) await refreshCart().catch(() => {});
-      return null;
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  const addToCart = async (id, variantId, qty = 1, extras) =>
-    run(async () => {
-      setCart(await apiAdd(id, variantId, qty, extras));
-      setIsOpen(true);
-    });
-  const removeItem = (lineItemId) => run(async () => setCart(await apiRemove(lineItemId)));
-  const updateQuantity = (lineItemId, qty) => run(async () => setCart(await apiQty(lineItemId, qty)));
-  const checkout = () =>
-    run(async () => { window.location.href = await apiCheckout(); }, { reread: true });
-
-  return (
-    <CartContext.Provider value={{ cart, summary, itemCount, isOpen, setIsOpen, loading, error, clearError: () => setError(null), addToCart, removeItem, updateQuantity, checkout, refreshCart }}>
-      {children}
-    </CartContext.Provider>
-  );
-}
-
-export function useCart() {
-  const ctx = useContext(CartContext);
-  if (!ctx) throw new Error("useCart must be used within <CartProvider>");
-  return ctx;
-}

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

@@ -1,104 +0,0 @@
-// Headless data layer for a product grid tile.
-// Normalises raw Wix product fields into render-agnostic structures so you can build
-// whatever card UI you want (image layout, badge style, price display, quick-add trigger)
-// without touching the badge logic, price rules, or colour-dot extraction.
-//
-// Usage:
-//   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().
-
-import { useMemo } from "react";
-import { productImage, productGallery } from "@/lib/storeImage";
-import { sellingPrice } from "@/rest/wix-store-catalog";
-
-export function useProductCard(product) {
-  return useMemo(() => {
-    const status = product?.inventory?.availabilityStatus;
-    const isSoldOut = status === "OUT_OF_STOCK";
-    // preorderStatus is only meaningful when the product is out of stock
-    const isPreorder = isSoldOut && product?.inventory?.preorderStatus === "ENABLED";
-    const isPartiallyOutOfStock = status === "PARTIALLY_OUT_OF_STOCK";
-
-    // Left-side badges (stacked, top-left of the image): stock / pre-order state.
-    const leftBadges = [];
-    if (isPreorder)                leftBadges.push({ type: "pre-order",     label: "Pre-order"     });
-    else if (isSoldOut)            leftBadges.push({ type: "sold-out",      label: "Sold out"      });
-    if (isPartiallyOutOfStock)     leftBadges.push({ type: "limited-stock", label: "Limited stock" });
-
-    // Merchant ribbons — the primary one plus every additional one. Render ALL of them, in one shared
-    // style (a "Sale" accent is fine, applied by label). Never compute a "-20%" badge from the price
-    // range: a range's minimum says nothing about the variant the buyer picks, and a ribbon is a
-    // label, not a price claim.
-    const ribbons = [product?.ribbon?.name, ...(product?.additionalRibbons ?? []).map((r) => r?.name)]
-      .filter((name, i, all) => name && all.indexOf(name) === i);
-    const promoBadge = ribbons[0] ? { type: "ribbon", label: ribbons[0] } : null;
-
-    // Price. A single-price product shows the price the buyer pays — the lowest-priced variant's
-    // discounted price when an automatic discount applies (priceAfterDiscount), else its regular
-    // price — with the struck "was" price beside it. Variants priced differently show a min–max
-    // range with NO struck price: one lone "was" against a range implies a saving that may not
-    // apply to the variant the buyer picks; the PDP shows the real comparison once a variant is chosen.
-    const min = product?.actualPriceRange?.minValue;
-    const max = product?.actualPriceRange?.maxValue;
-    const isRange = !!(min?.amount && max?.amount && min.amount !== max.amount);
-    const minVariant = product?.variantSummary?.minPriceVariant ?? null;
-    const { current, original } = sellingPrice(minVariant?.price);
-    const priceDisplay = isRange
-      ? `${min?.formattedAmount ?? ""} – ${max?.formattedAmount ?? ""}`
-      : current?.formattedAmount ?? min?.formattedAmount;
-    const compareAtDisplay =
-      !isRange && original?.formattedAmount && Number(original.amount) > Number(current?.amount ?? min?.amount)
-        ? original.formattedAmount
-        : null;
-
-    // Options preview for the tile summary row.
-    // Colour options → real hex dots (more informative than "3 colours").
-    // Non-colour options → "3 sizes · 2 materials" (pluralised from the merchant's own name).
-    const labels = [], colors = [];
-    for (const o of product?.options || []) {
-      const choices = (o.choicesSettings?.choices || []).filter((c) => c.visible !== false);
-      if (!choices.length) continue;
-      const swatches = choices.map((c) => c.colorCode).filter(Boolean);
-      if (swatches.length) { colors.push(...swatches); continue; }
-      const n = o.name.toLowerCase();
-      labels.push(`${choices.length} ${choices.length === 1 || n.endsWith("s") ? n : `${n}s`}`);
-    }
-    const optionLabel = labels.join(" · ");
-    const hasOptions  = (product?.options?.length || 0) > 0;
-
-    // Quick-add is only safe for single-variant products (no option choices to resolve).
-    // Sold-out with pre-order still shows a CTA, but it links to the PDP, not quick-add.
-    const isQuickAddable = !hasOptions && !isSoldOut;
-    // 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);
-    const hoverImage = productGallery(product)[1]?.url ?? null;
-
-    return {
-      isSoldOut,
-      isPreorder,
-      isPartiallyOutOfStock,
-      leftBadges,          // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
-      ribbons,             // every merchant ribbon label, primary first — render all of them
-      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,
-      directAddVariantId,  // pass as variantId to addToCart on quick-add
-      image,               // primary image URL | null
-      hoverImage,          // second image URL for hover effect | null
-    };
-  }, [product]);
-}

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

@@ -1,163 +0,0 @@
-// useProductDetail — all PDP logic, no markup: load product by slug, resolve the buyer's selections
-// to a Wix variant, gate add-to-cart on availability + mandatory modifiers, and build the addToCart
-// payload. The data paths here (variant resolution, price precedence, 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, sellingPrice } from "@/rest/wix-store-catalog";
-import { choiceImage, variantImage } from "@/lib/storeImage";
-import { useCart } from "@/context/CartContext";
-
-// A variant is identified by the SET of its choice ids — sorted, so option order can't matter.
-const choiceKey = (choiceIds) => [...choiceIds].sort().join("_");
-
-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);
-  // Selections start EMPTY. Pre-picking the first choice lets a buyer who never noticed the default
-  // buy the wrong colour; the PDP shows a neutral "choose a size" until every option is picked.
-  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);
-    setSelectedOptions({});
-    setQuantity(1);
-    getProductBySlug(slug)
-      .then((p) => {
-        if (cancelled) return;
-        if (!p) return setNotFound(true);
-        setProduct(p);
-      })
-      .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 || [];
-
-  // Visible variants keyed by their sorted choice ids. Two variants with the same choices is a
-  // catalog defect — report it instead of silently letting one overwrite the other.
-  const { variantByKey, duplicateKey } = useMemo(() => {
-    const map = new Map();
-    let dup = null;
-    for (const v of product?.variantsInfo?.variants || []) {
-      if (v.visible === false) continue;
-      const k = choiceKey((v.choices || []).map((c) => c.optionChoiceIds?.choiceId));
-      if (map.has(k) && !dup) dup = k;
-      map.set(k, v);
-    }
-    return { variantByKey: map, duplicateKey: dup };
-  }, [product]);
-
-  const selectionComplete = options.length > 0 && options.every((o) => selectedOptions[o.id]);
-  const variant = useMemo(() => {
-    if (options.length === 0) return variantByKey.values().next().value || null;   // the single variant
-    if (!selectionComplete || duplicateKey) return null;
-    return variantByKey.get(choiceKey(options.map((o) => selectedOptions[o.id]))) || null;
-  }, [options, variantByKey, duplicateKey, selectedOptions, selectionComplete]);
-
-  // In stock OR pre-orderable counts as buyable; a preorder add carries preOrderRequested.
-  const inStock = variant ? variant.inventoryStatus?.inStock !== false : true;
-  const isPreorder = !!variant && !inStock && variant.inventoryStatus?.preorderEnabled === true;
-  const available = inStock || isPreorder;
-
-  const missingModifier = modifiers.find((m) => m.mandatory && !(
-    m.modifierRenderType === "FREE_TEXT" ? modifierValues[m.freeTextSettings?.key] : modifierValues[m.key]));
-
-  const canAdd = useMemo(() => {
-    if (!product) return false;
-    if (options.length > 0 && !variant) return false;
-    if (variant && !available) return false;
-    return !missingModifier;
-  }, [product, options, variant, available, missingModifier]);
-
-  // Why the buy button is disabled — neutral guidance to render next to the action ("Choose a
-  // size"), not an error; null when the buyer can add. Promote to error styling only after they try.
-  const blockedReason = useMemo(() => {
-    if (!product) return null;
-    if (duplicateKey) return "This product's variants can't be resolved right now.";
-    if (options.length > 0 && !selectionComplete) {
-      const missing = options.filter((o) => !selectedOptions[o.id]).map((o) => o.name);
-      return `Choose ${missing.join(" and ")}`;
-    }
-    if (options.length > 0 && !variant) return "This combination isn't available";
-    if (variant && !available) return "Out of stock";
-    if (missingModifier) return `Add ${missingModifier.name}`;
-    return null;
-  }, [product, duplicateKey, options, selectionComplete, selectedOptions, variant, available, missingModifier]);
-
-  // Everything the buyer sees follows the resolved `variant` (also returned below). The price obeys
-  // the exact precedence in sellingPrice(): an automatic discount beats the regular price and strikes
-  // it; else the regular price with the merchant's compare-at as the "was". Before every option is
-  // picked, the product's min–max range (one value when equal) — never an empty price.
-  const min = product?.actualPriceRange?.minValue, max = product?.actualPriceRange?.maxValue;
-  const rangeDisplay = min?.amount && max?.amount && min.amount !== max.amount
-    ? `${min.formattedAmount} – ${max.formattedAmount}` : (min?.formattedAmount || "");
-  const resolved = variant ? sellingPrice(variant.price) : null;
-  const price = resolved?.current?.formattedAmount || rangeDisplay;
-  const compareAtPrice = resolved && resolved.original?.formattedAmount &&
-    Number(resolved.original.amount) > Number(resolved.current?.amount) ? resolved.original.formattedAmount : "";
-  const discountNames = product?.discountInfo?.discountRuleNames || [];   // automatic discounts, product level
-
-  // The gallery follows the selection. Prefer the selected choice's own image (the per-swatch photo,
-  // choice.media.items[].mediaId) — Wix's per-variant media is often NOT differentiated (it defaults to
-  // the product's main image), so preferring the variant would override the correct choice image for
-  // every colour. Fall back to the resolved variant's image only when no chosen option carries one.
-  // See lib/storeImage: choiceImage() / variantImage().
-  const focusMediaUrl = useMemo(() => {
-    for (const o of options) {
-      const choice = (o.choicesSettings?.choices || []).find((c) => c.choiceId === selectedOptions[o.id]);
-      const url = choiceImage(choice);
-      if (url) return url;
-    }
-    return variantImage(variant);
-  }, [variant, options, selectedOptions]);
-
-  // Changing an option resets the quantity — the ceiling belongs to the newly resolved variant.
-  const selectOption = (optionId, choiceId) => {
-    setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
-    setQuantity(1);
-  };
-  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). Preserve its undefined-on-success / null-on-failure result for chained actions.
-      // 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.
-      return 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,
-        preorder: isPreorder,
-      });
-    } finally {
-      setAdding(false);
-    }
-  }
-
-  return {
-    product, notFound, error, retry: () => setReloadKey((k) => k + 1),
-    options, modifiers,
-    selectedOptions, selectOption, modifierValues, setModifier,
-    quantity, setQuantity, variant, inStock, isPreorder, canAdd, blockedReason, adding,
-    price, compareAtPrice, discountNames, submit, focusMediaUrl,
-  };
-}

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

@@ -1,83 +0,0 @@
-// Catalog queries run on Wix before pagination. A changed selection starts a fresh cursor chain.
-import { useCallback, useEffect, useRef, useState } from "react";
-import { searchProducts, queryCategories, CATALOG_SORTS } from "@/rest/wix-store-catalog";
-
-export const SORTS = CATALOG_SORTS;
-const SYSTEM_CATEGORY_SLUG = "all-products";
-
-export function useShop({ pageSize = 24 } = {}) {
-  const [categories, setCategories] = useState([]);
-  const [activeCategory, setActiveCategory] = useState(null);
-  const [sort, setSort] = useState("featured");
-  const [filters, setFilters] = useState({});
-  const [attempt, setAttempt] = useState(0);
-  const [page, setPage] = useState({ key: null, products: null, cursor: null, error: null, loadingMore: false });
-  const generation = useRef(0);
-  const pendingMore = useRef(null);
-  const key = JSON.stringify([pageSize, activeCategory?.id ?? null, sort, filters.minPrice ?? null,
-    filters.maxPrice ?? null, !!filters.inStockOnly, filters.search ?? "", attempt]);
-  const currentKey = useRef(key);
-  currentKey.current = key;
-
-  useEffect(() => {
-    let alive = true;
-    queryCategories({ limit: 100 })
-      .then(({ categories: list }) => {
-        if (alive) setCategories((list || []).filter(c => c.visible !== false && c.slug !== SYSTEM_CATEGORY_SLUG));
-      })
-      .catch(() => { if (alive) setCategories([]); });
-    return () => { alive = false; };
-  }, []);
-
-  useEffect(() => {
-    const id = ++generation.current;
-    let alive = true;
-    pendingMore.current = null;
-    setPage({ key, products: null, cursor: null, error: null, loadingMore: false });
-    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search] = JSON.parse(key);
-    searchProducts({ limit, categoryId, sort: selectedSort, minPrice, maxPrice, inStockOnly, search })
-      .then(res => {
-        if (alive && generation.current === id && currentKey.current === key) {
-          setPage({ key, products: res.products, cursor: res.nextCursor, error: null, loadingMore: false });
-        }
-      })
-      .catch(e => {
-        if (alive && generation.current === id && currentKey.current === key) {
-          setPage({ key, products: [], cursor: null, error: e?.message || "Couldn't load products.", loadingMore: false });
-        }
-      });
-    return () => { alive = false; generation.current++; };
-  }, [key]);
-
-  const loadMore = useCallback(async () => {
-    if (page.key !== key || !page.cursor || pendingMore.current) return;
-    const request = { generation: generation.current, key };
-    pendingMore.current = request; // blocks repeated clicks before React rerenders
-    const isCurrent = () => generation.current === request.generation && currentKey.current === key;
-    setPage(p => ({ ...p, loadingMore: true, error: null }));
-    try {
-      const res = await searchProducts({ limit: pageSize, cursor: page.cursor });
-      if (isCurrent()) setPage(p => {
-        const seen = new Set((p.products || []).map(product => product.id));
-        return { ...p, products: [...(p.products || []), ...res.products.filter(product => {
-          if (seen.has(product.id)) return false;
-          seen.add(product.id); return true;
-        })], cursor: res.nextCursor };
-      });
-    } catch (e) {
-      if (isCurrent()) setPage(p => ({ ...p, error: e?.message || "Couldn't load more products." }));
-    } finally {
-      if (pendingMore.current === request) pendingMore.current = null;
-      if (isCurrent()) setPage(p => ({ ...p, loadingMore: false }));
-    }
-  }, [key, page.key, page.cursor, pageSize]);
-
-  const retry = useCallback(() => setAttempt(n => n + 1), []);
-  const current = page.key === key;
-  return {
-    categories, activeCategory, setActiveCategory, sort, setSort, filters, setFilters,
-    products: current ? page.products : null, loading: !current || page.products === null,
-    error: current ? page.error : null, retry,
-    hasMore: current && !!page.cursor, loadMore, loadingMore: current && page.loadingMore,
-  };
-}