@wix/agent-skills 1.19.1 → 1.20.0

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

@@ -1,18 +1,24 @@
-// 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.
+// Catalog listing for a shop or category surface: category, sort, price/stock/search filters,
+// option facets, 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.
+//
+// URL state: sort, filters, facet choices (and a live category switch on /shop) are read from the
+// query string on mount and written back with replaceState — a filtered gallery is a link a
+// shopper can share, reload, and step back to. Paging stays out of the URL.
 //
 // 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.
+// chain, replacing the seed without a skeleton flash. A /category/[slug] page passes
+// `initialCategoryId` so the first query is already scoped.
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
   CATALOG_SORTS,
   fetchCategories,
+  fetchFacetData,
   searchCatalog,
   type CatalogSort,
 } from "../../wix/storefront/catalog";
-import type { Category, ProductSummary } from "../../wix/storefront/types";
+import type { Category, Facet, PriceRange, ProductSummary } from "../../wix/storefront/types";
 
 export const SORTS = CATALOG_SORTS;
 
@@ -27,12 +33,16 @@ export interface ShopFilters {
 export interface UseShopOptions {
   initialProducts?: ProductSummary[];
   initialCategories?: Category[];
+  /** Scope the listing to one category from the first render (a /category/[slug] page). */
+  initialCategoryId?: string | null;
   pageSize?: number;
 }
 
 export interface UseShop {
   /** null while the first load is in flight — render skeletons, not an empty state. */
   products: ProductSummary[] | null;
+  /** Matching products across the whole catalog for the current selection; null until known. */
+  total: number | null;
   categories: Category[];
   /** null = "all products". */
   activeCategoryId: string | null;
@@ -41,6 +51,17 @@ export interface UseShop {
   setSort: (sort: CatalogSort) => void;
   filters: ShopFilters;
   setFilters: (filters: ShopFilters) => void;
+  /** The filterable options of the current scope (Color, Size…), from the catalog itself. */
+  facets: Facet[];
+  /** Lowest and highest product price in the scope — the price slider's bounds; null until known or when all prices are equal. */
+  priceRange: PriceRange | null;
+  /** Selected facet choice ids — products carrying ANY of them match. */
+  selectedChoiceIds: string[];
+  toggleChoice: (choiceId: string) => void;
+  /** Clears price/stock/search filters and facet selections (keeps category and sort). */
+  clearFilters: () => void;
+  /** True when any filter or facet is active. */
+  hasActiveFilters: boolean;
   loading: boolean;
   error: string | null;
   retry: () => void;
@@ -49,9 +70,29 @@ export interface UseShop {
   loadingMore: boolean;
 }
 
+const URL_KEYS = { sort: "sort", min: "min", max: "max", stock: "stock", q: "q", choice: "choice", category: "category" } as const;
+
+function readUrlState(): { sort?: CatalogSort; filters: ShopFilters; choiceIds: string[]; categoryId?: string | null } | null {
+  if (typeof window === "undefined") return null;
+  const p = new URLSearchParams(window.location.search);
+  const sort = p.get(URL_KEYS.sort);
+  const filters: ShopFilters = {};
+  if (p.get(URL_KEYS.min)) filters.minPrice = p.get(URL_KEYS.min)!;
+  if (p.get(URL_KEYS.max)) filters.maxPrice = p.get(URL_KEYS.max)!;
+  if (p.get(URL_KEYS.stock) === "1") filters.inStockOnly = true;
+  if (p.get(URL_KEYS.q)) filters.search = p.get(URL_KEYS.q)!;
+  return {
+    sort: sort && sort in CATALOG_SORTS ? (sort as CatalogSort) : undefined,
+    filters,
+    choiceIds: p.getAll(URL_KEYS.choice),
+    categoryId: p.has(URL_KEYS.category) ? p.get(URL_KEYS.category) : undefined,
+  };
+}
+
 interface PageState {
   key: string | null;
   products: ProductSummary[] | null;
+  total: number | null;
   cursor: string | null;
   error: string | null;
   loadingMore: boolean;
@@ -60,22 +101,39 @@ interface PageState {
 export function useShop({
   initialProducts,
   initialCategories,
+  initialCategoryId = null,
   pageSize = 24,
 }: UseShopOptions = {}): UseShop {
   const [categories, setCategories] = useState<Category[]>(initialCategories ?? []);
-  const [activeCategoryId, setActiveCategoryId] = useState<string | null>(null);
+  const [activeCategoryId, setActiveCategoryId] = useState<string | null>(initialCategoryId);
   const [sort, setSort] = useState<CatalogSort>("featured");
   const [filters, setFilters] = useState<ShopFilters>({});
+  const [selectedChoiceIds, setSelectedChoiceIds] = useState<string[]>([]);
+  const [facets, setFacets] = useState<Facet[]>([]);
+  const [priceRange, setPriceRange] = useState<PriceRange | null>(null);
   const [attempt, setAttempt] = useState(0);
   const [page, setPage] = useState<PageState>({
     key: null,
     products: initialProducts ?? null,
+    total: null,
     cursor: null,
     error: null,
     loadingMore: false,
   });
   const generation = useRef(0);
   const pendingMore = useRef<object | null>(null);
+  const firstWrite = useRef(true);
+
+  // Adopt the URL's selection once, after hydration (the server rendered the defaults).
+  useEffect(() => {
+    const u = readUrlState();
+    if (!u) return;
+    if (u.sort) setSort(u.sort);
+    if (Object.keys(u.filters).length) setFilters(u.filters);
+    if (u.choiceIds.length) setSelectedChoiceIds(u.choiceIds);
+    if (u.categoryId !== undefined && u.categoryId !== initialCategoryId) setActiveCategoryId(u.categoryId || null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
 
   const key = JSON.stringify([
     pageSize,
@@ -85,11 +143,35 @@ export function useShop({
     filters.maxPrice ?? null,
     !!filters.inStockOnly,
     filters.search ?? "",
+    [...selectedChoiceIds].sort(),
     attempt,
   ]);
   const currentKey = useRef(key);
   currentKey.current = key;
 
+  // Mirror the selection into the query string (defaults are omitted; nothing else in the URL is touched).
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    // The mount run still holds the defaults (the adopted URL state lands on the next render) —
+    // writing now would erase the very params being adopted.
+    if (firstWrite.current) {
+      firstWrite.current = false;
+      return;
+    }
+    const p = new URLSearchParams(window.location.search);
+    for (const k of Object.values(URL_KEYS)) p.delete(k);
+    if (sort !== "featured") p.set(URL_KEYS.sort, sort);
+    if (filters.minPrice != null && filters.minPrice !== "") p.set(URL_KEYS.min, String(filters.minPrice));
+    if (filters.maxPrice != null && filters.maxPrice !== "") p.set(URL_KEYS.max, String(filters.maxPrice));
+    if (filters.inStockOnly) p.set(URL_KEYS.stock, "1");
+    if (filters.search?.trim()) p.set(URL_KEYS.q, filters.search.trim());
+    for (const id of selectedChoiceIds) p.append(URL_KEYS.choice, id);
+    if (activeCategoryId !== initialCategoryId) p.set(URL_KEYS.category, activeCategoryId ?? "");
+    const qs = p.toString();
+    const next = `${window.location.pathname}${qs ? `?${qs}` : ""}${window.location.hash}`;
+    if (next !== `${window.location.pathname}${window.location.search}${window.location.hash}`) window.history.replaceState(window.history.state, "", next);
+  }, [key, sort, filters, selectedChoiceIds, activeCategoryId, initialCategoryId]);
+
   useEffect(() => {
     if (initialCategories) return;
     let alive = true;
@@ -100,18 +182,31 @@ export function useShop({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // Facets follow the category scope (a Size facet in "Donuts" is meaningless).
+  useEffect(() => {
+    let alive = true;
+    fetchFacetData({ categoryId: activeCategoryId }).then((d) => {
+      if (!alive) return;
+      setFacets(d.facets);
+      setPriceRange(d.priceRange);
+    });
+    return () => {
+      alive = false;
+    };
+  }, [activeCategoryId]);
+
   useEffect(() => {
     const id = ++generation.current;
     let alive = true;
     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 })
+    setPage((p) => ({ key, products: p.key === null ? p.products : null, total: null, cursor: null, error: null, loadingMore: false }));
+    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search, choiceIds] = JSON.parse(key);
+    searchCatalog({ limit, categoryId, sort: selectedSort, minPrice, maxPrice, inStockOnly, search, choiceIds })
       .then((res) => {
         if (alive && generation.current === id && currentKey.current === key) {
-          setPage({ key, products: res.products, cursor: res.nextCursor, error: null, loadingMore: false });
+          setPage({ key, products: res.products, total: res.total, cursor: res.nextCursor, error: null, loadingMore: false });
         }
       })
       .catch((e) => {
@@ -119,6 +214,7 @@ export function useShop({
           setPage({
             key,
             products: [],
+            total: null,
             cursor: null,
             error: e instanceof Error ? e.message : "Couldn't load products.",
             loadingMore: false,
@@ -166,12 +262,29 @@ export function useShop({
   }, [key, page.key, page.cursor, pageSize]);
 
   const retry = useCallback(() => setAttempt((n) => n + 1), []);
+  const toggleChoice = useCallback(
+    (choiceId: string) =>
+      setSelectedChoiceIds((ids) => (ids.includes(choiceId) ? ids.filter((x) => x !== choiceId) : [...ids, choiceId])),
+    [],
+  );
+  const clearFilters = useCallback(() => {
+    setFilters({});
+    setSelectedChoiceIds([]);
+  }, []);
 
   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);
+  const hasActiveFilters =
+    selectedChoiceIds.length > 0 ||
+    !!filters.inStockOnly ||
+    filters.minPrice != null && filters.minPrice !== "" ||
+    filters.maxPrice != null && filters.maxPrice !== "" ||
+    !!(filters.search && filters.search.trim());
   return {
+    products: current || seeded ? page.products : null,
+    total: current ? page.total : null,
     categories,
     activeCategoryId,
     setActiveCategoryId,
@@ -179,7 +292,12 @@ export function useShop({
     setSort,
     filters,
     setFilters,
-    products: current || seeded ? page.products : null,
+    facets,
+    priceRange,
+    selectedChoiceIds,
+    toggleChoice,
+    clearFilters,
+    hasActiveFilters,
     loading,
     error: current ? page.error : null,
     retry,

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

@@ -65,6 +65,21 @@ function cartCurrency(raw: RawCart | null): string {
   return raw?.customerInfo?.currencyCode ?? raw?.businessInfo?.currencyCode ?? "";
 }
 
+// "Monthly plan · every 2 months · 6 payments" from the line's subscriptionInfo (Cart V2 carries the
+// plan on the line); "" for a one-time purchase. Never invented — every word comes from the plan.
+function subscriptionTerms(info: RawCart | undefined): string {
+  if (!info) return "";
+  const s: RawCart = info.subscriptionSettings ?? {};
+  const unit: Record<string, string> = { DAY: "day", WEEK: "week", MONTH: "month", YEAR: "year" };
+  const parts: string[] = [];
+  const title = info.title?.original ?? info.title?.translated ?? "";
+  if (title) parts.push(title);
+  const u = unit[String(s.frequency ?? "")];
+  if (u) parts.push(`every ${s.interval && s.interval > 1 ? `${s.interval} ${u}s` : u}`);
+  if (!s.autoRenewal && s.billingCycles) parts.push(`${s.billingCycles} payments`);
+  return parts.join(" · ");
+}
+
 function toLine(raw: RawCart, currency: string): CartLine {
   const descriptionLines: string[] = (raw.attributes?.descriptionLines ?? [])
     .map((d: RawCart) => {
@@ -82,32 +97,41 @@ function toLine(raw: RawCart, currency: string): CartLine {
     imageUrl: imgSrc(raw.attributes?.image, 300, 300),
     descriptionLines,
     status: raw.status ?? "IN_STOCK",
+    subscription: subscriptionTerms(raw.subscriptionInfo),
   };
 }
 
-function toCart(raw: RawCart | null, subtotal: string): Cart {
+function toCart(raw: RawCart | null, subtotal: string, discount = ""): Cart {
   const currency = cartCurrency(raw);
   const lines = (raw?.lineItems ?? []).map((l: RawCart) => toLine(l, currency));
   return {
     lines,
     itemCount: lines.reduce((sum: number, l: CartLine) => sum + l.quantity, 0),
     subtotal,
+    discount,
     currency,
   };
 }
 
 async function readCartWithSubtotal(raw: RawCart | null): Promise<Cart> {
+  // Only estimate a cart WITH lines — on an absent/empty cart the endpoint returns 404.
   if (!raw?.lineItems?.length) return toCart(raw, "");
-  // The authoritative after-discount subtotal comes from the cart estimate, never from
-  // hand-summing line items (tax and shipping resolve at checkout).
+  // The authoritative after-discount subtotal and the CART-level discount come from the cart
+  // estimate, never from hand-summing lines. Its delivery/tax/fees read "0" when nothing was
+  // calculated — never render those as "Free"; shipping and tax resolve at checkout.
   let subtotal = "";
+  let discount = "";
   try {
     const estimate: RawCart = await cartApi.estimateCurrentCart();
-    subtotal = formatMoney(estimate?.summary?.priceSummary?.subtotal, cartCurrency(raw));
+    const summary = estimate?.summary?.priceSummary;
+    const currency = cartCurrency(raw);
+    subtotal = formatMoney(summary?.subtotal, currency);
+    const d = summary?.discount;
+    if (Number(d?.convertedAmount ?? d?.amount ?? 0) > 0) discount = formatMoney(d, currency);
   } catch {
     /* estimate is a display nicety — the cart itself is still valid */
   }
-  const cart = toCart(raw, subtotal);
+  const cart = toCart(raw, subtotal, discount);
   await fillLineImages(cart.lines, raw.lineItems as RawCart[]);
   return cart;
 }
@@ -127,6 +151,10 @@ export interface AddToCartExtras {
   modifierChoices?: Record<string, string>;
   /** FREE_TEXT modifier inputs: freeTextSettings key -> the buyer's text. */
   customTextFields?: Record<string, string>;
+  /** The variant is out of stock but pre-orderable — sends preOrderRequested. */
+  preorder?: boolean;
+  /** A chosen recurring plan (subscriptionPricesInfo); omit for a one-time purchase. */
+  subscriptionOptionId?: string;
 }
 
 /**
@@ -138,12 +166,14 @@ export async function addToCart(
   productId: string,
   variantId?: string | null,
   quantity = 1,
-  { modifierChoices, customTextFields }: AddToCartExtras = {},
+  { modifierChoices, customTextFields, preorder, subscriptionOptionId }: AddToCartExtras = {},
 ): Promise<Cart> {
   const options: Record<string, unknown> = {};
   if (variantId) options.variantId = variantId;
   if (modifierChoices && Object.keys(modifierChoices).length) options.options = modifierChoices;
   if (customTextFields && Object.keys(customTextFields).length) options.customTextFields = customTextFields;
+  if (subscriptionOptionId) options.subscriptionOptionId = subscriptionOptionId;
+  if (preorder) options.preOrderRequested = true;
 
   const { cart } = await cartApi.addLineItemsToCurrentCart({
     catalogItems: [

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

@@ -10,6 +10,8 @@ import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
 import type {
   Category,
+  Facet,
+  FacetData,
   ProductDetail,
   ProductOption,
   ProductModifier,
@@ -24,11 +26,43 @@ const categories = wixModule(categoriesModule);
 // Requested on every product read. CURRENCY populates formattedAmount (without it, prices render
 // as bare unlocalized numbers); MEDIA_ITEMS_INFO populates the gallery; the detail read adds
 // PLAIN_DESCRIPTION and VARIANT_OPTION_CHOICE_NAMES (which populates variantsInfo.variants).
-const LIST_FIELDS = ["CURRENCY", "MEDIA_ITEMS_INFO"];
-const DETAIL_FIELDS = [...LIST_FIELDS, "PLAIN_DESCRIPTION", "VARIANT_OPTION_CHOICE_NAMES"];
+// MIN_PRICE_VARIANT + DISCOUNT_INFO → variantSummary.minPriceVariant with its discounted price:
+// a card's real price and the direct-add variant id, without a per-product fetch.
+const LIST_FIELDS = ["CURRENCY", "MEDIA_ITEMS_INFO", "MIN_PRICE_VARIANT", "DISCOUNT_INFO"];
+// INFO_SECTION + INFO_SECTION_PLAIN_DESCRIPTION → infoSections[] with HTML bodies.
+const DETAIL_FIELDS = [
+  ...LIST_FIELDS,
+  "PLAIN_DESCRIPTION",
+  "VARIANT_OPTION_CHOICE_NAMES",
+  "INFO_SECTION",
+  "INFO_SECTION_PLAIN_DESCRIPTION",
+];
 
 type RawProduct = Record<string, any>;
 
+/**
+ * The price the buyer pays, and the price to strike — exact precedence, shared by cards and
+ * variants. An automatic discount (priceAfterDiscount, present when DISCOUNT_INFO is requested)
+ * wins and strikes the regular actualPrice; otherwise actualPrice with the merchant's
+ * compareAtPrice as the "was". `!== undefined` on purpose: a discounted price of 0 is a real price.
+ */
+export function sellingPrice(price: RawProduct | undefined): { current?: RawProduct; original?: RawProduct } {
+  if (price?.priceAfterDiscount !== undefined) return { current: price.priceAfterDiscount, original: price.actualPrice };
+  return { current: price?.actualPrice, original: price?.compareAtPrice };
+}
+
+/** The struck price only when it is real and higher than what the buyer pays. */
+function strike(original: RawProduct | undefined, current: RawProduct | undefined): string | null {
+  const o = Number(original?.amount), c = Number(current?.amount);
+  return original?.formattedAmount && Number.isFinite(o) && Number.isFinite(c) && o > c ? original.formattedAmount : null;
+}
+
+/** Every merchant ribbon label, primary first — a ribbon is a label, never proof of a price. */
+function ribbonsOf(raw: RawProduct): string[] {
+  return [raw.ribbon?.name, ...((raw.additionalRibbons ?? []) as RawProduct[]).map((r) => r?.name)]
+    .filter((n, i, all): n is string => typeof n === "string" && n.length > 0 && all.indexOf(n) === i);
+}
+
 function toAvailability(raw: RawProduct): Availability {
   const status = raw.inventory?.availabilityStatus;
   return status === "OUT_OF_STOCK" || status === "PARTIALLY_OUT_OF_STOCK"
@@ -36,13 +70,39 @@ function toAvailability(raw: RawProduct): Availability {
     : "IN_STOCK";
 }
 
+// The identity of a media entry BEFORE scaling — two scaled URLs of one photo differ in their
+// size parameters, so de-duplicating on resolved URLs shows the same image twice.
+function mediaKey(m: RawProduct | undefined): string {
+  const v = m?.image ?? m?.url ?? m;
+  if (!v) return "";
+  if (typeof v === "string") return v.split("#")[0];
+  return v.id ?? v.url ?? "";
+}
+
+// Every distinct media entry, main first, keyed on identity — shared by the tile (hover image)
+// and the PDP (gallery) so both see the same photos in the same order.
+function mediaEntries(raw: RawProduct): RawProduct[] {
+  const out: RawProduct[] = [];
+  const seen = new Set<string>();
+  for (const m of [raw.media?.main, ...((raw.media?.itemsInfo?.items ?? []) as RawProduct[])]) {
+    const k = mediaKey(m);
+    if (!k || seen.has(k)) continue;
+    seen.add(k);
+    out.push(m);
+  }
+  return out;
+}
+
 function toSummary(raw: RawProduct): ProductSummary {
   const options: RawProduct[] = raw.options ?? [];
-  const galleryItems: RawProduct[] = raw.media?.itemsInfo?.items ?? [];
-  const mainUrl = imgSrc(raw.media?.main, 800, 800);
-  const hover = galleryItems
-    .map((m) => imgSrc(m.image ?? m, 800, 800))
-    .filter((u) => u && u !== mainUrl);
+  const media = mediaEntries(raw);
+  const mainUrl = imgSrc(media[0], 800, 800);
+  const hover = media.slice(1).map((m) => imgSrc(m, 800, 800)).filter(Boolean);
+  const swatches = options
+    .filter((o) => o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES")
+    .flatMap((o) => (o.choicesSettings?.choices ?? []) as RawProduct[])
+    .filter((c) => c.visible !== false && c.colorCode)
+    .map((c) => String(c.colorCode));
   const availability = toAvailability(raw);
   const preorder = raw.inventory?.preorderStatus === "ENABLED" && availability === "OUT_OF_STOCK";
   const optionsSummary = options
@@ -51,19 +111,30 @@ function toSummary(raw: RawProduct): ProductSummary {
       return `${visible.length} ${String(o.name ?? "").toLowerCase()}${visible.length === 1 ? "" : "s"}`;
     })
     .join(" · ");
+  // Price: the cheapest variant's selling price (discount applied) via MIN_PRICE_VARIANT; the
+  // product range when variants are priced differently. A struck "was" only for a single price.
+  const min = raw.actualPriceRange?.minValue;
+  const max = raw.actualPriceRange?.maxValue;
+  const isRange = !!(min?.amount && max?.amount && min.amount !== max.amount);
+  const minVariant: RawProduct | undefined = raw.variantSummary?.minPriceVariant;
+  const { current, original } = sellingPrice(minVariant?.price);
+  const ribbons = ribbonsOf(raw);
   return {
     id: raw._id ?? "",
     slug: raw.slug ?? "",
     name: raw.name ?? "",
-    price: raw.actualPriceRange?.minValue?.formattedAmount ?? "",
-    maxPrice: raw.actualPriceRange?.maxValue?.formattedAmount ?? "",
-    compareAtPrice: raw.compareAtPriceRange?.minValue?.formattedAmount ?? null,
-    ribbon: raw.ribbon?.name ?? null,
+    price: current?.formattedAmount ?? min?.formattedAmount ?? "",
+    maxPrice: max?.formattedAmount ?? "",
+    compareAtPrice: isRange ? null : strike(original ?? raw.compareAtPriceRange?.minValue, current ?? min),
+    ribbon: ribbons[0] ?? null,
+    ribbons,
+    minPriceVariantId: minVariant?._id ?? minVariant?.variantId ?? null,
     availability,
     preorder,
     imageUrl: mainUrl,
     hoverImageUrl: hover[0] ?? "",
     optionsSummary,
+    swatches,
     quickAddable: options.length === 0 && availability === "IN_STOCK",
   };
 }
@@ -107,25 +178,29 @@ function toVariants(raw: RawProduct): ProductVariant[] {
       const names = c.optionChoiceNames;
       if (names?.optionName) choices[names.optionName] = names.choiceName ?? "";
     }
+    const { current, original } = sellingPrice(v.price);
     return {
       variantId: v._id ?? v.variantId ?? "",
       choices,
-      price: v.price?.actualPrice?.formattedAmount ?? "",
-      compareAtPrice: v.price?.compareAtPrice?.formattedAmount ?? null,
+      price: current?.formattedAmount ?? "",
+      compareAtPrice: strike(original, current),
       inStock: v.inventoryStatus?.inStock !== false,
+      preorderEnabled: v.inventoryStatus?.preorderEnabled === true,
     };
   });
 }
 
 function toDetail(raw: RawProduct): ProductDetail {
   const summary = toSummary(raw);
-  const gallery = [
-    summary.imageUrl,
-    ...(raw.media?.itemsInfo?.items ?? []).map((m: RawProduct) => imgSrc(m.image ?? m, 1200, 1200)),
-  ].filter((u, i, arr) => u && arr.indexOf(u) === i);
+  // De-duplicated on media identity (mediaEntries), then resolved once at one size — never
+  // "main at 800 + items at 1200", which yields two thumbnails of the same photo.
+  const gallery = mediaEntries(raw).map((m) => imgSrc(m, 1200, 1200)).filter(Boolean);
   return {
     ...summary,
-    descriptionHtml: raw.plainDescription ?? "",
+    descriptionHtml: raw.plainDescription ?? "",   // plainDescription IS an HTML string despite the name
+    infoSections: ((raw.infoSections ?? []) as RawProduct[])
+      .map((s) => ({ title: s.title ?? "", html: s.plainDescription ?? "" }))
+      .filter((s) => s.title || s.html),
     gallery,
     options: toOptions(raw),
     modifiers: toModifiers(raw),
@@ -174,6 +249,8 @@ export interface CatalogSearchOptions {
   inStockOnly?: boolean;
   /** Name search, max 100 chars. */
   search?: string;
+  /** Option-choice facets: products carrying ANY of these choice ids (see fetchFacets). */
+  choiceIds?: string[];
 }
 
 /**
@@ -190,7 +267,8 @@ export async function searchCatalog({
   maxPrice,
   inStockOnly = false,
   search = "",
-}: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null }> {
+  choiceIds = [],
+}: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null; total: number | null }> {
   if (!Number.isInteger(limit) || limit < 1 || limit > 100)
     throw new Error("limit must be between 1 and 100.");
   let query: RawProduct = { cursorPaging: { limit, ...(cursor ? { cursor } : {}) } };
@@ -210,6 +288,8 @@ export async function searchCatalog({
     if (max !== undefined)
       conditions.push({ "actualPriceRange.minValue.amount": { $lte: String(max) } });
     if (inStockOnly) conditions.push({ "inventory.availabilityStatus": { $eq: "IN_STOCK" } });
+    // Facets discover PRODUCTS that carry a choice; the PDP / QuickAdd still resolves the variant.
+    if (choiceIds.length) conditions.push({ "options.choicesSettings.choices.choiceId": { $hasSome: choiceIds } });
     query = {
       ...query,
       filter: { $and: conditions },
@@ -218,12 +298,77 @@ export async function searchCatalog({
     };
   }
   const res: RawProduct = await products.searchProducts(query, { fields: LIST_FIELDS as any });
+  // The result count for the "N products" line — same filter, issued alongside the first page.
+  let total: number | null = null;
+  if (!cursor && query.filter) {
+    try {
+      const count: RawProduct = await products.countProducts({ filter: query.filter });
+      total = typeof count?.count === "number" ? count.count : null;
+    } catch {
+      /* the count is a nicety — the page is still valid */
+    }
+  }
   return {
     products: (res.products ?? []).map((p: RawProduct) => toSummary(p)),
     nextCursor: res.pagingMetadata?.cursors?.next ?? null,
+    total,
   };
 }
 
+/**
+ * The filterable options of the catalog (or of one category): every option name with its
+ * choices, aggregated from the products themselves — so the panel only offers facets that
+ * exist. Color options carry a colorCode for swatches. Non-fatal: [] when the read fails.
+ */
+export async function fetchFacets(scope: { categoryId?: string | null } = {}): Promise<Facet[]> {
+  return (await fetchFacetData(scope)).facets;
+}
+
+/**
+ * Facets plus the scope's price bounds (lowest minimum, highest maximum across its products) — the
+ * filter panel's slider needs both, from one 100-product read. Non-fatal: empty facets and a null
+ * range when the read fails.
+ */
+export async function fetchFacetData({ categoryId }: { categoryId?: string | null } = {}): Promise<FacetData> {
+  try {
+    const conditions: RawProduct[] = [{ visible: true }];
+    if (categoryId) conditions.push({ "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] } });
+    const res: RawProduct = await products.searchProducts(
+      { filter: { $and: conditions }, cursorPaging: { limit: 100 } },
+      { fields: [] as any },
+    );
+    const byName = new Map<string, Facet>();
+    let lo = Infinity;
+    let hi = -Infinity;
+    let currency = "";
+    for (const p of (res.products ?? []) as RawProduct[]) {
+      const min = Number(p.actualPriceRange?.minValue?.amount);
+      const max = Number(p.actualPriceRange?.maxValue?.amount);
+      if (Number.isFinite(min)) lo = Math.min(lo, min);
+      if (Number.isFinite(max)) hi = Math.max(hi, max);
+      currency = currency || p.currency || "";
+      for (const o of (p.options ?? []) as RawProduct[]) {
+        const name = o.name ?? "";
+        if (!name) continue;
+        const isColor = o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES";
+        const facet: Facet = byName.get(name) ?? { name, isColor, choices: [] };
+        for (const ch of (o.choicesSettings?.choices ?? []) as RawProduct[]) {
+          if (ch.visible === false || !ch.choiceId) continue;
+          if (!facet.choices.some((x) => x.id === ch.choiceId))
+            facet.choices.push({ id: ch.choiceId, name: ch.name ?? "", colorCode: ch.colorCode ?? null });
+        }
+        byName.set(name, facet);
+      }
+    }
+    return {
+      facets: [...byName.values()].filter((f) => f.choices.length > 1),
+      priceRange: Number.isFinite(lo) && Number.isFinite(hi) && hi > lo ? { min: Math.floor(lo), max: Math.ceil(hi), currency } : null,
+    };
+  } catch {
+    return { facets: [], priceRange: null };
+  }
+}
+
 /** First page of visible products in the default order — a thin wrap of searchCatalog. */
 export async function fetchProducts({ limit = 24 } = {}): Promise<ProductSummary[]> {
   return (await searchCatalog({ limit })).products;
@@ -260,17 +405,38 @@ export async function fetchCategories(): Promise<Category[]> {
       .exists("name", true)
       .find();
     return (res.items ?? [])
-      .map((c) => ({
-        id: (c as RawProduct)._id ?? "",
-        slug: (c as RawProduct).slug ?? "",
-        name: (c as RawProduct).name ?? "",
-      }))
+      .map((c) => toCategory(c as RawProduct))
       .filter((c) => c.slug !== "all-products");
   } catch {
     return [];
   }
 }
 
+function toCategory(raw: RawProduct): Category {
+  return {
+    id: raw._id ?? raw.id ?? "",
+    slug: raw.slug ?? "",
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+  };
+}
+
+/**
+ * One category by its URL slug — the data a /category/[slug] page needs (its id feeds
+ * searchCatalog / useShop, its name and description head the page). Null when not found or
+ * hidden, which the page turns into a real 404 — never a fallback to all products.
+ */
+export async function fetchCategoryBySlug(slug: string): Promise<Category | null> {
+  try {
+    const res: RawProduct = await categories.getCategoryBySlug(slug, { appNamespace: "@wix/stores" } as any);
+    const raw: RawProduct | undefined = res?.category;
+    if (!raw || raw.visible === false) return null;
+    return toCategory(raw);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Resolve the variant for the buyer's selections (optionName -> choiceName).
  * A product with no options resolves to its single variant; with options, every option