@wix/agent-skills 1.19.1 → 1.19.2

package/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx

@@ -3,6 +3,7 @@
 import { createContext, useContext, useState, useEffect, useCallback } from "react";
 import {
   getCurrentCart,
+  estimateCurrentCart,
   addToCart as apiAdd,
   removeFromCart as apiRemove,
   updateCartItemQuantity as apiQty,
@@ -12,7 +13,11 @@ import {
 const CartContext = createContext(null);
 
 export function CartProvider({ children }) {
-  const [cart, setCart] = useState(null);
+  const [cart, setCartState] = useState(null);
+  // The calculated summary (after-discount subtotal, cart-level discount) — from the estimate, never
+  // summed in the client. Refreshed with every cart change; null while unknown or when the estimate
+  // fails, in which case surfaces fall back to cart.subtotal.
+  const [summary, setSummary] = useState(null);
   const [isOpen, setIsOpen] = useState(false);
   const [loading, setLoading] = useState(false);
   // The cart helpers throw on refusal with a buyer-readable reason — an empty cart, or line items
@@ -20,7 +25,13 @@ export function CartProvider({ children }) {
   // this the rejection is unhandled and the shopper sees the spinner stop with nothing said.
   const [error, setError] = useState(null);
 
-  const refreshCart = useCallback(async () => setCart(await getCurrentCart()), []);
+  // Every cart write goes through here so the summary always describes the cart on screen.
+  const setCart = useCallback((next) => {
+    setCartState(next);
+    if (!next?.lineItems?.length) { setSummary(null); return; }
+    estimateCurrentCart().then((s) => setSummary(s)).catch(() => setSummary(null));
+  }, []);
+  const refreshCart = useCallback(async () => setCart(await getCurrentCart()), [setCart]);
   useEffect(() => {
     refreshCart();
     const onVisible = () => document.visibilityState === "visible" && refreshCart();
@@ -59,7 +70,7 @@ export function CartProvider({ children }) {
     run(async () => { window.location.href = await apiCheckout(); }, { reread: true });
 
   return (
-    <CartContext.Provider value={{ cart, itemCount, isOpen, setIsOpen, loading, error, clearError: () => setError(null), addToCart, removeItem, updateQuantity, checkout, refreshCart }}>
+    <CartContext.Provider value={{ cart, summary, itemCount, isOpen, setIsOpen, loading, error, clearError: () => setError(null), addToCart, removeItem, updateQuantity, checkout, refreshCart }}>
       {children}
     </CartContext.Provider>
   );

package/skills/wix-vibe-headless/references/storefront/app/hooks/useProductCard.js

@@ -1,22 +1,16 @@
 // Headless data layer for a product grid tile.
 // Normalises raw Wix product fields into render-agnostic structures so you can build
 // whatever card UI you want (image layout, badge style, price display, quick-add trigger)
-// without touching the badge-priority logic, price-range maths, or colour-dot extraction.
+// without touching the badge logic, price rules, or colour-dot extraction.
 //
 // Usage:
-//   const { isSoldOut, leftBadges, promoBadge, priceDisplay, compareAtDisplay,
-//           colors, optionLabel, isQuickAddable, image, hoverImage } = useProductCard(product);
-//   // then render however you want, call addToCart(product.id) from useCart() for quick-add.
+//   const { isSoldOut, leftBadges, ribbons, promoBadge, priceDisplay, compareAtDisplay,
+//           colors, optionLabel, isQuickAddable, directAddVariantId, image, hoverImage } = useProductCard(product);
+//   // then render however you want; quick-add: addToCart(product.id, directAddVariantId) from useCart().
 
 import { useMemo } from "react";
 import { productImage, productGallery } from "@/lib/storeImage";
-
-function discountPercent(product) {
-  const now = Number(product?.actualPriceRange?.minValue?.amount);
-  const was = Number(product?.compareAtPriceRange?.minValue?.amount);
-  if (!now || !was || was <= now) return null;
-  return Math.round(((was - now) / was) * 100);
-}
+import { sellingPrice } from "@/rest/wix-store-catalog";
 
 export function useProductCard(product) {
   return useMemo(() => {
@@ -32,23 +26,31 @@ export function useProductCard(product) {
     else if (isSoldOut)            leftBadges.push({ type: "sold-out",      label: "Sold out"      });
     if (isPartiallyOutOfStock)     leftBadges.push({ type: "limited-stock", label: "Limited stock" });
 
-    // Right-side promo badge: discount % beats a merchant ribbon (a "Sale" ribbon is redundant
-    // when the % is already showing). Only one at a time.
-    const discount = discountPercent(product);
-    const ribbon   = product?.ribbon?.name;
-    const promoBadge = discount
-      ? { type: "discount", label: `-${discount}%` }
-      : ribbon
-      ? { type: "ribbon",   label: ribbon }
-      : null;
+    // Merchant ribbons — the primary one plus every additional one. Render ALL of them, in one shared
+    // style (a "Sale" accent is fine, applied by label). Never compute a "-20%" badge from the price
+    // range: a range's minimum says nothing about the variant the buyer picks, and a ribbon is a
+    // label, not a price claim.
+    const ribbons = [product?.ribbon?.name, ...(product?.additionalRibbons ?? []).map((r) => r?.name)]
+      .filter((name, i, all) => name && all.indexOf(name) === i);
+    const promoBadge = ribbons[0] ? { type: "ribbon", label: ribbons[0] } : null;
 
-    // Price: show a min–max range when variants span different prices so the PDP doesn't
-    // appear to raise the price once a variant is selected.
-    const priceMin = product?.actualPriceRange?.minValue?.formattedAmount;
-    const priceMax = product?.actualPriceRange?.maxValue?.formattedAmount;
-    const compareAt = product?.compareAtPriceRange?.minValue?.formattedAmount;
-    const priceDisplay      = priceMax && priceMax !== priceMin ? `${priceMin} – ${priceMax}` : priceMin;
-    const compareAtDisplay  = compareAt && compareAt !== priceMin ? compareAt : null;
+    // Price. A single-price product shows the price the buyer pays — the lowest-priced variant's
+    // discounted price when an automatic discount applies (priceAfterDiscount), else its regular
+    // price — with the struck "was" price beside it. Variants priced differently show a min–max
+    // range with NO struck price: one lone "was" against a range implies a saving that may not
+    // apply to the variant the buyer picks; the PDP shows the real comparison once a variant is chosen.
+    const min = product?.actualPriceRange?.minValue;
+    const max = product?.actualPriceRange?.maxValue;
+    const isRange = !!(min?.amount && max?.amount && min.amount !== max.amount);
+    const minVariant = product?.variantSummary?.minPriceVariant ?? null;
+    const { current, original } = sellingPrice(minVariant?.price);
+    const priceDisplay = isRange
+      ? `${min?.formattedAmount ?? ""} – ${max?.formattedAmount ?? ""}`
+      : current?.formattedAmount ?? min?.formattedAmount;
+    const compareAtDisplay =
+      !isRange && original?.formattedAmount && Number(original.amount) > Number(current?.amount ?? min?.amount)
+        ? original.formattedAmount
+        : null;
 
     // Options preview for the tile summary row.
     // Colour options → real hex dots (more informative than "3 colours").
@@ -68,6 +70,8 @@ export function useProductCard(product) {
     // Quick-add is only safe for single-variant products (no option choices to resolve).
     // Sold-out with pre-order still shows a CTA, but it links to the PDP, not quick-add.
     const isQuickAddable = !hasOptions && !isSoldOut;
+    // The variant a direct add sends (a product with no options still has one variant).
+    const directAddVariantId = isQuickAddable ? minVariant?.id ?? null : null;
 
     // Images: normalised through lib/storeImage so URLs are consistent across the tile,
     // the PDP gallery, and the cart. Hover image is the second gallery shot (if one exists).
@@ -78,15 +82,17 @@ export function useProductCard(product) {
       isSoldOut,
       isPreorder,
       isPartiallyOutOfStock,
-      leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
-      promoBadge,       // { type: 'discount'|'ribbon', label } | null
-      priceDisplay,     // formatted price (range or single value)
-      compareAtDisplay, // formatted compare-at price | null
-      colors,           // hex strings — render as dots; the tile shows up to however many you want
-      optionLabel,      // "3 sizes · 2 materials" or empty string
+      leftBadges,          // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
+      ribbons,             // every merchant ribbon label, primary first — render all of them
+      promoBadge,          // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
+      priceDisplay,        // formatted price the buyer pays, or a min–max range
+      compareAtDisplay,    // formatted struck "was" price | null (never beside a range)
+      colors,              // hex strings — render as dots; the tile shows up to however many you want
+      optionLabel,         // "3 sizes · 2 materials" or empty string
       isQuickAddable,
-      image,            // primary image URL | null
-      hoverImage,       // second image URL for hover effect | null
+      directAddVariantId,  // pass as variantId to addToCart on quick-add
+      image,               // primary image URL | null
+      hoverImage,          // second image URL for hover effect | null
     };
   }, [product]);
 }

package/skills/wix-vibe-headless/references/storefront/app/hooks/useProductDetail.js

@@ -1,13 +1,15 @@
-// useProductDetail — all PDP logic, no markup: load product by slug, pre-select first in-stock
-// choice per option, resolve the buyer's selections to a Wix variant, gate add-to-cart on stock +
-// mandatory modifiers, and build the addToCart payload. The data paths here (variant resolution,
-// modifier keys, stock gating) are the bug-prone part — keep them verbatim; the PDP page only
-// renders what this returns.
+// useProductDetail — all PDP logic, no markup: load product by slug, resolve the buyer's selections
+// to a Wix variant, gate add-to-cart on availability + mandatory modifiers, and build the addToCart
+// payload. The data paths here (variant resolution, price precedence, modifier keys, stock gating)
+// are the bug-prone part — keep them verbatim; the PDP page only renders what this returns.
 import { useState, useEffect, useMemo } from "react";
-import { getProductBySlug } from "@/rest/wix-store-catalog";
+import { getProductBySlug, sellingPrice } from "@/rest/wix-store-catalog";
 import { choiceImage, variantImage } from "@/lib/storeImage";
 import { useCart } from "@/context/CartContext";
 
+// A variant is identified by the SET of its choice ids — sorted, so option order can't matter.
+const choiceKey = (choiceIds) => [...choiceIds].sort().join("_");
+
 export function useProductDetail(slug) {
   const { addToCart } = useCart();
   const [product, setProduct] = useState(null);
@@ -16,6 +18,8 @@ export function useProductDetail(slug) {
   // link, the other is worth retrying. Without the split, a network blip reads as "product deleted".
   const [error, setError] = useState(null);
   const [adding, setAdding] = useState(false);
+  // Selections start EMPTY. Pre-picking the first choice lets a buyer who never noticed the default
+  // buy the wrong colour; the PDP shows a neutral "choose a size" until every option is picked.
   const [selectedOptions, setSelectedOptions] = useState({});
   const [modifierValues, setModifierValues] = useState({});
   const [quantity, setQuantity] = useState(1);
@@ -26,17 +30,13 @@ export function useProductDetail(slug) {
     setProduct(null);
     setNotFound(false);
     setError(null);
+    setSelectedOptions({});
+    setQuantity(1);
     getProductBySlug(slug)
       .then((p) => {
         if (cancelled) return;
         if (!p) return setNotFound(true);
         setProduct(p);
-        const initial = {};
-        (p.options || []).forEach((o) => {
-          const first = o.choicesSettings?.choices?.find((c) => c.inStock !== false);
-          if (first) initial[o.id] = first.choiceId;
-        });
-        setSelectedOptions(initial);
       })
       .catch((e) => { if (!cancelled) setError(e?.message || "Couldn't load this product."); });
     return () => { cancelled = true; };
@@ -44,29 +44,70 @@ export function useProductDetail(slug) {
 
   const options = product?.options || [];
   const modifiers = product?.modifiers || [];
-  const variants = product?.variantsInfo?.variants || [];
 
+  // Visible variants keyed by their sorted choice ids. Two variants with the same choices is a
+  // catalog defect — report it instead of silently letting one overwrite the other.
+  const { variantByKey, duplicateKey } = useMemo(() => {
+    const map = new Map();
+    let dup = null;
+    for (const v of product?.variantsInfo?.variants || []) {
+      if (v.visible === false) continue;
+      const k = choiceKey((v.choices || []).map((c) => c.optionChoiceIds?.choiceId));
+      if (map.has(k) && !dup) dup = k;
+      map.set(k, v);
+    }
+    return { variantByKey: map, duplicateKey: dup };
+  }, [product]);
+
+  const selectionComplete = options.length > 0 && options.every((o) => selectedOptions[o.id]);
   const variant = useMemo(() => {
-    if (options.length === 0) return variants[0] || null;
-    if (!options.every((o) => selectedOptions[o.id])) return null;
-    return variants.find((v) => (v.choices || []).every((c) =>
-      selectedOptions[c.optionChoiceIds?.optionId] === c.optionChoiceIds?.choiceId)) || null;
-  }, [options, variants, selectedOptions]);
+    if (options.length === 0) return variantByKey.values().next().value || null;   // the single variant
+    if (!selectionComplete || duplicateKey) return null;
+    return variantByKey.get(choiceKey(options.map((o) => selectedOptions[o.id]))) || null;
+  }, [options, variantByKey, duplicateKey, selectedOptions, selectionComplete]);
 
+  // In stock OR pre-orderable counts as buyable; a preorder add carries preOrderRequested.
   const inStock = variant ? variant.inventoryStatus?.inStock !== false : true;
+  const isPreorder = !!variant && !inStock && variant.inventoryStatus?.preorderEnabled === true;
+  const available = inStock || isPreorder;
+
+  const missingModifier = modifiers.find((m) => m.mandatory && !(
+    m.modifierRenderType === "FREE_TEXT" ? modifierValues[m.freeTextSettings?.key] : modifierValues[m.key]));
+
   const canAdd = useMemo(() => {
+    if (!product) return false;
     if (options.length > 0 && !variant) return false;
-    if (variant && !inStock) return false;
-    return modifiers.filter((m) => m.mandatory).every((m) =>
-      m.modifierRenderType === "FREE_TEXT" ? !!modifierValues[m.freeTextSettings?.key] : !!modifierValues[m.key]);
-  }, [options, variant, inStock, modifiers, modifierValues]);
+    if (variant && !available) return false;
+    return !missingModifier;
+  }, [product, options, variant, available, missingModifier]);
+
+  // Why the buy button is disabled — neutral guidance to render next to the action ("Choose a
+  // size"), not an error; null when the buyer can add. Promote to error styling only after they try.
+  const blockedReason = useMemo(() => {
+    if (!product) return null;
+    if (duplicateKey) return "This product's variants can't be resolved right now.";
+    if (options.length > 0 && !selectionComplete) {
+      const missing = options.filter((o) => !selectedOptions[o.id]).map((o) => o.name);
+      return `Choose ${missing.join(" and ")}`;
+    }
+    if (options.length > 0 && !variant) return "This combination isn't available";
+    if (variant && !available) return "Out of stock";
+    if (missingModifier) return `Add ${missingModifier.name}`;
+    return null;
+  }, [product, duplicateKey, options, selectionComplete, selectedOptions, variant, available, missingModifier]);
 
-  // Everything the buyer sees follows the resolved `variant` (also returned below, so an agent can
-  // surface more from it — sku, barcode, subscriptionPricesInfo — without new plumbing). Price and
-  // its struck-through "was" price come off the variant, falling back to the product's range before
-  // every option is picked.
-  const price = variant?.price?.actualPrice?.formattedAmount || product?.actualPriceRange?.minValue?.formattedAmount || "";
-  const compareAtPrice = variant?.price?.compareAtPrice?.formattedAmount || product?.compareAtPriceRange?.minValue?.formattedAmount || "";
+  // Everything the buyer sees follows the resolved `variant` (also returned below). The price obeys
+  // the exact precedence in sellingPrice(): an automatic discount beats the regular price and strikes
+  // it; else the regular price with the merchant's compare-at as the "was". Before every option is
+  // picked, the product's min–max range (one value when equal) — never an empty price.
+  const min = product?.actualPriceRange?.minValue, max = product?.actualPriceRange?.maxValue;
+  const rangeDisplay = min?.amount && max?.amount && min.amount !== max.amount
+    ? `${min.formattedAmount} – ${max.formattedAmount}` : (min?.formattedAmount || "");
+  const resolved = variant ? sellingPrice(variant.price) : null;
+  const price = resolved?.current?.formattedAmount || rangeDisplay;
+  const compareAtPrice = resolved && resolved.original?.formattedAmount &&
+    Number(resolved.original.amount) > Number(resolved.current?.amount) ? resolved.original.formattedAmount : "";
+  const discountNames = product?.discountInfo?.discountRuleNames || [];   // automatic discounts, product level
 
   // The gallery follows the selection. Prefer the selected choice's own image (the per-swatch photo,
   // choice.media.items[].mediaId) — Wix's per-variant media is often NOT differentiated (it defaults to
@@ -82,7 +123,11 @@ export function useProductDetail(slug) {
     return variantImage(variant);
   }, [variant, options, selectedOptions]);
 
-  const selectOption = (optionId, choiceId) => setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
+  // Changing an option resets the quantity — the ceiling belongs to the newly resolved variant.
+  const selectOption = (optionId, choiceId) => {
+    setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
+    setQuantity(1);
+  };
   const setModifier = (key, value) => setModifierValues((s) => ({ ...s, [key]: value }));
 
   async function submit() {
@@ -101,6 +146,7 @@ export function useProductDetail(slug) {
       return await addToCart(product.id, variant?.id, Math.max(1, Number(quantity) || 1), {
         modifierChoices: Object.keys(modifierChoices).length ? modifierChoices : undefined,
         customTextFields: Object.keys(customTextFields).length ? customTextFields : undefined,
+        preorder: isPreorder,
       });
     } finally {
       setAdding(false);
@@ -111,6 +157,7 @@ export function useProductDetail(slug) {
     product, notFound, error, retry: () => setReloadKey((k) => k + 1),
     options, modifiers,
     selectedOptions, selectOption, modifierValues, setModifier,
-    quantity, setQuantity, variant, inStock, canAdd, adding, price, compareAtPrice, submit, focusMediaUrl,
+    quantity, setQuantity, variant, inStock, isPreorder, canAdd, blockedReason, adding,
+    price, compareAtPrice, discountNames, submit, focusMediaUrl,
   };
 }

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js

@@ -40,17 +40,24 @@ const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
  * Throws on out-of-stock so the buyer can't reach checkout with an unbuyable line.
  * Full catalogReference reference: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md
  *
+ * A pre-order variant (inventoryStatus.preorderEnabled, out of stock) is added with `preorder: true`;
+ * a recurring subscription plan with its `subscriptionOptionId` (omit it for a one-time purchase).
+ * The two may coexist.
+ *
  * @param {string} catalogItemId    Product GUID (product.id).
  * @param {string} [variantId]      variantsInfo.variants[].id — required for products with variants.
  * @param {number} [quantity]
- * @param {{ modifierChoices?: Record<string,string>, customTextFields?: Record<string,string> }} [extras]
+ * @param {{ modifierChoices?: Record<string,string>, customTextFields?: Record<string,string>,
+ *           subscriptionOptionId?: string, preorder?: boolean }} [extras]
  * @returns {Promise<object>} Updated cart.
  */
-export async function addToCart(catalogItemId, variantId, quantity = 1, { modifierChoices, customTextFields } = {}) {
+export async function addToCart(catalogItemId, variantId, quantity = 1, { modifierChoices, customTextFields, subscriptionOptionId, preorder } = {}) {
   const catalogReferenceOptions = {};
   if (variantId) catalogReferenceOptions.variantId = variantId;
   if (modifierChoices && Object.keys(modifierChoices).length) catalogReferenceOptions.options = modifierChoices;
   if (customTextFields && Object.keys(customTextFields).length) catalogReferenceOptions.customTextFields = customTextFields;
+  if (subscriptionOptionId) catalogReferenceOptions.subscriptionOptionId = subscriptionOptionId;
+  if (preorder) catalogReferenceOptions.preOrderRequested = true;
 
   const catalogReference = { appId: STORES_APP_ID, catalogItemId };
   if (Object.keys(catalogReferenceOptions).length) catalogReference.options = catalogReferenceOptions;
@@ -92,8 +99,30 @@ export async function getCurrentCart() {
   }
 }
 
+/**
+ * Estimate the current cart's totals — the ONLY source of the after-discount subtotal and the
+ * cart-level discount. Line prices already carry item-level discounts; delivery and tax resolve at
+ * checkout unless asked for, so never invent them. Returns null when there is no cart or the
+ * estimate fails (a display nicety — the cart itself stays valid).
+ * https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/estimate-current-cart.md
+ * @returns {Promise<{ priceSummary: { subtotal: object, discount: object, total: object } }|null>}
+ *   priceSummary amounts are ConvertedMoney { amount, convertedAmount } — format like line prices.
+ */
+export async function estimateCurrentCart() {
+  try {
+    const res = await wixApiRequest("/ecom/v2/carts/current/estimate", { method: "POST", body: {} });
+    return res?.summary ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Start the hosted checkout for the current cart and return its URL.
+ * This is the shopper's CURRENT cart. A "Buy now" that skips the cart needs a standalone cart
+ * (POST /ecom/v2/carts) handed to the redirect session — it must never append to or replace the
+ * current cart. Not shipped here; verify the redirect session accepts a standalone cart id under
+ * the visitor token before adding it.
  * In Cart V2 the cart id IS the checkout id — there is no separate checkout-creation call; the
  * redirect session is created straight from the current cart's id.
  * Throws on empty cart, unavailable lines, or a missing redirect URL.

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-catalog.js

@@ -13,8 +13,13 @@ import { wixApiRequest } from "./wix-client.js";
  *   actualPriceRange.minValue.formattedAmount {string} — lowest price with currency symbol,
  *   actualPriceRange.maxValue.formattedAmount {string} — highest price with currency symbol,
  *   compareAtPriceRange.minValue.formattedAmount {string} — strikethrough price (present when on sale),
- *   actualPriceRange/compareAtPriceRange .minValue.amount {string} — the same figures unformatted
- *     ("129.00"). Use these for arithmetic: a percent-off badge can't be computed from "€129.00",
+ *   actualPriceRange/compareAtPriceRange .minValue.amount {string} — the same figures unformatted.
+ *     Never compute a percent-off or "you save" claim from them: a range's minimum says nothing about
+ *     the variant the buyer picks. The price the buyer pays comes from sellingPrice() below.
+ *   variantSummary.minPriceVariant {object} — the lowest-priced visible variant (MIN_PRICE_VARIANT):
+ *     { id, price: { actualPrice, compareAtPrice?, priceAfterDiscount? } } — a card's price, and the
+ *     variantId for a direct add on a product with no options,
+ *   discountInfo.discountRuleNames {string[]} — automatic-discount names (DISCOUNT_INFO), product level,
  *   inventory.availabilityStatus {string} — "IN_STOCK"|"OUT_OF_STOCK"|"PARTIALLY_OUT_OF_STOCK",
  *   inventory.preorderStatus {string} — "ENABLED"|"DISABLED". ENABLED + OUT_OF_STOCK is a pre-order,
  *     which is buyable — label it "Pre-order" rather than "Sold out",
@@ -23,8 +28,9 @@ import { wixApiRequest } from "./wix-client.js";
  *     getProductBySlug call per product,
  *   ribbon {object} — { id, name } merchant-set badge: "New", "Sale", "Best Seller". This is the
  *     catalogue's own label, so prefer it over anything derived — a "new" badge computed from
- *     createdDate flags every product at once right after seeding,
- *   additionalRibbons {array} — further { id, name } badges,
+ *     createdDate flags every product at once right after seeding. A ribbon is a LABEL: a "Sale"
+ *     ribbon is not proof of a lower price, and a compareAtPrice does not earn a ribbon,
+ *   additionalRibbons {array} — up to four further { id, name } badges. Render ALL of them,
  *   createdDate / updatedDate {string} — ISO timestamps,
  *   variantSummary.variantCount {number} — how many variants exist, without fetching them,
  *   options {array} — product options e.g. Size, Color:
@@ -45,9 +51,11 @@ import { wixApiRequest } from "./wix-client.js";
  *     dangerouslySetInnerHTML; strip tags only for plain-text contexts (meta description, teaser),
  *   variantsInfo.variants {array} — returned only by getProductBySlug:
  *     [{ id, visible, choices [{ optionChoiceIds: { optionId, choiceId } }],
- *        price: { actualPrice, compareAtPrice }, media, inventoryStatus: { inStock } }]
+ *        price: { actualPrice, compareAtPrice?, priceAfterDiscount? }, media,
+ *        inventoryStatus: { inStock, preorderEnabled } }]
  *     To resolve a buyer's option selections to a variantId: find the variant whose choices
  *     match all selected { optionId, choiceId } pairs, then pass variant.id to addToCart.
+ *     A variant is buyable when inStock OR preorderEnabled (a preorder add carries preOrderRequested).
  *
  * Category: { id, name, slug, visible, description, image, itemCounter, parentCategory.id }
  *   NB: queryCategories includes the auto-created system category { slug: "all-products" } —
@@ -55,6 +63,20 @@ import { wixApiRequest } from "./wix-client.js";
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories
  */
 
+/**
+ * The price the buyer pays, and the price to strike — exact precedence, shared by cards and the PDP.
+ * An automatic discount (priceAfterDiscount, present only 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.
+ * @param {{ actualPrice?: object, compareAtPrice?: object, priceAfterDiscount?: object }} [price]
+ *   variant.price, or variantSummary.minPriceVariant.price. Each is { amount, formattedAmount }.
+ * @returns {{ current: object|undefined, original: object|undefined }} render .formattedAmount
+ */
+export function sellingPrice(price) {
+  if (price?.priceAfterDiscount !== undefined) return { current: price.priceAfterDiscount, original: price.actualPrice };
+  return { current: price?.actualPrice, original: price?.compareAtPrice };
+}
+
 // Search Products supports server-side sort/filter before cursor paging:
 // https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md
 export const CATALOG_SORTS = {
@@ -108,7 +130,9 @@ export async function searchProducts({ limit = 100, cursor, categoryId, sort = "
   }
   const res = await wixApiRequest("/stores/v3/products/search", {
     method: "POST",
-    body: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"], search: query },
+    // MIN_PRICE_VARIANT + DISCOUNT_INFO → variantSummary.minPriceVariant with its discounted price:
+    // the card's price and the direct-add variantId, without a per-product fetch.
+    body: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO", "MIN_PRICE_VARIANT", "DISCOUNT_INFO"], search: query },
   });
   return { products: res?.products ?? [], nextCursor: res?.pagingMetadata?.cursors?.next ?? null };
 }
@@ -137,6 +161,7 @@ export async function getProductBySlug(slug) {
         "MEDIA_ITEMS_INFO",
         "PRODUCT_CHOICES_MEDIA_REFERENCES",
         "VARIANT_OPTION_CHOICE_NAMES",
+        "DISCOUNT_INFO", // variant price.priceAfterDiscount + discountInfo.discountRuleNames
       ],
     },
   });