@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-vibe-headless/references/shared/app/rest/wix-client.js

@@ -1,185 +0,0 @@
-/**
- * REST version of the Wix headless integration — the direct analog of
- * `storefrontApiRequest` in src/lib/shopify.ts. Plain fetch, JSON in / JSON out.
- * No SDK, no query builder, no Velo.
- *
- * WIX_CLIENT_ID is the one thing to set — and you set it in `wix-config.js`, not here.
- * The client exchanges it for a visitor access token via the OAuth2 token endpoint,
- * then sends that token on every API call.
- */
-
-// The public headless OAuth client id — set it in wix-config.js (do not hardcode it here).
-export { WIX_CLIENT_ID } from "./wix-config.js";
-import { WIX_CLIENT_ID } from "./wix-config.js";
-
-export const WIX_API_BASE = "https://www.wixapis.com";
-export const WIX_API_SUPPORTS_STRICT_PAYMENT_ERRORS = true;
-const OAUTH_TOKEN_URL = `${WIX_API_BASE}/oauth2/token`;
-
-// Scope the storage key by client id so two headless sites served from the same
-// origin (e.g. localhost:4321 across projects) don't share one visitor token —
-// which would load site A's token for site B and mix up carts/identity.
-const TOKEN_STORAGE_KEY = `wix-visitor-token-${WIX_CLIENT_ID}`;
-let tokenCache = null;
-
-function loadToken() {
-  if (tokenCache) return tokenCache;
-  if (typeof window === "undefined") return null;
-  try {
-    const raw = window.localStorage.getItem(TOKEN_STORAGE_KEY);
-    if (raw) tokenCache = JSON.parse(raw);
-  } catch {
-    /* ignore disabled/full storage */
-  }
-  return tokenCache;
-}
-
-function saveToken(t) {
-  tokenCache = t;
-  if (typeof window === "undefined") return;
-  try {
-    window.localStorage.setItem(TOKEN_STORAGE_KEY, JSON.stringify(t));
-  } catch {
-    /* ignore */
-  }
-}
-
-async function mintToken(body) {
-  const res = await fetch(OAUTH_TOKEN_URL, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-  });
-  if (!res.ok) throw new Error(`Wix OAuth failed: ${res.status}`);
-  const data = await res.json();
-  return {
-    accessToken: data.access_token,
-    refreshToken: data.refresh_token,
-    expiresAt: Date.now() + data.expires_in * 1000,
-  };
-}
-
-/**
- * Log a member in on THIS client by swapping the persisted token set for the
- * member's tokens (see references/members/). Member tokens are the SAME shape as
- * visitor tokens and refresh via the same `refresh_token` grant — logging in just
- * replaces the set the client already carries, so EVERY subsequent `wixApiRequest`
- * (cart, orders, bookings, "my …" reads) now runs as the member. Called by the
- * members helper after a successful credential / social / SSO login.
- *
- * @param {{ accessToken: string, refreshToken: string, expiresIn: number }} tokens
- */
-export function setSessionTokens({ accessToken, refreshToken, expiresIn }) {
-  saveToken({
-    accessToken,
-    refreshToken,
-    expiresAt: Date.now() + expiresIn * 1000,
-    role: "member",
-  });
-}
-
-/**
- * Drop the persisted session so the next call mints a FRESH anonymous visitor.
- * Call on logout — otherwise the dead member token lingers and reads fail.
- */
-export function clearSession() {
-  tokenCache = null;
-  if (typeof window === "undefined") return;
-  try {
-    window.localStorage.removeItem(TOKEN_STORAGE_KEY);
-  } catch {
-    /* ignore */
-  }
-}
-
-/**
- * True once a member is logged in on this client (vs. an anonymous visitor).
- * Gate account UI on this, or on the members helper's `isLoggedIn()`.
- * @returns {boolean}
- */
-export function isMember() {
-  return loadToken()?.role === "member";
-}
-
-/**
- * Get a visitor access token from the client id.
- *
- * The visitor token IS the identity of the Wix "current cart", so we persist the
- * refresh token to localStorage and REFRESH it on expiry — re-minting a fresh
- * `anonymous` token would create a NEW visitor and silently empty the cart on
- * every reload / after the 4h token lifetime. Anonymous mint happens only once
- * (or when no refresh token is stored).
- */
-async function getAccessToken() {
-  const cached = loadToken();
-  if (cached && cached.expiresAt > Date.now() + 60_000) return cached.accessToken;
-
-  if (cached?.refreshToken) {
-    try {
-      const refreshed = await mintToken({ clientId: WIX_CLIENT_ID, grantType: "refresh_token", refreshToken: cached.refreshToken });
-      // Refreshing preserves identity: a member refresh token yields member tokens.
-      refreshed.role = cached.role || "visitor";
-      saveToken(refreshed);
-      return refreshed.accessToken;
-    } catch {
-      /* refresh failed — fall through to a fresh anonymous visitor */
-    }
-  }
-  const fresh = await mintToken({ clientId: WIX_CLIENT_ID, grantType: "anonymous" });
-  fresh.role = "visitor";
-  saveToken(fresh);
-  return fresh.accessToken;
-}
-
-/**
- * Core transport — mirrors storefrontApiRequest. Adds the Authorization header,
- * resolves the path against the Wix API base, parses JSON, surfaces errors.
- *
- * @param {string} path
- * @param {{ method?: "GET"|"POST"|"PUT"|"DELETE", body?: unknown, query?: Record<string, string | undefined>, throwOnPaymentRequired?: boolean }} [options]
- */
-export async function wixApiRequest(path, options = {}) {
-  const { method = "POST", body, query, throwOnPaymentRequired = false } = options;
-  const token = await getAccessToken();
-
-  const url = new URL(path.startsWith("http") ? path : `${WIX_API_BASE}${path}`);
-  if (query) {
-    for (const [k, v] of Object.entries(query)) {
-      if (v === undefined) continue;
-      if (Array.isArray(v)) {
-        for (const item of v) url.searchParams.append(k, item);
-      } else {
-        url.searchParams.set(k, v);
-      }
-    }
-  }
-
-  const res = await fetch(url.toString(), {
-    method,
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: token, // Wix expects the raw access token (no "Bearer " prefix)
-    },
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
-
-  if (res.status === 402 && !throwOnPaymentRequired) {
-    // This API requires an active plan / premium feature on the site.
-    console.warn("Wix: Payment required (402) — this API needs an active plan/premium feature.");
-    return;
-  }
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    let parsed;
-    try { parsed = JSON.parse(text); } catch { parsed = text; }
-    // Attach status + parsed body so callers (e.g. the members helper) can map a
-    // meaningful auth outcome (404 = bad credentials, 409 = email exists) to a
-    // friendly message instead of parsing the message string.
-    const err = new Error(`Wix API error ${res.status}: ${text}`);
-    err.status = res.status;
-    err.body = parsed;
-    throw err;
-  }
-  if (res.status === 204) return undefined;
-  return await res.json();
-}

package/skills/wix-vibe-headless/references/shared/app/rest/wix-config.js

@@ -1,8 +0,0 @@
-// Wix credentials. The install step writes this file: deploy.cjs --client-id … --metasite-id …
-// If you're seeing the placeholders below, re-run that command with the ids from the prompt rather
-// than typing them in here.
-// Safe to commit: WIX_CLIENT_ID is a public, buyer-facing id (it only mints anonymous visitor
-// tokens); WIX_METASITE_ID just identifies the site.
-// wix-client.js and wix-manage-banner.js read their ids from here.
-export const WIX_CLIENT_ID = "<YOUR-CLIENT-ID>";
-export const WIX_METASITE_ID = "<YOUR-METASITE-ID>";

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

@@ -1,471 +0,0 @@
-# Wix Storefront — ready-made client
-
-The storefront ships the commerce hooks, server cart, REST transport, image helpers, and cart UI.
-You build the presentation: Shop page, product grid and cards, variant controls, product detail
-(PDP) page, Home, header, and footer. Use the interfaces below and proceed directly to implementation.
-
-The shipped client handles visitor authentication using its deployed configuration. No ID lookup
-or configuration changes are needed to build the UI. Never mock products or hand-build a
-`/checkout` URL; the shipped cart uses the eCom redirect session.
-
-## Prerequisites
-- The site's **Wix Stores** catalog is the read/cart target. It may be empty while the client is being built — render the empty state cleanly. Flows that seed do so after the client is built; verify the storefront once the catalog is populated, not against the empty state.
-
-## Already installed in `src/`
-Successful deployment verified these files are in place; use this map without needing to read their source (`@/` → `src/`).
-
-| file | what it is |
-|---|---|
-| `context/CartContext.jsx` | `CartProvider` and `useCart()`: server cart, add/update/remove, checkout |
-| `hooks/useProductDetail.js` | PDP product, variant resolution, selection, load/add state |
-| `hooks/useShop.js` | Catalog listing, categories, cursor paging, sort, failure state; use in your `Shop` |
-| `hooks/useProductCard.js` | Card badges, prices, options summary, quick-add flag, images |
-| `hooks/useVariantOptions.js` | Render-agnostic option and modifier groups for PDP controls |
-| `lib/storeImage.js` | Wix image URL and gallery helpers |
-| `components/CartButton.jsx` | Cart icon button with a live-count badge |
-| `components/CartDrawer.jsx` | Cart drawer; mount once, opens through `useCart` |
-| `components/WixManageBanner.jsx` | Preview-only manage banner; include only when the entry guide enables it |
-| `rest/wix-config.js` | Deployed configuration; consumed internally by the shipped client |
-| `rest/wix-client.js` | REST transport and visitor authentication |
-| `rest/wix-store-catalog.js` | Product and category queries |
-| `rest/wix-store-cart.js` | Cart mutations and hosted checkout |
-
-Build using the interfaces below without reading the shipped source. If you encounter an error
-after building the client, read or change whatever you need to diagnose and fix it.
-If deployment failed or files are missing, re-run the install/deploy step.
-
-## Theme
-Use the existing Base44 theme in `src/index.css` so your pages and the shipped components
-share the same colors and typography.
-
-## Presentation interfaces
-Build `pages/Shop.jsx`, `components/ProductGrid.jsx`, `components/ProductCard.jsx`, and
-`pages/ProductDetail.jsx` from these contracts. All paths are under `src/`. Home, header, and
-footer are yours to design; their integration is in **Routes and provider** below.
-
-### Shop page and product grid
-Create both files below. The hook owns catalog data; your page owns its presentation.
-
-```jsx
-// src/pages/Shop.jsx
-import { useShop, SORTS } from "@/hooks/useShop";
-import ProductGrid from "@/components/ProductGrid";
-
-export default function Shop() {
-  const s = useShop();
-  // Category controls: s.categories ({ id, name }), s.activeCategory;
-  // select with s.setActiveCategory(category), or null for all products.
-  // Sort controls: Object.entries(SORTS) -> [key, { label }];
-  // selected value s.sort; change with s.setSort(key).
-  // Optional filters: s.setFilters({ minPrice: 20, maxPrice: 100,
-  //   inStockOnly: true, search: "linen" }); s.setFilters({}) clears them.
-  // Apply a submitted/debounced search value; the hook queries on every change.
-  // Render s.error with s.retry separately from loading/empty results.
-  // On a later-page error, keep already loaded products visible.
-  // Pagination: when s.hasMore, call s.loadMore(); disable while s.loadingMore.
-  return (
-    <ProductGrid
-      products={s.products}
-      loading={s.loading}
-      emptyMessage={s.error ? "" : "No products yet."}
-      emptyHint={s.error ? "" : "Try another category or check back later."}
-    />
-  ); // Add the controls and states above; layout and styling are yours.
-}
-```
-
-```jsx
-// src/components/ProductGrid.jsx
-import ProductCard from "@/components/ProductCard";
-
-export default function ProductGrid({ products, loading, emptyMessage, emptyHint }) {
-  // products: array | null; emptyMessage and emptyHint are display text, not state.
-  // Layout and styling are yours; this component does not fetch products.
-  if (loading && !products?.length) return null; // Replace null with your loading UI.
-  if (!products?.length) {
-    // The page handles errors separately and suppresses emptyMessage on error.
-    return emptyMessage ? <div><p>{emptyMessage}</p><p>{emptyHint}</p></div> : null;
-  }
-  return products.map(product => <ProductCard key={product.id} product={product} />);
-}
-```
-
-### Product card
-Pass a catalog product to `ProductCard`: use `product.id` for identity/quick-add, `product.name`
-for the title, and `product.slug` for the PDP link. Pass the full object to `useProductCard`.
-
-```jsx
-import { useProductCard } from "@/hooks/useProductCard";
-import { useCart } from "@/context/CartContext";
-
-export default function ProductCard({ product }) {
-  const { addToCart, loading, error } = useCart();
-  const {
-    isSoldOut, isPreorder, isPartiallyOutOfStock, // booleans
-    leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
-    ribbons,          // every merchant ribbon label, primary first — render ALL of them, one shared style
-    promoBadge,       // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
-    priceDisplay,     // the price the buyer pays (discounted when an automatic discount applies), or a min–max range
-    compareAtDisplay, // struck "was" price | null — never beside a range (the PDP shows the real comparison)
-    teaser,           // plain-text description for the tile — plainDescription is HTML; never render it raw on a card
-    colors,           // hex colour strings
-    optionLabel,      // e.g. "3 sizes · 2 materials", or ""
-    isQuickAddable,   // no product options and not sold out; does NOT check modifiers
-    directAddVariantId, // the variant a quick-add sends; null when not quick-addable
-    image, hoverImage,// normalised primary / second gallery URL | null
-  } = useProductCard(product);
-  // Render your card.
-}
-```
-A ribbon is a label, never proof of a price: don't render a "Sale" badge from `compareAtDisplay`,
-and don't compute a percent-off — the hook deliberately doesn't. For quick-add, call
-`addToCart(product.id, directAddVariantId)` only when `isQuickAddable` and no mandatory
-modifier needs input (`product.modifiers` entries have a `mandatory` boolean). Otherwise link to `/product/${product.slug}` for selection, including
-pre-orders. Listing results have no full variants; the PDP hook loads and resolves them.
-Use cart-context `loading` to disable repeated adds. Failures open the shipped drawer with
-`error`; you can also display it beside the card/PDP controls (see **Cart**).
-
-### Catalog hook reference
-`useShop` and `SORTS` are named exports from `@/hooks/useShop`; the Shop skeleton above uses them.
-
-```js
-const {
-  categories, activeCategory, setActiveCategory,
-  products, loading, error, retry,
-  hasMore, loadMore, loadingMore, sort, setSort, filters, setFilters,
-} = useShop({ pageSize: 24 }); // optional argument; default pageSize 24
-// categories: category[]; activeCategory: category | null (null = all products)
-// setActiveCategory(categoryOrNull): starts a fresh product query, keeping sort/filters
-// products: product[] | null; loading: boolean (fresh query, including sort/filter changes)
-// error: string | null; retry(): reloads the active category's first page
-// hasMore, loadingMore: booleans; loadMore(): appends another page when available
-// sort: 'featured' | 'priceAsc' | 'priceHigh' | 'name' | 'newest'; setSort(key)
-// filters: { minPrice?, maxPrice?, inStockOnly?, search? }
-// setFilters(object): replaces filters; setFilters(previous => ({ ...previous, ...patch })) merges
-// SORTS: { [key]: { label } } for those keys
-```
-Wix filters and sorts the full matching catalog before paging; the hook never sorts a loaded subset.
-Changing category, sort, or filters resets products and the cursor; stale responses are ignored.
-`featured` retains its existing key but means **Default order**, not merchant-curated placement.
-Prices use the product's minimum actual variant price in site currency, in either direction and
-for both bounds; this is not a selected-variant or checkout-discount price. Bounds are inclusive,
-non-negative numbers (numeric strings accepted); null/empty omits a bound. Min must not exceed max.
-`inStockOnly` matches `IN_STOCK` products, excluding partially stocked and preorder-only products.
-`search` searches product names (up to 100 characters). These filters can be combined.
-
-Initial product failure sets `error` and an empty array;
-a later page failure preserves products and cursor; call `loadMore()` again to retry that page.
-`retry()` starts over at page one with current selections. Render the error separately from
-an empty catalog. Category loading fetches only the first 100 categories, excludes `visible: false`
-and `slug: "all-products"`, and falls back to `[]` on failure without setting `error`.
-
-For a standalone product selection or category menu, import these named functions from
-`@/rest/wix-store-catalog`. They return promises and reject on invalid query options or request failure.
-
-| Function | Result |
-|---|---|
-| `searchProducts({ limit = 100, cursor, categoryId, sort, minPrice, maxPrice, inStockOnly, search } = {})` | `{ products: product[], nextCursor: string or null }` — same sort/filter semantics as the hook |
-| `queryProducts(options = {})` | `{ products: product[], nextCursor: string or null }` — visible catalog products |
-| `queryCategories({ limit = 100, cursor } = {})` | `{ categories: category[], nextCursor: string or null }` — one category page |
-| `queryProductsByCategory(categoryId, options = {})` | `{ products: product[], nextCursor: string or null }` — visible products in the category identified by `id` |
-
-`queryProducts` and `queryProductsByCategory` accept the same options as `searchProducts`.
-A cursor continues the original query; changed filters/sort require starting without one.
-Products are the full listing objects consumed by `useProductCard`. Category menu fields are
-`id`, `name`, `slug`, and `visible`. Filter out `visible === false` and the system category
-`slug === "all-products"`; an empty category list is valid.
-
-```js
-const { categories, nextCursor: categoryCursor } = await queryCategories({ limit: 100 });
-const menu = categories.filter((c) => c.visible !== false && c.slug !== "all-products");
-// Once a category has been selected:
-const { products, nextCursor } = await queryProductsByCategory(selectedCategory.id, { limit: 24 });
-```
-Destructure the arrays; these calls never return bare arrays. Pass a result's `nextCursor` back
-as `cursor` to the same query for the next page, stopping at null. Keep category and product
-cursors separate; changing category, sort, or filters starts without a cursor. Handle failure separately from
-loading so a failed request does not leave a spinner.
-
-### Product detail
-```jsx
-import { useParams } from "react-router-dom";
-import { useProductDetail } from "@/hooks/useProductDetail";
-import { useVariantOptions } from "@/hooks/useVariantOptions";
-import { productGallery } from "@/lib/storeImage";
-
-export default function ProductDetail() {
-  const { slug } = useParams();
-  const d = useProductDetail(slug);
-  const { optionGroups, modifierGroups } = useVariantOptions(
-    d.options, d.modifiers, d.selectedOptions, d.modifierValues
-  );
-  // Keep all hooks above every conditional return, including while the product loads.
-  // d contains:
-  // product: Wix product | null; .name, .slug, .plainDescription (HTML)
-  // notFound: boolean; error: string | null (load error); retry: () => void
-  // price: formatted — the product's min–max range until every option is picked, then the selected
-  //   variant's price (an automatic discount beats the regular price); compareAtPrice: the struck
-  //   "was" price, "" when none. discountNames: automatic-discount names, product level.
-  // options, modifiers: arrays consumed by useVariantOptions above
-  // selectedOptions: { [optionId]: choiceId } — starts EMPTY (no pre-picked choice); selectOption(optionId, choiceId)
-  // modifierValues: { [key]: value }; setModifier(key, value)
-  // variant: resolved variant | null; null if required choices are missing or no match exists
-  // focusMediaUrl: selected choice image, then variant image, or null
-  // quantity, setQuantity(n): number (may be "" mid-edit); resets to 1 when an option changes
-  // inStock, isPreorder, canAdd, adding: booleans — a pre-order variant IS addable
-  // blockedReason: string | null — why the buy button is disabled ("Choose Size", "Out of stock");
-  //   render it next to the action as neutral guidance, not an error, until the buyer tries to buy
-  // submit: async () => adds product + resolved variant + quantity + modifiers (+ preorder)
-  // resolves undefined on success, null on failure (not a cart object or a boolean)
-  // Replace these placeholders with your error, not-found, and loading UI.
-  if (d.error) return null; // show d.error and offer d.retry()
-  if (d.notFound) return null;
-  if (!d.product) return null;
-
-  const images = productGallery(d.product); // [{ url, altText }], main first, de-duplicated
-  // Render your PDP using d, images, optionGroups, and modifierGroups.
-  return null;
-}
-```
-- Render `product.plainDescription` as HTML; strike `compareAtPrice` only when present and different from `price`.
-- Make the gallery follow `focusMediaUrl` when the selected option changes.
-- Render the option/modifier controls below; mark choices whose `inStock` is false; show `d.blockedReason` beside the button while it's disabled.
-- Label the action by state: `isPreorder` → "Pre-order"; otherwise "Add to cart". Keep quantity at least 1. Disable adding when `!canAdd || adding`; call `submit()` only with a loaded product and `canAdd`. `submit()` coerces quantity to at least 1 but does not itself enforce `canAdd`.
-- `canAdd` checks variant resolution, availability (in stock or pre-orderable), and mandatory modifier values. `inStock` defaults to true without a resolved variant; use `canAdd` for the full gate.
-- Render the PDP gallery from `images` — every image reachable (thumbnails, arrows, or a swipeable rail), not just the first; a single-image product gets no empty strip.
-- `submit()` resets `adding` after completion and preserves the cart result: `undefined` on success, `null` on failure. Add failures live in `useCart().error`, not the PDP load `error`; the shipped drawer opens to display them.
-
-### Variant and modifier controls
-The product-detail example above provides both groups:
-```js
-// optionGroups: [{ id, name, isColor, choices: [
-//   { choiceId, name, colorCode: string | null, isColorSwatch, inStock, selected }
-// ] }]
-// modifierGroups: [{ key, name, mandatory, type: 'choices'|'text',
-//   choices?: [{ key, name, selected }], value?: string }]
-// Select option: d.selectOption(group.id, choice.choiceId)
-// Select modifier: d.setModifier(m.key, choice.key)
-// Text modifier: d.setModifier(m.key, text)
-```
-Retired option choices are filtered out. Respect each choice's `inStock` and modifier's
-`mandatory` flag. A choice with `isColorSwatch` renders as a **color swatch** filled with its
-`colorCode` and labelled by its name — not as a text pill; the hook supplies the values and selection
-state without prescribing the rest of the layout.
-
-### Images
-`useProductCard` returns normalized `image`/`hoverImage`, and `useProductDetail` returns normalized
-`focusMediaUrl`; use them directly. For a gallery or images outside those hooks, import from
-`@/lib/storeImage`:
-
-| Helper | Contract |
-|---|---|
-| `productGallery(product)` | `[{ url, altText }]`, main image first, de-duplicated; skips entries without an image URL; empty array when no images |
-| `productImage(product)` | Normalized primary image URL or null, for a standalone catalog image |
-| `storeImage(value)` | Accepts a URL string, `{ image: { url } }`, or `{ url }`; prefixes `//` with `https:`, returns other URLs unchanged or null when absent |
-
-Gallery URLs are normalized too. Handle missing images; don't reconstruct media URLs or resolve
-choice/variant media yourself.
-
-### Cart
-Use the shipped `CartDrawer` and `CartButton` with `CartProvider`, as wired below. The drawer
-already renders cart lines, quantities, subtotal, and checkout; you do not need to build a cart UI.
-Your card/PDP adds products through the named `useCart` export from `@/context/CartContext`
-within `CartProvider` (the PDP hook calls it for you).
-
-```js
-const { addToCart, isOpen, setIsOpen, loading, error, clearError } = useCart();
-// addToCart(productId, variantId?, qty = 1, { modifierChoices?, customTextFields?, subscriptionOptionId?, preorder? }?)
-// isOpen: boolean; setIsOpen(true): open the drawer; setIsOpen(false): close it
-// loading: mutation-in-progress boolean; disable repeated adds while true
-// error: string | null; clearError(): clears it
-```
-`addToCart` uses `product.id` and the resolved `variant.id` when needed. Extras: string maps
-`modifierChoices: { [modifier.key]: choiceKey }` and
-`customTextFields: { [modifier.freeTextSettings.key]: userInput }` (include mandatory values);
-`preorder: true` for a pre-order variant (the PDP hook sets it); `subscriptionOptionId` for a chosen
-recurring plan (omit for one-time). The shipped PDP hook doesn't render subscriptions — add that
-only when the catalog has `subscriptionPricesInfo`, requiring an explicit plan choice.
-
-The context's add/remove/update/checkout methods return promises resolving to `undefined` on
-success or `null` on failure, storing the failure in `error`. They clear the previous error and
-set `loading` during the operation. Successful add updates the server-cart snapshot and opens the
-drawer; mutation failures also open it to display the error. Your card/PDP can additionally
-surface `error` inline. These context methods do not return the updated cart or checkout URL.
-The lower-level REST helpers can reject; don't apply their rejection contract to `useCart()`.
-
-#### Custom cart UI — optional
-Only use these additional contracts if you choose to render your own cart surface. They come
-from the same `useCart()` context; mutation results and error handling are described above.
-
-```js
-const { cart, summary, itemCount, removeItem, updateQuantity, checkout, refreshCart } = useCart();
-// cart: server cart | null; itemCount: sum of confirmed line quantities
-// summary: the estimate's { priceSummary: { subtotal, discount, total } } | null — refreshed with the cart;
-//   subtotal is after discounts, discount is the CART-level discount only; both ConvertedMoney
-// removeItem(lineItemId); updateQuantity(lineItemId, qty)
-// checkout(); refreshCart()
-```
-For custom cart presentation, `cart?.lineItems ?? []` is the list. Each line has `id`,
-`name.original`, and optional `attributes.image.url`. Option/modifier labels are in
-`attributes.descriptionLines`: `[{ name: { original }, plainText?: { original },
-colorInfo?: { original, code } }]`; use `plainText.original` or `colorInfo.original` for the value.
-Update/remove use the line's `id`, not a catalog product id. Show each line's `attributes.descriptionLines`
-(the chosen options and text) — a shopper verifies the configuration in the cart, not the checkout.
-
-Normalize custom cart images with `storeImage(line.attributes?.image?.url)` (see **Images**).
-
-`checkout()` navigates to the hosted checkout URL; it refuses empty carts and lines with a status
-other than `IN_STOCK`, and refreshes the cart after failure. `refreshCart()` replaces the snapshot
-and resolves to `undefined`; its underlying read returns null for no cart or a failed request. It
-does not set mutation `loading` or `error`.
-
-Cart money is `{ amount, convertedAmount }`, with no formatted string. `amount` is in site
-currency; `convertedAmount` is in display currency. Format
-`money.convertedAmount ?? money.amount` with `Intl.NumberFormat` and
-`cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode` (the shipped drawer falls
-back to `USD`). Use `summary.priceSummary.subtotal` (after discounts) with `cart.subtotal` as the
-fallback while `summary` is null, a Discount row only when `priceSummary.discount` is above zero, and
-line `pricing.totalPrice`; never sum lines yourself. Shipping and tax resolve at checkout — say
-"calculated at checkout", never a hardcoded charge, threshold, or a made-up zero. The estimate's
-`priceSummary.delivery`, `tax`, and `additionalFees` read `"0"` when nothing was calculated (verified
-live), so a zero there is not "Free shipping" or "No tax" — don't render those rows from the estimate.
-
-Line `quantityInfo.confirmedQuantity` is the current quantity; `availableQuantity` caps increases
-when finite. `status` can be `IN_STOCK`, `PARTIALLY_IN_STOCK`, `OUT_OF_STOCK`, or
-`REMOVED_FROM_CATALOG`; surface unavailable lines and prevent checkout until resolved.
-
-## Routes and provider
-
-> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
-> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
-> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
-> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
-> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
-> [both patterns](../_shared/routing.md).
->
-> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
-> names as the router exports, and nothing you write is pinned to one template.
-
-**No shipped source reads needed to wire this.** `CartDrawer` and `CartButton`
-are default exports that take **no props**. `CartProvider` is a named export accepting `children`;
-wire these exactly as shown below.
-When adding storefront routes and providers to `src/App.jsx`, preserve the existing platform
-authentication setup, including `AuthProvider`, `useAuth`, and their `@/lib/AuthContext` imports.
-Do not remove or replace that authentication logic.
-The shipped commerce flow needs no login: shoppers browse, cart, and check out on the Wix visitor
-session, which is separate from platform user auth. Whether the storefront is public or members-only
-is the brief's call — default to public, and gate routes behind platform auth only when the brief
-asks for it. Neither choice affects the commerce flow.
-- Wrap the routed tree in `<CartProvider>` (from `@/context/CartContext`).
-- Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
-  route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every** page
-  — including your Shop and product-detail pages. Mount `<CartDrawer/>` once in the Layout.
-- Routes under the Layout: `/shop` → **your `Shop`** (renders your grid); `/product/:slug` → **your
-  `ProductDetail`**; `/` → **your `Home`**.
-
-Mount the default export `CartButton` from `@/components/CartButton` once in your header. It opens
-the drawer and shows the live count, inheriting `currentColor`; use it as-is, without a nested button.
-
-```jsx
-import { Routes, Route, Outlet } from "react-router-dom";
-import { CartProvider } from "@/context/CartContext";
-import CartDrawer from "@/components/CartDrawer";
-import Shop from "@/pages/Shop";                       // YOU build
-import ProductDetail from "@/pages/ProductDetail";     // YOU build
-import Home from "@/pages/Home";       // YOU build
-import Header from "@/components/Header";   // YOU build
-import Footer from "@/components/Footer";   // YOU build
-
-function Layout() {
-  return (<>
-    <Header />
-    <Outlet />
-    <Footer />
-    <CartDrawer />
-  </>);
-}
-
-<CartProvider>
-  <Routes>
-    <Route element={<Layout />}>                                   {/* chrome wraps all */}
-      <Route path="/" element={<Home />} />                        {/* yours */}
-      <Route path="/shop" element={<Shop />} />                    {/* yours */}
-      <Route path="/product/:slug" element={<ProductDetail />} />  {/* yours */}
-    </Route>
-  </Routes>
-</CartProvider>
-```
-
-### Optional banner integration — enabled entry flows only
-Follow the entry guide's banner choice. If it disables the banner, use the common wiring above
-without a banner import, mount, or banner-specific fixed region.
-
-When enabled, `WixManageBanner` is a default export with no props. It reads its own configuration,
-links to the site's dashboard, and renders only in preview; it returns null
-when dismissed or while the site id is a placeholder. Mount it once above the header in one fixed
-region; keep the header in flow within that region and offset the content by its measured height
-so dismissal or resizing leaves no gap or overlap. Replace only the example's `Layout` with:
-
-```jsx
-import { useRef, useState, useEffect } from "react";
-import WixManageBanner from "@/components/WixManageBanner";
-
-function Layout() {
-  const topRef = useRef(null);
-  const [offset, setOffset] = useState(0);
-  useEffect(() => {
-    const ro = new ResizeObserver(() => setOffset(topRef.current?.offsetHeight ?? 0));
-    if (topRef.current) ro.observe(topRef.current);
-    return () => ro.disconnect();
-  }, []);
-  return (<>
-    <div ref={topRef} style={{ position: "fixed", top: 0, left: 0, right: 0, zIndex: 50 }}>
-      <WixManageBanner />
-      <Header />
-    </div>
-    <div style={{ paddingTop: offset }}>
-      <Outlet />
-      <Footer />
-    </div>
-    <CartDrawer />
-  </>);
-}
-```
-
-
-### TanStack Start template — the same pages, mounted as files
-
-Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
-around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
-route is a two-line file; shipped pages stay in `src/pages/` untouched.
-
-| route | file | component |
-|---|---|---|
-| `/` | `src/routes/index.jsx` | `Home` |
-| `/shop` | `src/routes/shop.jsx` | `Shop` |
-| `/product/:slug` | `src/routes/product.$slug.jsx` | `ProductDetail` |
-
-```jsx
-// src/routes/shop.jsx
-import { createFileRoute } from "@tanstack/react-router";
-import Shop from "@/pages/Shop";
-
-export const Route = createFileRoute("/shop")({ component: Shop });
-```
-
-Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
-reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
-[`../_shared/routing.md`](../_shared/routing.md).
-
-## Missing capabilities
-For anything these interfaces do not cover, consult the official Wix API documentation using
-the documentation skill available in your environment.
-For a specifically missing field/interface or an observed runtime error, read only the relevant
-shipped file; catalog and cart helpers link their API references inline.
-
-## Hard rules
-- Header/footer live in a `Layout` around `<Outlet/>` (see **Routes and provider**) — keep shared chrome out of individual pages.
-- Checkout goes through the shipped cart (redirect-session) — never a hand-built `/checkout` URL.
-- Render live Wix data or your empty state — never mock products, reviews, ratings, or counts.
-- Prices and ribbons come from the hooks as-is: no computed percent-off, no "Sale" badge inferred from a compare-at price, no struck price beside a range.
-- Cart totals come from `summary`/`cart` — never summed or hardcoded in the client; shipping and tax say "calculated at checkout".