@wix/agent-skills 1.20.0 → 1.21.0

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

@@ -1,173 +1,39 @@
-// Product detail state: option selection → variant resolution → add-to-cart, plus modifier
-// inputs. This is the logic the turtle-run class of bugs comes from (adding variants[0]
-// regardless of the buyer's choice) — always drive a PDP through this hook.
+// React binding of the product-detail store (wix/storefront/product-detail-store.ts) — option
+// selection → variant resolution → add-to-cart lives there, framework-free. Always drive a PDP or
+// quick-add picker through this hook (or the store): resolving variants by hand is where
+// "added variants[0] regardless of the buyer's choice" comes from.
 //
-// SSR-friendly: pass the server-fetched ProductDetail as `initial` (Astro/Next); in a SPA
-// pass the slug and it fetches on mount.
-import { useEffect, useMemo, useState } from "react";
-import { fetchProductBySlug, resolveVariant } from "../../wix/storefront/catalog";
-import type { ProductDetail, ProductOption, ProductVariant } from "../../wix/storefront/types";
-import { useCart } from "./useCart";
+// SSR-friendly: pass the server-fetched ProductDetail as `initial` (Astro/Next); in a SPA pass
+// the slug and it fetches on mount.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createProductDetailStore,
+  type ProductDetailState,
+  type ProductDetailStore,
+  type ProductDetailStoreOptions,
+} from "../../wix/storefront/product-detail-store";
 
-export interface UseProductDetailOptions {
-  initial?: ProductDetail | null;
-  slug?: string;
-}
+export { type OptionGroupView } from "../../wix/storefront/product-detail-store";
 
-export interface OptionGroupView extends ProductOption {
-  choices: (ProductOption["choices"][number] & { selected: boolean })[];
-}
+export type UseProductDetailOptions = ProductDetailStoreOptions;
 
-export interface UseProductDetail {
-  /** null while loading (or when the slug doesn't resolve — check notFound). */
-  product: ProductDetail | null;
-  notFound: boolean;
-  /** Option groups with per-choice `selected`, ready to render as pills/swatches. */
-  optionGroups: OptionGroupView[];
-  selectOption: (optionName: string, choiceName: string) => void;
-  /** Modifier inputs keyed by modifier key. */
-  modifierValues: Record<string, string>;
-  setModifier: (key: string, value: string) => void;
-  /** The resolved variant; null while the selection is incomplete. */
-  variant: ProductVariant | null;
-  /**
-   * Price to display right now: the product RANGE ("€24.99 – €34.99", one value when equal) until
-   * every option is picked, then the selected variant's price (an automatic discount applied).
-   */
-  price: string;
-  /** Struck "was" price — only once a variant is resolved (or for a single-price product), never beside a range. */
-  compareAtPrice: string | null;
-  /** The resolved variant is out of stock but pre-orderable — label the action "Pre-order". */
-  isPreorder: boolean;
-  /** False until every option is selected and the resolved variant is in stock or pre-orderable. */
-  canAdd: boolean;
-  /**
-   * Why the action is disabled — neutral guidance to render beside it ("Choose Size"), not an
-   * error; null when the buyer can add. Promote to error styling only after they try to buy.
-   */
-  blockedReason: string | null;
-  quantity: number;
-  setQuantity: (n: number) => void;
-  /** Adds the resolved variant to the cart (opens the drawer). Throws on refusal. */
-  add: () => Promise<void>;
-  adding: boolean;
-  error: string | null;
-}
+export type UseProductDetail = ProductDetailState &
+  Pick<ProductDetailStore, "selectOption" | "setModifier" | "setQuantity" | "add">;
 
 export function useProductDetail({ initial, slug }: UseProductDetailOptions): UseProductDetail {
-  const [product, setProduct] = useState<ProductDetail | null>(initial ?? null);
-  const [notFound, setNotFound] = useState(false);
-  const [selections, setSelections] = useState<Record<string, string>>({});
-  const [modifierValues, setModifierValues] = useState<Record<string, string>>({});
-  const [quantity, setQuantity] = useState(1);
-  const [adding, setAdding] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const { addToCart } = useCart();
-
+  const ref = useRef<{ slug?: string; store: ProductDetailStore } | null>(null);
+  if (!ref.current || ref.current.slug !== slug) ref.current = { slug, store: createProductDetailStore({ initial, slug }) };
+  const store = ref.current.store;
   useEffect(() => {
-    if (initial || !slug) return;
-    let alive = true;
-    fetchProductBySlug(slug)
-      .then((p) => {
-        if (!alive) return;
-        setProduct(p);
-        setNotFound(p === null);
-      })
-      .catch(() => alive && setNotFound(true));
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [slug]);
-
-  const variant = useMemo(
-    () => (product ? resolveVariant(product, selections) : null),
-    [product, selections],
-  );
-
-  const optionGroups: OptionGroupView[] = useMemo(
-    () =>
-      (product?.options ?? []).map((o) => ({
-        ...o,
-        choices: o.choices.map((c) => ({ ...c, selected: selections[o.name] === c.name })),
-      })),
-    [product, selections],
-  );
-
-  const missingModifier = (product?.modifiers ?? []).find(
-    (m) => m.mandatory && (modifierValues[m.key] ?? "").length === 0,
-  );
-  const missingOptions = (product?.options ?? []).filter((o) => !selections[o.name]).map((o) => o.name);
-  const selectionComplete = missingOptions.length === 0;
-
-  // In stock OR pre-orderable counts as buyable; a preorder add carries preOrderRequested.
-  const isPreorder = !!variant && !variant.inStock && variant.preorderEnabled;
-  const available = !!variant && (variant.inStock || variant.preorderEnabled);
-
-  const canAdd = !!product && available && !missingModifier;
-
-  const blockedReason: string | null = !product
-    ? null
-    : !selectionComplete
-      ? `Choose ${missingOptions.join(" and ")}`
-      : !variant
-        ? "This combination isn't available"
-        : !available
-          ? "Out of stock"
-          : missingModifier
-            ? `Add ${missingModifier.name}`
-            : null;
-
-  // Before every option is picked, the range — never an empty price, never a lone struck minimum.
-  const isRange = !!product && product.price !== product.maxPrice && !!product.maxPrice;
-  const rangeDisplay = product ? (isRange ? `${product.price} – ${product.maxPrice}` : product.price) : "";
-
-  async function add(): Promise<void> {
-    if (!product || !variant) return;
-    setAdding(true);
-    setError(null);
-    try {
-      const choiceModifiers: Record<string, string> = {};
-      const textModifiers: Record<string, string> = {};
-      for (const m of product.modifiers) {
-        const value = modifierValues[m.key];
-        if (!value) continue;
-        if (m.type === "text") textModifiers[m.key] = value;
-        else choiceModifiers[m.key] = value;
-      }
-      await addToCart(product.id, variant.variantId, quantity, {
-        modifierChoices: choiceModifiers,
-        customTextFields: textModifiers,
-        preorder: isPreorder,
-      });
-    } catch (e) {
-      setError(e instanceof Error ? e.message : String(e));
-      throw e;
-    } finally {
-      setAdding(false);
-    }
-  }
-
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
   return {
-    product,
-    notFound,
-    optionGroups,
-    selectOption: (optionName, choiceName) => {
-      setSelections((s) => ({ ...s, [optionName]: choiceName }));
-      setQuantity(1); // the ceiling belongs to the newly resolved variant
-    },
-    modifierValues,
-    setModifier: (key, value) => setModifierValues((v) => ({ ...v, [key]: value })),
-    variant,
-    price: variant?.price || rangeDisplay,
-    compareAtPrice: variant ? variant.compareAtPrice : isRange ? null : (product?.compareAtPrice ?? null),
-    isPreorder,
-    canAdd,
-    blockedReason,
-    quantity,
-    setQuantity,
-    add,
-    adding,
-    error,
+    ...state,
+    selectOption: store.selectOption,
+    setModifier: store.setModifier,
+    setQuantity: store.setQuantity,
+    add: store.add,
   };
 }

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

@@ -1,308 +1,34 @@
-// 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. 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, Facet, PriceRange, ProductSummary } from "../../wix/storefront/types";
+// React binding of the shop store (wix/storefront/shop-store.ts) — the listing state machine
+// lives there, framework-free; this hook subscribes to one instance per mounted listing and
+// exposes its state and actions under one name. Astro islands and React SPAs use this; a static
+// page, Vue, or Svelte uses the store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createShopStore, type ShopState, type ShopStore, type ShopStoreOptions } from "../../wix/storefront/shop-store";
 
-export const SORTS = CATALOG_SORTS;
+export { SORTS, type ShopFilters } from "../../wix/storefront/shop-store";
 
-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[];
-  /** 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;
-  setActiveCategoryId: (id: string | null) => void;
-  sort: CatalogSort;
-  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;
-  hasMore: boolean;
-  loadMore: () => Promise<void>;
-  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;
-}
+export type UseShopOptions = ShopStoreOptions;
 
-export function useShop({
-  initialProducts,
-  initialCategories,
-  initialCategoryId = null,
-  pageSize = 24,
-}: UseShopOptions = {}): UseShop {
-  const [categories, setCategories] = useState<Category[]>(initialCategories ?? []);
-  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);
+export type UseShop = ShopState &
+  Pick<ShopStore, "setActiveCategoryId" | "setSort" | "setFilters" | "toggleChoice" | "clearFilters" | "retry" | "loadMore">;
 
-  // Adopt the URL's selection once, after hydration (the server rendered the defaults).
+export function useShop(options: UseShopOptions = {}): UseShop {
+  const ref = useRef<ShopStore | null>(null);
+  if (!ref.current) ref.current = createShopStore(options);
+  const store = ref.current;
   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,
-    activeCategoryId,
-    sort,
-    filters.minPrice ?? null,
-    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;
-    fetchCategories().then((list) => alive && setCategories(list)).catch(() => alive && setCategories([]));
-    return () => {
-      alive = false;
-    };
-    // 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, 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, total: res.total, cursor: res.nextCursor, error: null, loadingMore: false });
-        }
-      })
-      .catch((e) => {
-        if (alive && generation.current === id && currentKey.current === key) {
-          setPage({
-            key,
-            products: [],
-            total: null,
-            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
-  }, [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), []);
-  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());
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
   return {
-    products: current || seeded ? page.products : null,
-    total: current ? page.total : null,
-    categories,
-    activeCategoryId,
-    setActiveCategoryId,
-    sort,
-    setSort,
-    filters,
-    setFilters,
-    facets,
-    priceRange,
-    selectedChoiceIds,
-    toggleChoice,
-    clearFilters,
-    hasActiveFilters,
-    loading,
-    error: current ? page.error : null,
-    retry,
-    hasMore: current && !!page.cursor,
-    loadMore,
-    loadingMore: current && page.loadingMore,
+    ...state,
+    setActiveCategoryId: store.setActiveCategoryId,
+    setSort: store.setSort,
+    setFilters: store.setFilters,
+    toggleChoice: store.toggleChoice,
+    clearFilters: store.clearFilters,
+    retry: store.retry,
+    loadMore: store.loadMore,
   };
 }

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

@@ -0,0 +1,121 @@
+// Cart rules and DTO mapping — transport-agnostic, imported by both ./cart.ts (SDK) and the REST
+// twin in references/storefront/rest/cart.ts (fetch). Raw Cart V2 entities may carry `_id` (SDK)
+// or `id` (REST). Has its own formatMoney (a copy of ../money.ts) so it stands alone when stripped.
+import type { Cart, CartLine } from "./types";
+import type { ImgSrc, Raw } from "./catalog-core";
+
+/** Public app id of the Wix Stores catalog — required inside every catalogReference. */
+export const WIX_STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+/**
+ * Cart V2 money is ConvertedMoney { amount, convertedAmount } with NO formatted string, and the
+ * currency lives on the cart, not on the money. Format with the buyer's display currency when
+ * present, else the site's. Never hardcode "$" or assume USD.
+ */
+export function formatMoney(money: Raw | null | undefined, currencyCode: string | null | undefined): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}
+
+export const cartCurrency = (raw: Raw | null | undefined): string =>
+  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. Every word comes from the plan — a
+ * subscription line must read as one in the cart, never a generic "recurring".
+ */
+export function subscriptionTerms(info: Raw | undefined): string {
+  if (!info) return "";
+  const s: Raw = 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(" · ");
+}
+
+export function toLine(raw: Raw, currency: string, imgSrc: ImgSrc): CartLine {
+  return {
+    lineItemId: rawId(raw), // the LINE id — what update/remove take, never the product id
+    productName: raw.name?.original ?? "",
+    quantity: raw.quantityInfo?.confirmedQuantity ?? 0,
+    unitPrice: formatMoney(raw.pricing?.unitPrice, currency),
+    linePrice: formatMoney(raw.pricing?.totalPrice, currency),
+    imageUrl: imgSrc(raw.attributes?.image, 300, 300),
+    descriptionLines: ((raw.attributes?.descriptionLines ?? []) as Raw[])
+      .map((d) => {
+        const label = d.name?.original ?? "", value = d.plainText?.original ?? d.colorInfo?.original ?? "";
+        return label && value ? `${label}: ${value}` : value || label;
+      })
+      .filter(Boolean),
+    status: raw.status ?? "IN_STOCK", // not IN_STOCK → the line can't be checked out as-is
+    subscription: subscriptionTerms(raw.subscriptionInfo),
+  };
+}
+
+export function toCart(raw: Raw | null, subtotal: string, discount: string, imgSrc: ImgSrc): Cart {
+  const currency = cartCurrency(raw);
+  const lines = ((raw?.lineItems ?? []) as Raw[]).map((l) => toLine(l, currency, imgSrc));
+  return { lines, itemCount: lines.reduce((n, l) => n + l.quantity, 0), subtotal, discount, currency };
+}
+
+/** The after-discount subtotal and the CART-level discount from an estimate; "" when unknown. */
+export function summaryTotals(estimate: Raw | null | undefined, raw: Raw): { subtotal: string; discount: string } {
+  const s = estimate?.summary?.priceSummary;
+  const currency = cartCurrency(raw);
+  const d = s?.discount;
+  return {
+    subtotal: formatMoney(s?.subtotal, currency),
+    discount: Number(d?.convertedAmount ?? d?.amount ?? 0) > 0 ? formatMoney(d, currency) : "",
+  };
+}
+
+/** The catalogReference.options object for an add — omits every key the buyer didn't use. */
+export function addOptions({ variantId, modifierChoices, customTextFields, subscriptionOptionId, preorder }: {
+  variantId?: string | null; modifierChoices?: Record<string, string>; customTextFields?: Record<string, string>;
+  subscriptionOptionId?: string; preorder?: boolean;
+}): Raw {
+  const o: Raw = {};
+  if (variantId) o.variantId = variantId;                                            // REQUIRED for any product with options
+  if (modifierChoices && Object.keys(modifierChoices).length) o.options = modifierChoices; // MODIFIERS only, never Size/Color
+  if (customTextFields && Object.keys(customTextFields).length) o.customTextFields = customTextFields;
+  if (subscriptionOptionId) o.subscriptionOptionId = subscriptionOptionId;
+  if (preorder) o.preOrderRequested = true;
+  return o;
+}
+
+/** Read the add result — a refused add still returns 200: a line whose status isn't IN_STOCK, or no line, is a refusal. */
+export function assertAdded(cart: Raw | null | undefined, productId: string, variantId?: string | null): void {
+  const line = ((cart?.lineItems ?? []) as Raw[]).find(
+    (l) => l.source?.catalogReference?.catalogItemId === productId && (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
+  );
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`This item isn't available right now (${String(line.status).toLowerCase().replace(/_/g, " ")}).`);
+  }
+  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
+    throw new Error("The item couldn't be added. Make sure every required selection was made (options for a product with variants, and all mandatory customizations).");
+  }
+}
+
+/** Refuse checkout for an empty cart or any line not IN_STOCK — say which. */
+export function assertCheckoutable(raw: Raw | null): void {
+  const lines: Raw[] = raw?.lineItems ?? [];
+  if (!lines.length) throw new Error("Your cart is empty.");
+  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
+  if (unavailable.length) {
+    throw new Error(`Some items are no longer available: ${unavailable.map((l) => l.name?.original).filter(Boolean).join(", ")}.`);
+  }
+  if (!rawId(raw)) throw new Error("Checkout couldn't start: the cart has no id.");
+}