@wix/agent-skills 1.18.2 → 1.19.1

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

@@ -1,30 +1,31 @@
 # Storefront — playbook
 
 The commerce machinery ships as files — data layer, hooks, cart, checkout, SEO plumbing,
-typed end-to-end. **The presentation is yours**: you design and implement the product card,
-the grid, and the PDP surface on the shipped hooks/DTOs, plus the home page and the brand.
-You never write commerce code; you never skip designing the store.
+typed end-to-end. **The presentation doesn't ship — you build it** on the shipped hooks/DTOs:
+the shop and product (PDP) pages with their islands, the home page, and the brand. The
+skeletons below carry each page's contract — including the SSR and SEO machinery, which must
+be exact. You never write commerce code; you never skip designing the store.
 
 ## The file map (deployed into `src/`)
 
 **Don't read the shipped files** — this table and the contracts below are everything you
-need. Open a shipped file's source **only** on a real fallback: a runtime error, a field this
-playbook doesn't cover, or when a *reference* component's pattern is explicitly worth reading
-(marked below). Files you edit: `SiteLayout.astro`, `styles/global.css`, and the two page
-imports you swap to your own components.
+need. Open a shipped file's source **only** on a real fallback: a runtime error, or a field
+this playbook doesn't cover. Files you edit: `SiteLayout.astro` and `styles/global.css`.
+Files you **create** (skeletons below): the shop and PDP pages with their island components,
+plus your home page.
 
 | file | what it is |
 |---|---|
 | `wix/config.ts` · `wix/sdk.ts` | shared auth seam (deploy configures it — nothing to set by hand) |
 | `wix/media.ts` · `wix/money.ts` | `imgSrc()` / `formatMoney()` — already used by everything shipped |
 | `wix/storefront/types.ts` | the DTOs (`ProductSummary`, `ProductDetail`, `Cart`, `Category`) — contracts inlined below |
-| `wix/storefront/catalog.ts` | `fetchProducts`, `fetchProductsByCategory`, `fetchProductBySlug`, `fetchCategories`, `resolveVariant` |
+| `wix/storefront/catalog.ts` | `searchCatalog` (sort/filter/search + cursor paging, all server-side), `fetchProducts`, `fetchProductsByCategory`, `fetchProductBySlug`, `fetchCategories`, `resolveVariant` |
 | `wix/storefront/cart.ts` · `cart-store.ts` | Cart V2 + shared cart state (module store — spans Astro islands) |
 | `hooks/storefront/useCart.ts` | cart state + actions — contract below |
 | `hooks/storefront/useShop.ts` | listing + live category filter — contract below |
 | `hooks/storefront/useProductDetail.ts` | option selection → variant resolution → add-to-cart — contract below |
 | `components/storefront/CartButton.tsx` · `CartDrawer.tsx` | header badge + slide-over cart — **wire as-is** (drawer once per page) |
-| `components/storefront/ShopView.tsx` · `ProductCard.tsx` · `ProductGrid.tsx` · `ProductDetailView.tsx` · `VariantPicker.tsx` | **REFERENCE implementations** — correct, plain, deliberately generic. Read for patterns if useful; **build your own instead of shipping them** (below) |
+| `components/storefront/ShopView.tsx` · `ProductDetailView.tsx` | **don't ship — YOU create them** (skeletons below): the client islands your shop and PDP pages mount |
 | `styles/global.css` | **the design system**: Tailwind v4 + the `@theme` token block (colors, radii, fonts — same token family as the official Wix templates). Everything, shipped and yours, styles from these tokens |
 
 Astro stack additionally gets:
@@ -32,24 +33,26 @@ Astro stack additionally gets:
 | file | what it is |
 |---|---|
 | `layouts/SiteLayout.astro` | the site chrome — **yours to brand**: header, footer, nav. Keep the `<slot name="seo-tags" />`, the global.css import, and the CartButton/CartDrawer mounts |
-| `pages/shop.astro` | SSR listing page — **keep its frontmatter** (the data fetching), swap the island import to YOUR shop component |
-| `pages/products/[slug].astro` | SSR PDP with owner-editable SEO — **keep its frontmatter and the SEO pieces** (`wixMetadata`, `loadSEOTagsServiceConfig`, `<SEO.Tags>`) exactly, swap the island import to YOUR detail component |
+| `pages/shop.astro` · `pages/products/[slug].astro` | **don't ship — YOU create them** (skeletons below): thin SSR pages that fetch server-side and mount your islands; the PDP page carries the owner-editable SEO machinery, exactly as its skeleton shows |
 
 ## What you build — this is the design job, not optional polish
 
-You implement **four surfaces yourself**, styled with Tailwind utilities on the `@theme`
-tokens, designed to fit the brief (the business, the tone, the audience — a toy brand and a
-jewelry house should not get the same store):
+You implement **three surfaces yourself** — each an SSR page plus its island, per the
+skeletons below — styled with Tailwind utilities on the `@theme` tokens, designed to fit the
+brief (the business, the tone, the audience — a toy brand and a jewelry house should not get
+the same store):
 
-1. **The product card + grid** — your tile design (image treatment, badges, price/sale
-   presentation, hover behavior) and your grid rhythm (columns, density, maybe an editorial
-   featured tile). Keep skeleton-while-loading and an honest empty state (the reference
-   `ProductGrid` shows the pattern — `products === null` → skeletons, `[]` → empty message).
-2. **The shop surface** — category filter + your grid, on `useShop`.
-3. **The PDP surface** — gallery, price/sale, description, your option-selection UI (color
-   options = real swatches), quantity, add-to-cart — on `useProductDetail`, which owns ALL
-   selection/variant logic; you own how it looks.
-4. **The home page** — hero, featured products (fetch in frontmatter → your grid), brand story.
+1. **The shop page + `ShopView`** (skeletons below) — category filter + your grid of your
+   tiles: image treatment, badges, price/sale presentation, hover behavior, grid rhythm
+   (columns, density, maybe an editorial featured tile). `products === null` → skeleton tiles,
+   `[]` → an honest empty state. Decompose into `ProductCard`/`ProductGrid` files if you like —
+   your call, nothing prescribes it.
+2. **The PDP page + `ProductDetailView`** (skeletons below) — gallery, price/sale,
+   description, your option-selection UI (color options = real swatches), quantity,
+   add-to-cart — on `useProductDetail`, which owns ALL selection/variant logic; you own how it
+   looks. This is the surface that most often looks generic — make the layout the brand's: an
+   editorial split, a sticky buy column, a full-bleed gallery.
+3. **The home page** — hero, featured products (fetch in frontmatter → your grid), brand story.
 
 Plus the **theme** (edit the `@theme` block in `styles/global.css` — one edit; a dark brand is
 flipped token values; add brand fonts as extra tokens) and the **chrome** (header/footer in
@@ -64,10 +67,17 @@ flipped token values; add brand fonts as extra tokens) and the **chrome** (heade
 //   imageUrl, hoverImageUrl, optionsSummary /* "2 colors · 3 sizes" */, quickAddable: boolean }
 // price vs maxPrice differ → show a range. quickAddable → useCart().addToCart(product.id).
 
-// useShop({ initialProducts?, initialCategories? }) →
+// useShop({ initialProducts?, initialCategories?, pageSize? /* 24 */ }) →
 // { products: ProductSummary[]|null /* null = loading → skeletons */, categories: Category[],
-//   activeCategoryId: string|null, setActiveCategoryId(id|null), loading, error }
+//   activeCategoryId: string|null, setActiveCategoryId(id|null),
+//   sort: keyof SORTS, setSort(sort), filters, setFilters({ minPrice?, maxPrice?, inStockOnly?, search? }),
+//   loading, error, retry(), hasMore, loadMore(), loadingMore }
 // Category = { id, slug, name }. Render the filter bar only when categories.length > 1.
+// Sort/filter/search/paging run on Wix across the WHOLE catalog (a change restarts the list).
+// SORTS (exported next to useShop) is Record<sortKey, { label: string }> — the value is an
+// OBJECT, so render entry.label, never the entry itself:
+//   Object.entries(SORTS).map(([key, { label }]) => <option value={key}>{label}</option>)
+// hasMore → render a "load more" control calling loadMore() (disabled while loadingMore).
 
 // useProductDetail({ initial? /* SSR */, slug? /* SPA */ }) →
 // { product: ProductDetail|null, notFound,
@@ -84,16 +94,165 @@ flipped token values; add brand fonts as extra tokens) and the **chrome** (heade
 // { cart: { lines, itemCount, subtotal, currency }|null, busy, error, open,
 //   addToCart(productId, variantId?, qty?, extras?), updateQuantity(lineItemId, qty),
 //   removeLine(lineItemId), checkout(), openCart(), closeCart(), refresh() }
+// addToCart rejects on refusal (out of stock, digital product with no file) AND records
+// .error, opening the drawer either way — so render .error in whatever surface you build for
+// the cart, and never chain checkout() onto an add without awaiting it successfully.
+```
+
+### The pages and islands you create — skeletons
+
+Nothing renders until you write these — the store IS your work. Each page is a thin SSR shell
+(fetch → DTO props → island); each island is a thin view over a hook. The pages' frontmatter
+is **machinery, not design** — reproduce it as the skeletons show, exactly. Hooks first,
+branches after (an early return above a hook changes hook order between renders and React
+throws). The islands render on the server too (`client:load` SSRs), and by then the 200 and
+headers are already sent — a render throw truncates the body mid-stream and surfaces to the
+visitor as `ERR_HTTP2_PROTOCOL_ERROR`, not an error page. Render every state totally; nothing
+in a render path may throw.
+
+```astro
+---
+// src/pages/shop.astro — YOU create it. Products and categories are fetched SERVER-SIDE
+// (SEO: view-source shows product names) and handed to the island as serialized DTO props;
+// category switches then filter live on the client.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import ShopView from "../components/storefront/ShopView";
+import { fetchProducts, fetchCategories } from "../wix/storefront/catalog";
+import type { Category, ProductSummary } from "../wix/storefront/types";
+
+let products: ProductSummary[] = [];
+let categories: Category[] = [];
+try {
+  [products, categories] = await Promise.all([fetchProducts({ limit: 24 }), fetchCategories()]);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream; the island
+  // renders your empty state instead.
+}
+---
+<SiteLayout title="Shop">
+  <!-- your page heading / intro, then: -->
+  <ShopView client:load initialProducts={products} initialCategories={categories} />
+</SiteLayout>
+```
+
+```astro
+---
+// src/pages/products/[slug].astro — YOU create it. This is a Wix ITEM PAGE: the wixMetadata
+// export + <SEO.Tags> are what let the site owner edit this page's title/description/OG in
+// the dashboard and register the route in the sitemap. All three SEO pieces are REQUIRED,
+// exactly as here.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import ProductDetailView from "../../components/storefront/ProductDetailView";
+import { fetchProductBySlug } from "../../wix/storefront/catalog";
+import { WIX_APPS } from "@wix/essentials";
+import { SEO } from "@wix/seo/components";
+import { loadSEOTagsServiceConfig } from "@wix/seo/services";
+import { seoTags } from "@wix/seo";
+
+export const wixMetadata = {
+  appDefId: WIX_APPS.checkoutAndOrders.id,
+  pageIdentifier: WIX_APPS.checkoutAndOrders.productPageMetadata.pageIdentifier,
+  identifiers: { slug: WIX_APPS.checkoutAndOrders.productPageMetadata.identifiers.handle },
+};
+
+const slug = Astro.params.slug!;
+
+// Behind Wix's proxy the request URL is the internal one — the real public page URL arrives
+// on x-wix-forwarded-url, and the SEO service needs the public one.
+const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
+    ? forwardedUrl
+    : Astro.url.href;
+
+let product = null;
+let seoTagsServiceConfig = null;
+try {
+  [product, seoTagsServiceConfig] = await Promise.all([
+    fetchProductBySlug(slug),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.STORES_PRODUCT,
+      itemData: { slug },
+    }),
+  ]);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!product) {
+  return new Response(null, { status: 404 });
+}
+---
+<SiteLayout title={product.name}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+  <ProductDetailView client:load initial={product} />
+</SiteLayout>
+```
+
+```tsx
+// src/components/storefront/ShopView.tsx — YOU build it; your shop.astro mounts it.
+import { useShop } from "../../hooks/storefront/useShop";
+import type { Category, ProductSummary } from "../../wix/storefront/types";
+
+export default function ShopView(props: {
+  initialProducts?: ProductSummary[];   // SSR props from your shop.astro — pass straight
+  initialCategories?: Category[];       // to useShop; omitted in a SPA (client fetch)
+}) {
+  const { products, categories, activeCategoryId, setActiveCategoryId, loading, error } =
+    useShop(props);
+  // …you implement the render:
+  //   • category pills when categories.length > 1 — All + one per category,
+  //     driving setActiveCategoryId(id | null)
+  //   • a sort control over SORTS driving setSort; filters (price bounds, in-stock,
+  //     name search) via setFilters — include the ones that fit the brief, not all of them
+  //   • error → a short inline message (retry() re-runs the query)
+  //   • products === null (or loading) → skeleton tiles; [] → your honest empty state
+  //   • else YOUR grid of YOUR tiles (ProductSummary contract above): image
+  //     (hoverImageUrl on hover), name, price/compareAtPrice, ribbon, optionsSummary;
+  //     tile links to `/products/${p.slug}`; quickAddable → useCart().addToCart(p.id)
+  //   • hasMore → your "load more" control calling loadMore() (disabled while loadingMore)
+}
+```
+
+```tsx
+// src/components/storefront/ProductDetailView.tsx — YOU build the whole PDP surface;
+// your [slug].astro mounts it with the server-fetched product.
+import { useProductDetail } from "../../hooks/storefront/useProductDetail";
+import type { ProductDetail } from "../../wix/storefront/types";
+
+export default function ProductDetailView(props: {
+  initial?: ProductDetail | null;   // SSR (Astro); a SPA passes { slug } instead
+  slug?: string;
+}) {
+  const d = useProductDetail(props);   // full contract above — selection lives HERE
+  // …you implement the render. Handle in order:
+  //   d.notFound  → a "doesn't exist (anymore)" message
+  //   !d.product  → a loading placeholder
+  //   else the product view, laid out for the brand:
+  //     • gallery from d.product.gallery (urls, main first): show ONE primary
+  //       image at full size, and the rest as a small thumbnail strip (or a
+  //       scrollable row) that swaps the primary — never map the whole gallery
+  //       to full-width images stacked down the column (products with per-color
+  //       linked media carry several gallery urls, so that stacks big duplicates).
+  //       A single-image gallery is just the one primary — no empty strip.
+  //     • name, live d.price / d.compareAtPrice (strike only when they differ),
+  //       descriptionHtml rendered as HTML
+  //     • option controls from d.optionGroups → d.selectOption(optionName, choiceName)
+  //       (isColor → real swatches via colorCode; disable out-of-stock choices);
+  //       modifiers from d.product.modifiers → d.setModifier(key, value), "*" = mandatory
+  //     • quantity (d.quantity / d.setQuantity), then the buy button gated by d.canAdd
+  //       ONLY — never resolve variants yourself — calling d.add(); d.adding disables,
+  //       d.error renders inline
+}
 ```
 
 ### Wiring — Astro (default)
 
 1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass).
-2. Write your components under `src/components/storefront/` (new file names — don't overwrite
-   the references), then **swap the island import** in `pages/shop.astro` and
-   `pages/products/[slug].astro` to yours — keep each page's frontmatter (data fetching, SEO
-   pieces) exactly as shipped. Primary-content islands mount `client:load` with the SSR props;
-   browser-state widgets (cart) are `client:only="react"` — the shipped mounts show this.
+2. Create the shop and PDP pages and their islands per the skeletons above — frontmatter
+   machinery exact, presentation yours. Primary-content islands mount `client:load` with the
+   SSR props; browser-state widgets (cart) are `client:only="react"`.
 3. Write `pages/index.astro` (home) on `SiteLayout`.
 
 ### Wiring — React SPA (Vite etc.)
@@ -109,7 +268,7 @@ client id into `wix/config.ts`; nothing else to configure.
 
 - **Data and commerce logic only through the shipped exports** — never rewrite their
   internals or re-derive a request shape. Extend by calling the exports or adding a new
-  function in `wix/storefront/` for a genuine gap (API contracts: the `wix-docs` skill).
+  function in `wix/storefront/` for what they don't cover (API contracts: the `wix-docs` skill).
 - **Selection→cart goes through `useProductDetail`** — never add a product with options by
   picking `variants[0]`, and never gate `canAdd` yourself.
 - Don't wrap shipped calls in your own API routes — they run client-side by design.
@@ -117,8 +276,18 @@ client id into `wix/config.ts`; nothing else to configure.
   parallel theme files, no hardcoded palette values in components.
 - Checkout only through the shipped cart (`checkout()`) — never a hand-built checkout URL.
 - Live data or an honest empty state — never mock products, prices, reviews, or counts.
-- Keep the PDP page's SEO pieces (`wixMetadata` + `loadSEOTagsServiceConfig` + `<SEO.Tags>`)
-  exactly as shipped — owners edit those tags in their dashboard.
+- Your PDP page carries the SEO pieces (`wixMetadata` + `loadSEOTagsServiceConfig` +
+  `<SEO.Tags>`) exactly as the skeleton shows — owners edit those tags in their dashboard.
+- **Browsing, cart and checkout need no login.** They run on the Wix visitor session the
+  shipped SDK client already holds. Don't gate the shop, the PDP or the cart behind sign-in,
+  and don't add a members/auth flow unless the brief actually asks for accounts.
+- **Call every hook before any conditional return.** A PDP that returns early for
+  `notFound`/loading above its `useState`/`useEffect` changes hook order between renders and
+  React throws. Hooks first, branches after.
+- **Sort and filter at the source, not on a loaded page.** `useShop`'s sort/filters/search and
+  `searchCatalog` run on Wix across the whole catalog before cursor paging; re-ordering the
+  array a hook already returned only sorts the slice you happen to have. Never sort/filter
+  client-side, and never raise the page limit instead of paging (`hasMore`/`loadMore`).
 
 ## Point the user to their dashboard
 
@@ -144,6 +313,6 @@ a color option, ≥1 on sale, an image per product) unless the brief says otherw
       a reload (same visitor token).
 - [ ] Checkout button redirects to Wix-hosted checkout.
 - [ ] PDP view-source carries the SEO tags (Astro).
-- [ ] Card/grid/PDP/home are YOUR designs on the tokens — not the shipped references; the
-      data-layer/hook/cart files are unedited.
+- [ ] Shop/PDP/home are YOUR designs on the tokens; the data-layer/hook/cart files are
+      unedited.
 - [ ] Dashboard links handed to the owner.

package/skills/wix-headless-fast/references/storefront/app/hooks/storefront/useShop.ts

@@ -1,21 +1,33 @@
-// Catalog listing + category filter for a shop/listing surface.
+// Catalog listing for a shop surface: category filter, sort, price/stock/search filters, and
+// cursor paging — all applied by Wix across the whole catalog (searchCatalog), never to a page
+// already in hand. A changed selection starts a fresh cursor chain.
 //
-// SSR-friendly: when the host fetched the data already (Astro frontmatter, a server
-// component), pass it as `initial` and no client fetch happens for it. In a pure SPA,
-// pass nothing and the hook fetches on mount. Category switches always fetch live
-// (server-side-filtered by the category id).
-import { useEffect, useState } from "react";
+// SSR-friendly: pass `initialProducts`/`initialCategories` (Astro frontmatter) and they render
+// immediately — the hook still revalidates the first page once on mount to open the cursor
+// chain, replacing the seed without a skeleton flash.
+import { useCallback, useEffect, useRef, useState } from "react";
 import {
+  CATALOG_SORTS,
   fetchCategories,
-  fetchProducts,
-  fetchProductsByCategory,
+  searchCatalog,
+  type CatalogSort,
 } from "../../wix/storefront/catalog";
 import type { Category, ProductSummary } from "../../wix/storefront/types";
 
+export const SORTS = CATALOG_SORTS;
+
+export interface ShopFilters {
+  minPrice?: number | string;
+  maxPrice?: number | string;
+  inStockOnly?: boolean;
+  /** Name search, max 100 chars. */
+  search?: string;
+}
+
 export interface UseShopOptions {
   initialProducts?: ProductSummary[];
   initialCategories?: Category[];
-  limit?: number;
+  pageSize?: number;
 }
 
 export interface UseShop {
@@ -25,21 +37,63 @@ export interface UseShop {
   /** null = "all products". */
   activeCategoryId: string | null;
   setActiveCategoryId: (id: string | null) => void;
+  sort: CatalogSort;
+  setSort: (sort: CatalogSort) => void;
+  filters: ShopFilters;
+  setFilters: (filters: ShopFilters) => void;
   loading: boolean;
   error: string | null;
+  retry: () => void;
+  hasMore: boolean;
+  loadMore: () => Promise<void>;
+  loadingMore: boolean;
+}
+
+interface PageState {
+  key: string | null;
+  products: ProductSummary[] | null;
+  cursor: string | null;
+  error: string | null;
+  loadingMore: boolean;
 }
 
-export function useShop({ initialProducts, initialCategories, limit = 100 }: UseShopOptions = {}): UseShop {
-  const [products, setProducts] = useState<ProductSummary[] | null>(initialProducts ?? null);
+export function useShop({
+  initialProducts,
+  initialCategories,
+  pageSize = 24,
+}: UseShopOptions = {}): UseShop {
   const [categories, setCategories] = useState<Category[]>(initialCategories ?? []);
   const [activeCategoryId, setActiveCategoryId] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
+  const [sort, setSort] = useState<CatalogSort>("featured");
+  const [filters, setFilters] = useState<ShopFilters>({});
+  const [attempt, setAttempt] = useState(0);
+  const [page, setPage] = useState<PageState>({
+    key: null,
+    products: initialProducts ?? null,
+    cursor: null,
+    error: null,
+    loadingMore: false,
+  });
+  const generation = useRef(0);
+  const pendingMore = useRef<object | null>(null);
+
+  const key = JSON.stringify([
+    pageSize,
+    activeCategoryId,
+    sort,
+    filters.minPrice ?? null,
+    filters.maxPrice ?? null,
+    !!filters.inStockOnly,
+    filters.search ?? "",
+    attempt,
+  ]);
+  const currentKey = useRef(key);
+  currentKey.current = key;
 
   useEffect(() => {
     if (initialCategories) return;
     let alive = true;
-    fetchCategories().then((c) => alive && setCategories(c));
+    fetchCategories().then((list) => alive && setCategories(list)).catch(() => alive && setCategories([]));
     return () => {
       alive = false;
     };
@@ -47,34 +101,90 @@ export function useShop({ initialProducts, initialCategories, limit = 100 }: Use
   }, []);
 
   useEffect(() => {
-    // The initial all-products data may have come from the server; only fetch when it
-    // didn't, or when the buyer picked a category.
-    if (activeCategoryId === null && initialProducts) {
-      setProducts(initialProducts);
-      return;
-    }
+    const id = ++generation.current;
     let alive = true;
-    setLoading(true);
-    setError(null);
-    const load = activeCategoryId
-      ? fetchProductsByCategory(activeCategoryId, { limit })
-      : fetchProducts({ limit });
-    load
-      .then((items) => {
-        if (!alive) return;
-        setProducts(items);
+    pendingMore.current = null;
+    // Keep the SSR seed (or the previous page) on screen while the fresh query runs;
+    // only a selection change with no seed shows skeletons.
+    setPage((p) => ({ key, products: p.key === null ? p.products : null, cursor: null, error: null, loadingMore: false }));
+    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search] = JSON.parse(key);
+    searchCatalog({ 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) return;
-        setProducts([]);
-        setError(e instanceof Error ? e.message : String(e));
-      })
-      .finally(() => alive && setLoading(false));
+        if (alive && generation.current === id && currentKey.current === key) {
+          setPage({
+            key,
+            products: [],
+            cursor: null,
+            error: e instanceof Error ? e.message : "Couldn't load products.",
+            loadingMore: false,
+          });
+        }
+      });
     return () => {
       alive = false;
+      generation.current++;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [activeCategoryId, limit]);
+  }, [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 searchCatalog({ 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 instanceof 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), []);
 
-  return { products, categories, activeCategoryId, setActiveCategoryId, loading, error };
+  const current = page.key === key;
+  const seeded = page.key === null && page.products !== null; // SSR seed, first query in flight
+  // Seeded content on screen is not "loading" — skeletons are only for a genuinely empty wait.
+  const loading = (!current && !seeded) || (current && page.products === null);
+  return {
+    categories,
+    activeCategoryId,
+    setActiveCategoryId,
+    sort,
+    setSort,
+    filters,
+    setFilters,
+    products: current || seeded ? page.products : null,
+    loading,
+    error: current ? page.error : null,
+    retry,
+    hasMore: current && !!page.cursor,
+    loadMore,
+    loadingMore: current && page.loadingMore,
+  };
 }

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/cart-store.ts

@@ -72,8 +72,14 @@ export async function addLine(
   quantity = 1,
   extras?: AddToCartExtras,
 ): Promise<void> {
-  await run(() => apiAdd(productId, variantId, quantity, extras));
-  setState({ open: true });
+  try {
+    await run(() => apiAdd(productId, variantId, quantity, extras));
+  } finally {
+    // Open either way. On success this shows the new line; on refusal it's the only thing that
+    // makes .error visible — the drawer renders it, and a drawer that stays shut on failure
+    // turns a refused add (out of stock, a digital product with no file) into silence.
+    setState({ open: true });
+  }
 }
 
 export async function updateLineQuantity(lineItemId: string, quantity: number): Promise<void> {