@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -1,309 +0,0 @@
-// Catalog rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./catalog.ts
-// (the SDK, managed Astro and React) and the REST twin in references/storefront/rest/catalog.ts
-// (fetch, a static site or a port to another language). Every rule about prices, ribbons,
-// ranges, media, variants lives HERE, once. A raw entity may come from the SDK (`_id`) or from
-// REST (`id`); the mappers accept both. Imports are type-only so a strip to JS emits no imports.
-import type {
-  Availability,
-  Category,
-  Facet,
-  FacetData,
-  ProductDetail,
-  ProductModifier,
-  ProductOption,
-  ProductSummary,
-  ProductVariant,
-} from "./types";
-
-/** A raw Catalog V3 entity as either transport returns it. */
-export type Raw = Record<string, any>;
-/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
-export type ImgSrc = (value: any, width: number, height: number) => string;
-/** Media identity before scaling — de-duplicate on this, never on a resolved URL. */
-export type MediaKey = (value: any) => string;
-
-const id = (raw: Raw | undefined): string => raw?._id ?? raw?.id ?? "";
-
-// Requested on every product read. CURRENCY → formattedAmount (without it prices render as bare
-// numbers); MEDIA_ITEMS_INFO → the gallery; MIN_PRICE_VARIANT + DISCOUNT_INFO → the cheapest variant
-// with its discounted price: a card's real price and the direct-add variant id, no per-product fetch.
-export const LIST_FIELDS = ["CURRENCY", "MEDIA_ITEMS_INFO", "MIN_PRICE_VARIANT", "DISCOUNT_INFO"] as const;
-// The detail read adds the HTML description, the variants (VARIANT_OPTION_CHOICE_NAMES — without it
-// variantsInfo is null), and the info sections with HTML bodies.
-export const DETAIL_FIELDS = [
-  ...LIST_FIELDS,
-  "PLAIN_DESCRIPTION",
-  "VARIANT_OPTION_CHOICE_NAMES",
-  "INFO_SECTION",
-  "INFO_SECTION_PLAIN_DESCRIPTION",
-] as const;
-
-// ---- sort + filter ---------------------------------------------------------------------------------
-
-export const CATALOG_SORTS = {
-  featured: { label: "Default order" }, // the catalog's own order — no sort sent, and NOT a sales ranking
-  priceAsc: { label: "Price: low to high" },
-  priceHigh: { label: "Price: high to low" },
-  name: { label: "Name: A–Z" },
-  newest: { label: "Newest" },
-} as const;
-export type CatalogSort = keyof typeof CATALOG_SORTS;
-
-export const SORT_FIELDS: Partial<Record<CatalogSort, { fieldName: string; order: "ASC" | "DESC" }[]>> = {
-  priceAsc: [{ fieldName: "actualPriceRange.minValue.amount", order: "ASC" }, { fieldName: "name", order: "ASC" }],
-  priceHigh: [{ fieldName: "actualPriceRange.minValue.amount", order: "DESC" }, { fieldName: "name", order: "ASC" }],
-  name: [{ fieldName: "name", order: "ASC" }],
-  newest: [{ fieldName: "createdDate", order: "DESC" }, { fieldName: "name", order: "ASC" }],
-};
-
-export interface CatalogSearchOptions {
-  /** 1–100, default 24. */
-  limit?: number;
-  /** Continues the ORIGINAL query — send it alone; any change of selection starts over without one. */
-  cursor?: string | null;
-  categoryId?: string | null;
-  sort?: CatalogSort;
-  /** Inclusive bounds on the product's minimum actual variant price, site currency. */
-  minPrice?: number | string;
-  maxPrice?: number | string;
-  /** IN_STOCK only — excludes partially stocked and preorder-only products. */
-  inStockOnly?: boolean;
-  /** Name search, max 100 chars. */
-  search?: string;
-  /** Option-choice facets: products carrying ANY of these choice ids (see fetchFacetData). */
-  choiceIds?: string[];
-}
-
-export function priceBound(value: number | string | undefined, name: string): number | undefined {
-  if (value == null || value === "") return undefined;
-  const n = Number(value);
-  if (!Number.isFinite(n) || n < 0) throw new Error(`${name} must be a non-negative number.`);
-  return n;
-}
-
-/**
- * The filter every catalog read shares (the page, its count, the facets) — one place, so they
- * can't drift. Search rejects two operators in ONE field object: price bounds are separate
- * conditions joined by $and. Category: `allCategoriesInfo.categories` with `$matchItems` on the
- * id (includes parent categories); never `$hasSome`, never V1 `collectionIds`. Facets discover
- * PRODUCTS carrying a choice; the picker / PDP still resolves the variant.
- */
-export function catalogFilter({ categoryId, minPrice, maxPrice, inStockOnly = false, choiceIds = [] }: CatalogSearchOptions = {}): Raw {
-  const min = priceBound(minPrice, "minPrice"), max = priceBound(maxPrice, "maxPrice");
-  if (min !== undefined && max !== undefined && min > max) throw new Error("minPrice must not exceed maxPrice.");
-  const and: Raw[] = [{ visible: true }];
-  if (categoryId) and.push({ "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] } });
-  if (min !== undefined) and.push({ "actualPriceRange.minValue.amount": { $gte: String(min) } });
-  if (max !== undefined) and.push({ "actualPriceRange.minValue.amount": { $lte: String(max) } });
-  if (inStockOnly) and.push({ "inventory.availabilityStatus": { $eq: "IN_STOCK" } });
-  if (choiceIds.length) and.push({ "options.choicesSettings.choices.choiceId": { $hasSome: choiceIds } });
-  return { $and: and };
-}
-
-/** The full Search Products body (minus fields) for a page; a cursor request carries ONLY cursorPaging. */
-export function searchQuery(o: CatalogSearchOptions): Raw {
-  const { limit = 24, cursor, sort = "featured", search = "" } = o;
-  if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error("limit must be between 1 and 100.");
-  const paging = { cursorPaging: { limit, ...(cursor ? { cursor } : {}) } };
-  if (cursor) return paging;
-  if (!(sort in CATALOG_SORTS)) throw new Error("Unsupported catalog sort.");
-  if (search.trim().length > 100) throw new Error("Search must be at most 100 characters.");
-  return {
-    ...paging,
-    filter: catalogFilter(o),
-    ...(SORT_FIELDS[sort] ? { sort: SORT_FIELDS[sort] } : {}),
-    ...(search.trim() ? { search: { expression: search.trim(), fields: ["name"] } } : {}),
-  };
-}
-
-// ---- price rules ----------------------------------------------------------------------------------
-
-/**
- * The price the buyer pays and the price to strike — exact precedence, shared by cards and
- * variants. An automatic discount (priceAfterDiscount) wins and strikes the regular actualPrice;
- * else 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: Raw | undefined): { current?: Raw; original?: Raw } {
-  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. */
-export function strike(original: Raw | undefined, current: Raw | 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, primary first, de-duplicated. A ribbon is a label, never proof of a price. */
-export function ribbonsOf(raw: Raw): string[] {
-  return [raw.ribbon?.name, ...((raw.additionalRibbons ?? []) as Raw[]).map((r) => r?.name)]
-    .filter((n, i, all): n is string => typeof n === "string" && n.length > 0 && all.indexOf(n) === i);
-}
-
-export function toAvailability(raw: Raw): Availability {
-  const s = raw.inventory?.availabilityStatus;
-  return s === "OUT_OF_STOCK" || s === "PARTIALLY_OUT_OF_STOCK" ? s : "IN_STOCK";
-}
-
-/**
- * Every distinct media entry, main first, keyed on identity — two scaled URLs of one photo are
- * ONE entry (the "two thumbnails for the same image" bug). Shared by the tile and the PDP.
- */
-export function mediaEntries(raw: Raw, mediaKey: MediaKey): unknown[] {
-  const out: unknown[] = [];
-  const seen = new Set<string>();
-  for (const m of [raw.media?.main, ...((raw.media?.itemsInfo?.items ?? []) as Raw[])]) {
-    const v = m?.image ?? m;
-    const k = mediaKey(v);
-    if (!k || seen.has(k)) continue;
-    seen.add(k);
-    out.push(v);
-  }
-  return out;
-}
-
-// ---- DTO mappers -----------------------------------------------------------------------------------
-
-export function toSummary(raw: Raw, imgSrc: ImgSrc, mediaKey: MediaKey): ProductSummary {
-  const options: Raw[] = raw.options ?? [];
-  const media = mediaEntries(raw, mediaKey);
-  const mainUrl = imgSrc(media[0], 800, 800);
-  const hover = media.slice(1).map((m) => imgSrc(m, 800, 800)).filter(Boolean);
-  const availability = toAvailability(raw);
-  // Price: the cheapest variant's selling price (discount applied); the product RANGE when variants
-  // are priced differently — and NO struck price beside a range (a lone struck minimum claims a
-  // saving that may not apply to the variant picked).
-  const min = raw.actualPriceRange?.minValue, max = raw.actualPriceRange?.maxValue;
-  const isRange = !!(min?.amount && max?.amount && min.amount !== max.amount);
-  const minVariant: Raw | undefined = raw.variantSummary?.minPriceVariant;
-  const { current, original } = sellingPrice(minVariant?.price);
-  const ribbons = ribbonsOf(raw);
-  return {
-    id: id(raw),
-    slug: raw.slug ?? "",
-    name: raw.name ?? "",
-    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) || minVariant.variantId || null : null,
-    availability,
-    // Out of stock but pre-orderable — label "Pre-order", not "Sold out".
-    preorder: raw.inventory?.preorderStatus === "ENABLED" && availability === "OUT_OF_STOCK",
-    imageUrl: mainUrl,
-    hoverImageUrl: hover[0] ?? "",
-    optionsSummary: options
-      .map((o) => {
-        const n = ((o.choicesSettings?.choices ?? []) as Raw[]).filter((c) => c.visible !== false).length;
-        return `${n} ${String(o.name ?? "").toLowerCase()}${n === 1 ? "" : "s"}`;
-      })
-      .join(" · "),
-    swatches: options
-      .filter((o) => o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES")
-      .flatMap((o) => (o.choicesSettings?.choices ?? []) as Raw[])
-      .filter((c) => c.visible !== false && c.colorCode)
-      .map((c) => String(c.colorCode)),
-    // Addable in one click: no options and plainly in stock.
-    quickAddable: options.length === 0 && availability === "IN_STOCK",
-  };
-}
-
-export function toOptions(raw: Raw): ProductOption[] {
-  return ((raw.options ?? []) as Raw[]).map((o) => ({
-    id: id(o) || o.name || "",
-    name: o.name ?? "",
-    isColor: o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES",
-    choices: ((o.choicesSettings?.choices ?? []) as Raw[])
-      .filter((c) => c.visible !== false) // a retired choice the merchant no longer sells
-      .map((c) => ({ choiceId: c.choiceId ?? "", name: c.name ?? "", colorCode: c.colorCode ?? null, inStock: c.inStock !== false })),
-  }));
-}
-
-export function toModifiers(raw: Raw): ProductModifier[] {
-  return ((raw.modifiers ?? []) as Raw[]).map((m) => ({
-    key: m.key ?? m.freeTextSettings?.key ?? m.name ?? "",
-    name: m.name ?? "",
-    mandatory: m.mandatory === true,
-    type: m.modifierRenderType === "FREE_TEXT" ? ("text" as const) : ("choices" as const),
-    choices: ((m.choicesSettings?.choices ?? []) as Raw[]).map((c) => ({ key: c.key ?? c.name ?? "", name: c.name ?? "" })),
-  }));
-}
-
-/** Variants keyed by optionName → choiceName. Buyable when in stock OR pre-orderable. */
-export function toVariants(raw: Raw): ProductVariant[] {
-  return ((raw.variantsInfo?.variants ?? []) as Raw[])
-    .filter((v) => v.visible !== false)
-    .map((v) => {
-      const choices: Record<string, string> = {};
-      for (const c of (v.choices ?? []) as Raw[]) {
-        const on = c.optionChoiceNames?.optionName, cn = c.optionChoiceNames?.choiceName;
-        if (on && cn) choices[on] = cn;
-      }
-      const { current, original } = sellingPrice(v.price);
-      return {
-        variantId: id(v),
-        choices,
-        price: current?.formattedAmount ?? "",
-        compareAtPrice: strike(original, current),
-        inStock: v.inventoryStatus?.inStock !== false,
-        preorderEnabled: v.inventoryStatus?.preorderEnabled === true,
-      };
-    });
-}
-
-export function toDetail(raw: Raw, imgSrc: ImgSrc, mediaKey: MediaKey): ProductDetail {
-  return {
-    ...toSummary(raw, imgSrc, mediaKey),
-    descriptionHtml: raw.plainDescription ?? "", // an HTML string despite the name — render as HTML
-    infoSections: ((raw.infoSections ?? []) as Raw[])
-      .map((s) => ({ title: s.title ?? "", html: s.plainDescription ?? "" }))
-      .filter((s) => s.title || s.html),
-    // De-duplicated on media identity, then resolved once at one size.
-    gallery: mediaEntries(raw, mediaKey).map((m) => imgSrc(m, 1200, 1200)).filter(Boolean),
-    options: toOptions(raw),
-    modifiers: toModifiers(raw),
-    variants: toVariants(raw),
-  };
-}
-
-export function toCategory(raw: Raw): Category {
-  return { id: id(raw), slug: raw.slug ?? "", name: raw.name ?? "", description: raw.description ?? "" };
-}
-
-/** Facets + price bounds from a scope's products (the 100-product read), so the panel only offers filters that exist. */
-export function toFacetData(products: Raw[]): FacetData {
-  const byName = new Map<string, Facet>();
-  let lo = Infinity, hi = -Infinity, currency = "";
-  for (const p of products) {
-    const min = Number(p.actualPriceRange?.minValue?.amount), 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 Raw[]) {
-      if (!o.name) continue;
-      const facet: Facet = byName.get(o.name) ?? { name: o.name, isColor: o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES", choices: [] };
-      for (const c of (o.choicesSettings?.choices ?? []) as Raw[]) {
-        if (c.visible === false || !c.choiceId) continue;
-        if (!facet.choices.some((x) => x.id === c.choiceId)) facet.choices.push({ id: c.choiceId, name: c.name ?? "", colorCode: c.colorCode ?? null });
-      }
-      byName.set(o.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,
-  };
-}
-
-/**
- * Resolve the variant for the buyer's selections (optionName → choiceName). A product with no
- * options resolves to its single variant; with options every option must be selected and match.
- * null while incomplete. Selections start EMPTY — never pre-pick a first choice.
- */
-export function resolveVariant(detail: ProductDetail, selections: Record<string, string>): ProductVariant | null {
-  if (detail.options.length === 0) return detail.variants[0] ?? null;
-  if (!detail.options.every((o) => selections[o.name])) return null;
-  return detail.variants.find((v) => detail.options.every((o) => v.choices[o.name] === selections[o.name])) ?? null;
-}

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

@@ -1,133 +0,0 @@
-// Catalog reads (Wix Stores Catalog V3) over the SDK — the only file that touches raw catalog
-// entities on this transport. Everything it returns is a plain DTO from ./types. The rules and
-// mappers live in ./catalog-core (shared with the REST twin in references/storefront/rest/); this
-// file is the transport only. Copy as-is; extend by adding functions, not by editing these.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product-by-slug.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/query-categories.md
-import { productsV3 } from "@wix/stores";
-import { categories as categoriesModule } from "@wix/categories";
-import { wixModule } from "../sdk";
-import { imgSrc, mediaKey } from "../media";
-import {
-  CATALOG_SORTS,
-  DETAIL_FIELDS,
-  LIST_FIELDS,
-  catalogFilter,
-  resolveVariant,
-  searchQuery,
-  sellingPrice,
-  toCategory,
-  toDetail,
-  toFacetData,
-  toSummary,
-  type CatalogSearchOptions,
-  type CatalogSort,
-  type Raw,
-} from "./catalog-core";
-import type { Category, Facet, FacetData, ProductDetail, ProductSummary } from "./types";
-
-export { CATALOG_SORTS, resolveVariant, sellingPrice, type CatalogSearchOptions, type CatalogSort };
-
-const products = wixModule(productsV3);
-const categories = wixModule(categoriesModule);
-
-/**
- * Search visible catalog products — sorted, filtered, faceted, and searched by Wix across the
- * whole catalog, then cursor-paged. `nextCursor` continues the same query; start over (no cursor)
- * whenever any selection changes. `total` (the "N products" line) is issued with the first page.
- */
-export async function searchCatalog(o: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null; total: number | null }> {
-  const query = searchQuery(o);
-  const res: Raw = await products.searchProducts(query, { fields: LIST_FIELDS as any });
-  let total: number | null = null;
-  if (!o.cursor && query.filter) {
-    try {
-      const count: Raw = 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 ?? []) as Raw[]).map((p) => toSummary(p, imgSrc, mediaKey)),
-    nextCursor: res.pagingMetadata?.cursors?.next ?? null,
-    total,
-  };
-}
-
-/** The filterable options of the catalog (or one category). 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 on failure.
- */
-export async function fetchFacetData({ categoryId }: { categoryId?: string | null } = {}): Promise<FacetData> {
-  try {
-    const res: Raw = await products.searchProducts(
-      { filter: catalogFilter({ categoryId }), cursorPaging: { limit: 100 } },
-      { fields: ["CURRENCY"] as any },
-    );
-    return toFacetData((res.products ?? []) as Raw[]);
-  } 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;
-}
-
-/** First page of a category — same wrap; category filtering only works through search. */
-export async function fetchProductsByCategory(categoryId: string, { limit = 24 } = {}): Promise<ProductSummary[]> {
-  return (await searchCatalog({ limit, categoryId })).products;
-}
-
-/** Fetch one product by its URL slug, with options/modifiers/variants. Null when not found. */
-export async function fetchProductBySlug(slug: string): Promise<ProductDetail | null> {
-  try {
-    const res = await products.getProductBySlug(slug, { fields: DETAIL_FIELDS as any });
-    return res.product ? toDetail(res.product as Raw, imgSrc, mediaKey) : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * List the store's categories for nav/filter UI, minus Wix's auto-created "all-products"
- * system category. The query must carry a filter condition (`.exists("name", true)` — a
- * tautology): a bare .find() serializes an empty filter that the API rejects on the
- * visitor-client path. Treat a failure as "no category nav", not a fatal error.
- */
-export async function fetchCategories(): Promise<Category[]> {
-  try {
-    const res = await categories
-      .queryCategories({ treeReference: { appNamespace: "@wix/stores" } })
-      .exists("name", true)
-      .find();
-    return (res.items ?? []).map((c) => toCategory(c as Raw)).filter((c) => c.slug !== "all-products");
-  } catch {
-    return [];
-  }
-}
-
-/**
- * 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). The response is WRAPPED:
- * { category }. 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: Raw = await categories.getCategoryBySlug(slug, { appNamespace: "@wix/stores" } as any);
-    const raw: Raw | undefined = res?.category;
-    if (!raw || raw.visible === false) return null;
-    return toCategory(raw);
-  } catch {
-    return null;
-  }
-}

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

@@ -1,147 +0,0 @@
-// Product detail as a framework-free store — the logic behind useProductDetail, usable from React
-// (useProductDetail wraps it), from a static page's PDP and quick-add picker, from Vue/Svelte, or as
-// the specification for a port. Option selection → variant resolution → add-to-cart, plus modifier
-// inputs. This is where the "adds variants[0] regardless of the buyer's choice" class of bugs comes
-// from — always drive a purchase surface through this store, never resolve variants by hand.
-//
-// Selections start EMPTY (a buyer who never noticed a pre-picked default buys the wrong colour).
-// Pass the server-fetched ProductDetail as `initial` (SSR) or a `slug` (the store fetches on start).
-// One store per product surface: createProductDetailStore(), not a singleton.
-import { fetchProductBySlug, resolveVariant } from "./catalog";
-import { addLine } from "./cart-store";
-import type { ProductDetail, ProductOption, ProductVariant } from "./types";
-
-export interface ProductDetailStoreOptions {
-  initial?: ProductDetail | null;
-  slug?: string;
-}
-
-export interface OptionGroupView extends ProductOption {
-  choices: (ProductOption["choices"][number] & { selected: boolean })[];
-}
-
-export interface ProductDetailState {
-  /** 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[];
-  /** Modifier inputs keyed by modifier key. */
-  modifierValues: Record<string, string>;
-  /** The resolved variant; null while the selection is incomplete. */
-  variant: ProductVariant | null;
-  /** The RANGE ("€24.99 – €34.99", one value when equal) until every option is picked, then the variant's price. */
-  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 ("Choose Size"), not an error; null when addable. */
-  blockedReason: string | null;
-  quantity: number;
-  adding: boolean;
-  error: string | null;
-}
-
-export interface ProductDetailStore {
-  getState(): ProductDetailState;
-  subscribe(listener: () => void): () => void;
-  /** Fetch by slug when no `initial` was given. Call once when mounted. */
-  start(): void;
-  stop(): void;
-  selectOption(optionName: string, choiceName: string): void;
-  setModifier(key: string, value: string): void;
-  setQuantity(n: number): void;
-  /** Adds the resolved variant to the cart (the cart store opens the drawer). Throws on refusal. */
-  add(): Promise<void>;
-}
-
-export function createProductDetailStore({ initial, slug }: ProductDetailStoreOptions): ProductDetailStore {
-  let product: ProductDetail | null = initial ?? null;
-  let notFound = false;
-  let selections: Record<string, string> = {};
-  let modifierValues: Record<string, string> = {};
-  let quantity = 1;
-  let adding = false;
-  let error: string | null = null;
-  let started = false;
-  const listeners = new Set<() => void>();
-  let snapshot: ProductDetailState | null = null;
-  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
-
-  function getState(): ProductDetailState {
-    if (snapshot) return snapshot;
-    const variant = product ? resolveVariant(product, selections) : null;
-    const optionGroups: OptionGroupView[] = (product?.options ?? []).map((o) => ({
-      ...o,
-      choices: o.choices.map((c) => ({ ...c, selected: selections[o.name] === c.name })),
-    }));
-    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) : "";
-    snapshot = {
-      product, notFound, optionGroups, modifierValues, variant,
-      price: variant?.price || rangeDisplay,
-      compareAtPrice: variant ? variant.compareAtPrice : isRange ? null : (product?.compareAtPrice ?? null),
-      isPreorder, canAdd, blockedReason, quantity, adding, error,
-    };
-    return snapshot;
-  }
-
-  return {
-    getState,
-    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
-    start() {
-      if (started) return;
-      started = true;
-      if (initial || !slug) return;
-      fetchProductBySlug(slug)
-        .then((p) => { if (!started) return; product = p; notFound = p === null; emit(); })
-        .catch(() => { if (started) { notFound = true; emit(); } });
-    },
-    stop() { started = false; },
-    selectOption(optionName, choiceName) {
-      selections = { ...selections, [optionName]: choiceName };
-      quantity = 1; // the ceiling belongs to the newly resolved variant
-      emit();
-    },
-    setModifier(key, value) { modifierValues = { ...modifierValues, [key]: value }; emit(); },
-    setQuantity(n) { quantity = n; emit(); },
-    async add() {
-      const s = getState();
-      if (!product || !s.variant) return;
-      adding = true; error = null; emit();
-      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 addLine(product.id, s.variant.variantId, quantity, { modifierChoices: choiceModifiers, customTextFields: textModifiers, preorder: s.isPreorder });
-      } catch (e) {
-        error = e instanceof Error ? e.message : String(e);
-        throw e;
-      } finally {
-        adding = false; emit();
-      }
-    },
-  };
-}