@jay-framework/wix-stores 0.19.6 → 0.20.0

package/README.md

@@ -64,9 +64,6 @@ Run `jay-stack agent-kit` (or `yarn agent-kit`) to index the live category tree
 urls:
   product: '/products/{slug}' # default
   category: null # no category pages by default
-
-# Fallback category for pages without category context
-defaultCategory: 'all-products' # slug of the fallback category
 ```
 
 URL templates use three placeholders:
@@ -114,7 +111,6 @@ src/pages/products/
 urls:
   product: '/products/{prefix}/{category}/{slug}'
   category: '/products/{prefix}/{category}'
-defaultCategory: 'all-products'
 ```
 
 ```
@@ -154,12 +150,12 @@ src/pages/products/polgat/
 
 ### Setting Params for Static Routes
 
-Static route directories use `jay-params` to tell the component which prefix they represent:
+Static route directories use `jay-params` to tell the component which category they represent:
 
 ```html
-<!-- src/pages/products/polgat/page.jay-html -->
+<!-- src/pages/products/polgat/page.jay-html (root category) -->
 <script type="application/jay-params">
-  prefix: polgat
+  category: polgat
 </script>
 <script
   type="application/jay-headless"
@@ -171,11 +167,10 @@ Static route directories use `jay-params` to tell the component which prefix the
 
 ## Category Header
 
-The category header is always loaded. The component resolves category metadata using a fallback chain:
+The category header is always loaded. The component resolves category metadata:
 
-1. **`category` param** → load category
-2. **`prefix` param** → load root category
-3. **Neither** → load `defaultCategory` from config
+1. **`category` param** → load category (always the active category slug)
+2. **No `category`** → load the "All Products" system category via `getAllProductsCategory()` (header only, no base filter)
 
 If the resolved category is missing image, description, or SEO data, the component walks up the parent chain until it finds the data. Each field inherits independently.
 

package/dist/agent-kit/aiditor/add-menu.template.yaml

@@ -5,7 +5,11 @@ items:
     subCategory: Components
     pluginName: wix-stores
     packageName: "@jay-framework/wix-stores"
-    thumbnail: thumbnails/wix-stores/product-search.png
+    thumbnail: thumbnails/wix-stores/product-search.svg
+    interaction:
+      mode: stage-place
+      stagePromptTemplate: |
+        Add a product search component at this marker location on the page.
     prompt: |
       Use headless component @jay-framework/wix-stores / contract product-search.
       Read agent-kit/materialized-contracts/wix-stores/product-search.jay-contract.
@@ -18,26 +22,52 @@ items:
     subCategory: Components
     pluginName: wix-stores
     packageName: "@jay-framework/wix-stores"
-    thumbnail: thumbnails/wix-stores/product-page.png
+    thumbnail: thumbnails/wix-stores/product-page.svg
+    interaction:
+      mode: stage-place
+      stagePromptTemplate: |
+        Add a product page component at this marker location on the page.
     prompt: |
       Use headless component @jay-framework/wix-stores / contract product-page.
       Read agent-kit/materialized-contracts/wix-stores/product-page.jay-contract.
       Script key: p
       Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
 
-  - id: wix-stores:related-products
-    title: Related products
+  - id: wix-stores:category-products
+    title: Category products
     category: Store
     subCategory: Components
     pluginName: wix-stores
     packageName: "@jay-framework/wix-stores"
-    thumbnail: thumbnails/wix-stores/related-products.png
+    thumbnail: thumbnails/wix-stores/category-products.svg
+    interaction:
+      mode: stage-place
+      stagePromptTemplate: |
+        Add a category products grid at this marker location on the page.
     prompt: |
-      Use headless component @jay-framework/wix-stores / contract related-products.
-      Read agent-kit/materialized-contracts/wix-stores/related-products.jay-contract.
+      Use headless component @jay-framework/wix-stores / contract category-products.
+      Read agent-kit/materialized-contracts/wix-stores/category-products.jay-contract.
       Script key: r
       Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
-      Use alongside product-page; pass productId and categorySlug as instance props.
+      Pass categorySlug to show products from a category. Pass productId to exclude a product (e.g. on a product page).
+
+  - id: wix-stores:product-spotlight
+    title: Product spotlight
+    category: Store
+    subCategory: Components
+    pluginName: wix-stores
+    packageName: "@jay-framework/wix-stores"
+    thumbnail: thumbnails/wix-stores/product-spotlight.png
+    interaction:
+      mode: stage-place
+      stagePromptTemplate: |
+        Add a product spotlight at this marker location on the page.
+    prompt: |
+      Use headless component @jay-framework/wix-stores / contract product-spotlight.
+      Read agent-kit/materialized-contracts/wix-stores/product-spotlight.jay-contract.
+      Script key: spotlight
+      Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
+      Pass slug as a prop to specify which product to display.
 
   - id: wix-stores:category-list
     title: Category list
@@ -45,7 +75,11 @@ items:
     subCategory: Components
     pluginName: wix-stores
     packageName: "@jay-framework/wix-stores"
-    thumbnail: thumbnails/wix-stores/category-list.png
+    thumbnail: thumbnails/wix-stores/category-list.svg
+    interaction:
+      mode: stage-place
+      stagePromptTemplate: |
+        Add a category list at this marker location on the page.
     prompt: |
       Use headless component @jay-framework/wix-stores / contract category-list.
       Read agent-kit/materialized-contracts/wix-stores/category-list.jay-contract.

package/dist/agent-kit/aiditor/thumbnails/wix-stores/category-list.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="320" height="240" viewBox="0 0 320 240" fill="none">
+  <rect width="320" height="240" fill="#f8fafc"/>
+  <rect x="16" y="20" width="288" height="36" rx="8" fill="#fff" stroke="#e2e8f0"/>
+  <rect x="28" y="32" width="120" height="12" rx="3" fill="#cbd5e1"/>
+  <rect x="16" y="72" width="136" height="14" rx="4" fill="#e2e8f0"/>
+  <rect x="16" y="98" width="288" height="1" fill="#e2e8f0"/>
+  <rect x="16" y="112" width="200" height="12" rx="3" fill="#cbd5e1"/>
+  <rect x="16" y="136" width="160" height="10" rx="3" fill="#e2e8f0"/>
+  <rect x="16" y="168" width="288" height="1" fill="#e2e8f0"/>
+  <rect x="16" y="182" width="184" height="12" rx="3" fill="#cbd5e1"/>
+  <rect x="16" y="206" width="128" height="10" rx="3" fill="#e2e8f0"/>
+</svg>

package/dist/agent-kit/aiditor/thumbnails/wix-stores/category-products.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="320" height="240" viewBox="0 0 320 240" fill="none">
+  <rect width="320" height="240" fill="#f8fafc"/>
+  <rect x="16" y="24" width="120" height="12" rx="3" fill="#cbd5e1"/>
+  <rect x="16" y="56" width="72" height="96" rx="8" fill="#fff" stroke="#e2e8f0"/>
+  <rect x="24" y="64" width="56" height="48" rx="4" fill="#dbeafe"/>
+  <rect x="24" y="120" width="48" height="8" rx="2" fill="#cbd5e1"/>
+  <rect x="96" y="56" width="72" height="96" rx="8" fill="#fff" stroke="#e2e8f0"/>
+  <rect x="104" y="64" width="56" height="48" rx="4" fill="#fce7f3"/>
+  <rect x="104" y="120" width="48" height="8" rx="2" fill="#cbd5e1"/>
+  <rect x="176" y="56" width="72" height="96" rx="8" fill="#fff" stroke="#e2e8f0"/>
+  <rect x="184" y="64" width="56" height="48" rx="4" fill="#dcfce7"/>
+  <rect x="184" y="120" width="48" height="8" rx="2" fill="#cbd5e1"/>
+  <rect x="248" y="56" width="56" height="96" rx="8" fill="#fff" stroke="#e2e8f0"/>
+  <rect x="256" y="64" width="40" height="48" rx="4" fill="#fef3c7"/>
+</svg>

package/dist/agent-kit/aiditor/thumbnails/wix-stores/product-page.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="320" height="240" viewBox="0 0 320 240" fill="none">
+  <rect width="320" height="240" fill="#f4f7fb"/>
+  <rect x="16" y="16" width="288" height="28" rx="6" fill="#e2e8f0"/>
+  <rect x="16" y="56" width="120" height="12" rx="3" fill="#cbd5e1"/>
+  <rect x="16" y="76" width="88" height="10" rx="3" fill="#e2e8f0"/>
+  <rect x="16" y="104" width="136" height="120" rx="8" fill="#dbeafe" stroke="#93c5fd"/>
+  <rect x="168" y="104" width="136" height="16" rx="4" fill="#cbd5e1"/>
+  <rect x="168" y="128" width="96" height="10" rx="3" fill="#e2e8f0"/>
+  <rect x="168" y="148" width="72" height="10" rx="3" fill="#e2e8f0"/>
+  <rect x="168" y="180" width="88" height="28" rx="6" fill="#2563eb"/>
+  <text x="188" y="198" fill="#fff" font-family="system-ui,sans-serif" font-size="11">Add to cart</text>
+</svg>

package/dist/agent-kit/aiditor/thumbnails/wix-stores/product-search.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="320" height="240" viewBox="0 0 320 240" fill="none">
+  <rect width="320" height="240" fill="#f8fafc"/>
+  <rect x="16" y="16" width="200" height="24" rx="6" fill="#fff" stroke="#cbd5e1"/>
+  <rect x="24" y="24" width="64" height="8" rx="2" fill="#e2e8f0"/>
+  <g>
+    <rect x="16" y="56" width="88" height="88" rx="8" fill="#fff" stroke="#e2e8f0"/>
+    <rect x="24" y="64" width="72" height="48" rx="4" fill="#dbeafe"/>
+    <rect x="24" y="120" width="56" height="8" rx="2" fill="#cbd5e1"/>
+    <rect x="112" y="56" width="88" height="88" rx="8" fill="#fff" stroke="#e2e8f0"/>
+    <rect x="120" y="64" width="72" height="48" rx="4" fill="#fce7f3"/>
+    <rect x="120" y="120" width="56" height="8" rx="2" fill="#cbd5e1"/>
+    <rect x="208" y="56" width="88" height="88" rx="8" fill="#fff" stroke="#e2e8f0"/>
+    <rect x="216" y="64" width="72" height="48" rx="4" fill="#dcfce7"/>
+    <rect x="216" y="120" width="56" height="8" rx="2" fill="#cbd5e1"/>
+  </g>
+  <rect x="16" y="160" width="288" height="64" rx="8" fill="#fff" stroke="#e2e8f0"/>
+</svg>

package/dist/contracts/category-products.jay-contract

@@ -0,0 +1,31 @@
+name: category-products
+description: Products from a specific category. Use for category product showcases, or as related products on a product page (pass productId to exclude the current product).
+props:
+  - name: productId
+    type: string
+    description: Product ID to exclude from results (optional, use for related products)
+  - name: categorySlug
+    type: string
+    description: Category slug to filter products by
+  - name: limit
+    type: number
+    description: Maximum number of products to show (default 4)
+tags:
+  - tag: products
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    phase: fast+interactive
+    description: Product cards from the category
+    link: ./product-card
+
+  - tag: hasProducts
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether there are products to show
+
+  - tag: categoryName
+    type: data
+    dataType: string
+    description: Name of the category these products belong to

package/dist/contracts/category-products.jay-contract.d.ts

@@ -0,0 +1,36 @@
+import {JayContract} from "@jay-framework/runtime";
+import {ProductCardViewState, ProductCardRefs, ProductCardRepeatedRefs} from "./product-card.jay-contract";
+
+export interface CategoryProductsViewState {
+  products: Array<ProductCardViewState>,
+  hasProducts: boolean,
+  categoryName: string
+}
+
+export type CategoryProductsSlowViewState = Pick<CategoryProductsViewState, 'categoryName'>;
+
+export type CategoryProductsFastViewState = Pick<CategoryProductsViewState, 'hasProducts'> & {
+    products: Array<CategoryProductsViewState['products'][number]>;
+};
+
+export type CategoryProductsInteractiveViewState = Pick<CategoryProductsViewState, 'hasProducts'> & {
+    products: Array<CategoryProductsViewState['products'][number]>;
+};
+
+
+export interface CategoryProductsRefs {
+  products: ProductCardRepeatedRefs
+}
+
+
+export interface CategoryProductsRepeatedRefs {
+  products: ProductCardRepeatedRefs
+}
+
+export interface CategoryProductsProps {
+  productId?: string;
+  categorySlug?: string;
+  limit?: number;
+}
+
+export type CategoryProductsContract = JayContract<CategoryProductsViewState, CategoryProductsRefs, CategoryProductsSlowViewState, CategoryProductsFastViewState, CategoryProductsInteractiveViewState, CategoryProductsProps>

package/dist/contracts/product-spotlight.jay-contract

@@ -0,0 +1,16 @@
+name: product-spotlight
+description: A single product card by slug. Use to feature a specific product on any page (homepage, content pages, etc.).
+props:
+  - name: slug
+    type: string
+    description: Product slug to display
+tags:
+  - tag: product
+    type: sub-contract
+    description: The product card
+    link: ./product-card
+
+  - tag: hasProduct
+    type: variant
+    dataType: boolean
+    description: Whether the product was found

package/dist/contracts/product-spotlight.jay-contract.d.ts

@@ -0,0 +1,61 @@
+import {JayContract} from "@jay-framework/runtime";
+import {ProductCardViewState, ProductCardRefs, ProductCardRepeatedRefs} from "./product-card.jay-contract";
+
+export interface ProductSpotlightViewState {
+  product: ProductCardViewState,
+  hasProduct: boolean
+}
+
+export type ProductSpotlightSlowViewState = Pick<ProductSpotlightViewState, 'hasProduct'> & {
+    product: Pick<ProductSpotlightViewState['product'], '_id' | 'name' | 'slug' | 'productUrl' | 'categoryPrefix' | 'hasDiscount' | 'hasRibbon' | 'productType' | 'quickAddType'> & {
+    mainMedia: ProductSpotlightViewState['product']['mainMedia'];
+    thumbnail: ProductSpotlightViewState['product']['thumbnail'];
+    inventory: ProductSpotlightViewState['product']['inventory'];
+    ribbon: ProductSpotlightViewState['product']['ribbon'];
+    brand: ProductSpotlightViewState['product']['brand'];
+    quickOption: Pick<ProductSpotlightViewState['product']['quickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode'>>;
+};
+    secondQuickOption: Pick<ProductSpotlightViewState['product']['secondQuickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode'>>;
+};
+};
+};
+
+export type ProductSpotlightFastViewState = {
+    product: Pick<ProductSpotlightViewState['product'], 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+    secondQuickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+};
+
+export type ProductSpotlightInteractiveViewState = {
+    product: Pick<ProductSpotlightViewState['product'], 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+    secondQuickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+};
+
+
+export interface ProductSpotlightRefs {
+  product: ProductCardRefs
+}
+
+
+export interface ProductSpotlightRepeatedRefs {
+  product: ProductCardRepeatedRefs
+}
+
+export interface ProductSpotlightProps {
+  slug?: string;
+}
+
+export type ProductSpotlightContract = JayContract<ProductSpotlightViewState, ProductSpotlightRefs, ProductSpotlightSlowViewState, ProductSpotlightFastViewState, ProductSpotlightInteractiveViewState, ProductSpotlightProps>

package/dist/index.client.js

@@ -886,7 +886,7 @@ function ProductSearchInteractive(props, refs, viewStateSignals, fastCarryForwar
   };
 }
 const productSearch = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(ProductSearchInteractive);
-function RelatedProductsInteractive(_props, refs, viewStateSignals, _fastCarryForward, storesContext) {
+function CategoryProductsInteractive(_props, refs, viewStateSignals, _fastCarryForward, storesContext) {
   const { products: [products, setProducts], hasProducts: [hasProducts] } = viewStateSignals;
   setupCardInteractions(refs.products, { get: products, set: setProducts }, storesContext);
   return {
@@ -896,7 +896,34 @@ function RelatedProductsInteractive(_props, refs, viewStateSignals, _fastCarryFo
     })
   };
 }
-const relatedProducts = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(RelatedProductsInteractive);
+const categoryProducts = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(CategoryProductsInteractive);
+function ProductSpotlightInteractive(_props, refs, viewStateSignals, fastCarryForward, storesContext) {
+  const { product: [product, setProduct] } = viewStateSignals;
+  const fullProduct = fastCarryForward.product;
+  refs.product.addToCartButton.onclick(async () => {
+    if (!fullProduct._id || fullProduct.quickAddType !== QuickAddType.SIMPLE)
+      return;
+    setProduct({ ...product(), isAddingToCart: true });
+    try {
+      await storesContext.addToCart(fullProduct._id, 1);
+    } catch (error) {
+      console.error("Failed to add to cart:", error);
+    } finally {
+      setProduct({ ...product(), isAddingToCart: false });
+    }
+  });
+  refs.product.viewOptionsButton.onclick(() => {
+    if (fullProduct.productUrl) {
+      window.location.href = fullProduct.productUrl;
+    }
+  });
+  return {
+    render: () => ({
+      product: product()
+    })
+  };
+}
+const productSpotlight = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(ProductSpotlightInteractive);
 const categoryList = makeJayStackComponent().withProps();
 const init = makeJayInit().withClient(async (data) => {
   console.log("[wix-stores] Initializing client-side stores context...");
@@ -909,9 +936,10 @@ export {
   cartIndicator,
   cartPage,
   categoryList,
+  categoryProducts,
   init,
   productPage,
   productSearch,
-  provideWixStoresContext,
-  relatedProducts
+  productSpotlight,
+  provideWixStoresContext
 };

package/dist/index.d.ts

@@ -41,6 +41,13 @@ interface ProductOptionsViewState {
 }
 
 
+interface ProductOptionsRefs {
+  choices: {
+    choiceButton: HTMLElementCollectionProxy<ChoiceOfProductOptionsViewState, HTMLButtonElement>
+  }
+}
+
+
 interface ProductOptionsRepeatedRefs {
   choices: {
     choiceButton: HTMLElementCollectionProxy<ChoiceOfProductOptionsViewState, HTMLButtonElement>
@@ -127,6 +134,16 @@ interface ProductCardViewState {
 }
 
 
+interface ProductCardRefs {
+  productLink: HTMLElementProxy<ProductCardViewState, HTMLAnchorElement>,
+  addToCartButton: HTMLElementProxy<ProductCardViewState, HTMLButtonElement>,
+  cardContainer: HTMLElementProxy<ProductCardViewState, HTMLElement>,
+  viewOptionsButton: HTMLElementProxy<ProductCardViewState, HTMLButtonElement>,
+  quickOption: ProductOptionsRefs,
+  secondQuickOption: ProductOptionsRefs
+}
+
+
 interface ProductCardRepeatedRefs {
   productLink: HTMLElementCollectionProxy<ProductCardViewState, HTMLAnchorElement>,
   addToCartButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
@@ -470,6 +487,8 @@ interface WixStoresService {
     getCustomizations(): Promise<Customization[]>;
     /** Get cached data extension schemas for products. Lazily loaded. */
     getDataExtensionSchemas(): Promise<DataExtensionSchema[]>;
+    /** Get the "All Products" system category ID. Lazily fetched and cached. */
+    getAllProductsCategoryId(): Promise<string | null>;
 }
 /**
  * Server service marker for Wix Stores.
@@ -865,36 +884,92 @@ interface ProductFastCarryForward {
  */
 declare const productPage: _jay_framework_fullstack_component.JayStackComponentDefinition<ProductPageRefs, ProductPageSlowViewState, ProductPageFastViewState, ProductPageInteractiveViewState, [ProductSlowCarryForward, WixStoresService], [Signals<ProductPageFastViewState>, ProductFastCarryForward, WixStoresContext], PageProps & ProductPageParams, ProductPageParams, _jay_framework_component.JayComponentCore<PageProps & ProductPageParams, ProductPageInteractiveViewState>>;
 
-interface RelatedProductsViewState {
+interface CategoryProductsViewState {
   products: Array<ProductCardViewState>,
   hasProducts: boolean,
   categoryName: string
 }
 
-type RelatedProductsSlowViewState = Pick<RelatedProductsViewState, 'categoryName'>;
+type CategoryProductsSlowViewState = Pick<CategoryProductsViewState, 'categoryName'>;
 
-type RelatedProductsFastViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
-    products: Array<RelatedProductsViewState['products'][number]>;
+type CategoryProductsFastViewState = Pick<CategoryProductsViewState, 'hasProducts'> & {
+    products: Array<CategoryProductsViewState['products'][number]>;
 };
 
-type RelatedProductsInteractiveViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
-    products: Array<RelatedProductsViewState['products'][number]>;
+type CategoryProductsInteractiveViewState = Pick<CategoryProductsViewState, 'hasProducts'> & {
+    products: Array<CategoryProductsViewState['products'][number]>;
 };
 
 
-interface RelatedProductsRefs {
+interface CategoryProductsRefs {
   products: ProductCardRepeatedRefs
 }
 
-interface RelatedProductsProps {
-    productId: string;
+interface CategoryProductsProps {
+    productId?: string;
     categorySlug?: string;
     limit?: number;
 }
-interface RelatedSlowCarryForward {
+interface SlowCarryForward {
     products: ProductCardViewState[];
 }
-declare const relatedProducts: _jay_framework_fullstack_component.JayStackComponentDefinition<RelatedProductsRefs, RelatedProductsSlowViewState, RelatedProductsFastViewState, RelatedProductsInteractiveViewState, [RelatedSlowCarryForward, WixStoresService], [Signals<RelatedProductsFastViewState>, Record<string, never>, WixStoresContext], PageProps & RelatedProductsProps, {}, _jay_framework_component.JayComponentCore<PageProps & RelatedProductsProps, RelatedProductsInteractiveViewState>>;
+declare const categoryProducts: _jay_framework_fullstack_component.JayStackComponentDefinition<CategoryProductsRefs, CategoryProductsSlowViewState, CategoryProductsFastViewState, CategoryProductsInteractiveViewState, [SlowCarryForward, WixStoresService], [Signals<CategoryProductsFastViewState>, Record<string, never>, WixStoresContext], PageProps & CategoryProductsProps, {}, _jay_framework_component.JayComponentCore<PageProps & CategoryProductsProps, CategoryProductsInteractiveViewState>>;
+
+interface ProductSpotlightViewState {
+  product: ProductCardViewState,
+  hasProduct: boolean
+}
+
+type ProductSpotlightSlowViewState = Pick<ProductSpotlightViewState, 'hasProduct'> & {
+    product: Pick<ProductSpotlightViewState['product'], '_id' | 'name' | 'slug' | 'productUrl' | 'categoryPrefix' | 'hasDiscount' | 'hasRibbon' | 'productType' | 'quickAddType'> & {
+    mainMedia: ProductSpotlightViewState['product']['mainMedia'];
+    thumbnail: ProductSpotlightViewState['product']['thumbnail'];
+    inventory: ProductSpotlightViewState['product']['inventory'];
+    ribbon: ProductSpotlightViewState['product']['ribbon'];
+    brand: ProductSpotlightViewState['product']['brand'];
+    quickOption: Pick<ProductSpotlightViewState['product']['quickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode'>>;
+};
+    secondQuickOption: Pick<ProductSpotlightViewState['product']['secondQuickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode'>>;
+};
+};
+};
+
+type ProductSpotlightFastViewState = {
+    product: Pick<ProductSpotlightViewState['product'], 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+    secondQuickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+};
+
+type ProductSpotlightInteractiveViewState = {
+    product: Pick<ProductSpotlightViewState['product'], 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+    secondQuickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+};
+
+
+interface ProductSpotlightRefs {
+  product: ProductCardRefs
+}
+
+interface ProductSpotlightProps {
+    slug: string;
+}
+interface SpotlightCarryForward {
+    product: ProductCardViewState;
+}
+declare const productSpotlight: _jay_framework_fullstack_component.JayStackComponentDefinition<ProductSpotlightRefs, ProductSpotlightSlowViewState, ProductSpotlightFastViewState, ProductSpotlightInteractiveViewState, [SpotlightCarryForward, WixStoresService], [Signals<ProductSpotlightFastViewState>, SpotlightCarryForward, WixStoresContext], PageProps & ProductSpotlightProps, {}, _jay_framework_component.JayComponentCore<PageProps & ProductSpotlightProps, ProductSpotlightInteractiveViewState>>;
 
 interface CategoryOfCategoryListViewState {
   _id: string,
@@ -1065,4 +1140,4 @@ declare function generateWixStoresReferences(ctx: PluginReferencesContext): Prom
  */
 declare const generator: _jay_framework_fullstack_component.DynamicContractGenerator<[WixStoresService]>;
 
-export { type CategoryListParams, type CategoryTree, type GetProductBySlugInput, type ProductPageParams, type ProductSearchParams, type RelatedProductsProps, WIX_STORES_CONTEXT, WIX_STORES_SERVICE_MARKER, type WixStoresContext, type WixStoresInitData, type WixStoresService, type WixStoresServiceOptions, buildCategoryUrl, buildProductUrl, categoryList, findCategoryImage, findRootCategoryId, findRootCategorySlug, generateWixStoresReferences, getCategories, getProductBySlug, getVariantStock, init, productPage, generator as productPageContractGenerator, productSearch, provideWixStoresService, relatedProducts, searchProducts, setupWixStores };
+export { type CategoryListParams, type CategoryProductsProps, type CategoryTree, type GetProductBySlugInput, type ProductPageParams, type ProductSearchParams, type ProductSpotlightProps, WIX_STORES_CONTEXT, WIX_STORES_SERVICE_MARKER, type WixStoresContext, type WixStoresInitData, type WixStoresService, type WixStoresServiceOptions, buildCategoryUrl, buildProductUrl, categoryList, categoryProducts, findCategoryImage, findRootCategoryId, findRootCategorySlug, generateWixStoresReferences, getCategories, getProductBySlug, getVariantStock, init, productPage, generator as productPageContractGenerator, productSearch, productSpotlight, provideWixStoresService, searchProducts, setupWixStores };

package/dist/index.js

@@ -60,6 +60,7 @@ function provideWixStoresService(wixClient, options) {
   let cachedTree = null;
   let cachedCustomizations = null;
   let cachedExtensionSchemas = null;
+  let cachedAllProductsCategoryId;
   const categoriesClient = getCategoriesClient(wixClient);
   const customizationsClient = getCustomizationsV3Client(wixClient);
   const service = {
@@ -134,6 +135,17 @@ function provideWixStoresService(wixClient, options) {
         cachedExtensionSchemas = [];
       }
       return cachedExtensionSchemas;
+    },
+    async getAllProductsCategoryId() {
+      if (cachedAllProductsCategoryId !== void 0) return cachedAllProductsCategoryId;
+      try {
+        const result = await service.products.getAllProductsCategory();
+        cachedAllProductsCategoryId = result.categoryId ?? null;
+      } catch (error) {
+        console.error("[wix-stores] Failed to get All Products category:", error);
+        cachedAllProductsCategoryId = null;
+      }
+      return cachedAllProductsCategoryId;
     }
   };
   registerService(WIX_STORES_SERVICE_MARKER, service);
@@ -716,6 +728,7 @@ const getProductBySlug = makeJayQuery("wixStores.getProductBySlug").withServices
       const fields = [
         "MEDIA_ITEMS_INFO",
         "VARIANT_OPTION_CHOICE_NAMES",
+        "CURRENCY",
         ...needsCategoryInfo(wixStores) ? ["ALL_CATEGORIES_INFO"] : []
       ];
       const result = await wixStores.products.getProductBySlug(slug, {
@@ -878,7 +891,10 @@ const EMPTY_CATEGORY_HEADER = {
 };
 async function findCategoryBySlug$1(categoriesClient, slug) {
   const result = await categoriesClient.queryCategories({ treeReference: { appNamespace: "@wix/stores" } }).eq("slug", slug).eq("visible", true).limit(1).find();
-  return result.items?.[0] ?? null;
+  const cat = result.items?.[0];
+  if (!cat?._id)
+    return null;
+  return loadCategoryDetails(categoriesClient, cat._id);
 }
 async function loadCategoryDetails(categoriesClient, categoryId) {
   try {
@@ -888,8 +904,7 @@ async function loadCategoryDetails(categoriesClient, categoryId) {
   }
 }
 async function buildCategoryHeader(wixStoreService, category, categoryUrlTemplate) {
-  const details = await loadCategoryDetails(wixStoreService.categories, category._id);
-  const cat = details || category;
+  const cat = category;
   const imageUrl = cat.image ? formatWixMediaUrl("", cat.image) : "";
   const description = cat.description || "";
   const categoryTree = await wixStoreService.getCategoryTree();
@@ -955,21 +970,19 @@ async function buildCategoryHeader(wixStoreService, category, categoryUrlTemplat
   }
   return header;
 }
-async function renderSlowlyChanging$3(props, wixStores) {
+async function renderSlowlyChanging$4(props, wixStores) {
   const Pipeline = RenderPipeline.for();
   const categorySlug = props.category ?? null;
-  const prefixSlug = props.prefix ?? null;
-  const defaultCategorySlug = wixStores.defaultCategory;
   let activeCategory = null;
   let baseCategoryId = null;
   if (categorySlug) {
     activeCategory = await findCategoryBySlug$1(wixStores.categories, categorySlug);
     baseCategoryId = activeCategory?._id ?? null;
-  } else if (prefixSlug) {
-    activeCategory = await findCategoryBySlug$1(wixStores.categories, prefixSlug);
-    baseCategoryId = activeCategory?._id ?? null;
-  } else if (defaultCategorySlug) {
-    activeCategory = await findCategoryBySlug$1(wixStores.categories, defaultCategorySlug);
+  } else {
+    const allProductsCategoryId = await wixStores.getAllProductsCategoryId();
+    if (allProductsCategoryId) {
+      activeCategory = await loadCategoryDetails(wixStores.categories, allProductsCategoryId);
+    }
   }
   const tree = await wixStores.getCategoryTree();
   const categoryHeader = activeCategory ? await buildCategoryHeader(wixStores, activeCategory, wixStores.urls.category) : EMPTY_CATEGORY_HEADER;
@@ -1028,7 +1041,7 @@ async function renderSlowlyChanging$3(props, wixStores) {
     };
   });
 }
-async function renderFastChanging$2(props, slowCarryForward, _wixStores) {
+async function renderFastChanging$3(props, slowCarryForward, _wixStores) {
   const Pipeline = RenderPipeline.for();
   const urlFilters = parseUrlFilters(props.url);
   const initialSort = parseSortParam(urlFilters.sort);
@@ -1155,12 +1168,13 @@ async function* loadSearchParams([wixStores]) {
       if (rootSlug) {
         params.push({ prefix: rootSlug, category: node.slug });
       } else {
-        params.push({ prefix: node.slug });
+        params.push({ category: node.slug });
       }
       for (const child of node.children) {
         collectParams(child, rootSlug ?? node.slug);
       }
     };
+    const allProductsCategoryId = await wixStores.getAllProductsCategoryId();
     const allCategories = [];
     let result = await wixStores.categories.queryCategories({
       treeReference: { appNamespace: "@wix/stores" }
@@ -1176,6 +1190,8 @@ async function* loadSearchParams([wixStores]) {
     for (const cat of allCategories) {
       if (!cat._id)
         continue;
+      if (cat._id === allProductsCategoryId)
+        continue;
       const node = {
         slug: cat.slug || "",
         itemCount: cat.itemCounter ?? 0,
@@ -1205,7 +1221,7 @@ async function* loadSearchParams([wixStores]) {
     for (const root of roots) {
       sumItems(root);
     }
-    const params = [];
+    const params = [{}];
     for (const root of roots) {
       collectParams(root, null);
     }
@@ -1215,7 +1231,7 @@ async function* loadSearchParams([wixStores]) {
     yield [];
   }
 }
-const productSearch = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadSearchParams).withSlowlyRender(renderSlowlyChanging$3).withFastRender(renderFastChanging$2);
+const productSearch = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadSearchParams).withSlowlyRender(renderSlowlyChanging$4).withFastRender(renderFastChanging$3);
 var ProductType = /* @__PURE__ */ ((ProductType2) => {
   ProductType2[ProductType2["PHYSICAL"] = 0] = "PHYSICAL";
   ProductType2[ProductType2["DIGITAL"] = 1] = "DIGITAL";
@@ -1449,7 +1465,7 @@ function mapVariants(variantsInfo) {
     strikethroughPrice: variant.price.compareAtPrice?.formattedAmount || ""
   })) || [];
 }
-async function renderSlowlyChanging$2(props, wixStores) {
+async function renderSlowlyChanging$3(props, wixStores) {
   const Pipeline = RenderPipeline.for();
   const template = wixStores.urls.product;
   const needsCategories = template.includes("{category}") || template.includes("{prefix}");
@@ -1505,7 +1521,7 @@ async function renderSlowlyChanging$2(props, wixStores) {
     };
   });
 }
-async function renderFastChanging$1(props, slowCarryForward, wixStores) {
+async function renderFastChanging$2(props, slowCarryForward, wixStores) {
   const Pipeline = RenderPipeline.for();
   const { variants } = slowCarryForward;
   const defaultVariant = variants.find((v) => v.inventoryStatus === StockStatus.IN_STOCK) || variants[0];
@@ -1555,9 +1571,9 @@ async function renderFastChanging$1(props, slowCarryForward, wixStores) {
     }
   }));
 }
-const productPage = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadProductParams).withSlowlyRender(renderSlowlyChanging$2).withFastRender(renderFastChanging$1);
+const productPage = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadProductParams).withSlowlyRender(renderSlowlyChanging$3).withFastRender(renderFastChanging$2);
 const DEFAULT_LIMIT = 4;
-async function renderSlowlyChanging$1(props, wixStores) {
+async function renderSlowlyChanging$2(props, wixStores) {
   const Pipeline = RenderPipeline.for();
   const limit = props.limit ?? DEFAULT_LIMIT;
   const categorySlug = props.categorySlug;
@@ -1601,7 +1617,7 @@ async function renderSlowlyChanging$1(props, wixStores) {
     carryForward: { products }
   }));
 }
-async function renderFastChanging(_props, slowCarryForward, _wixStores) {
+async function renderFastChanging$1(_props, slowCarryForward, _wixStores) {
   const Pipeline = RenderPipeline.for();
   const { products } = slowCarryForward;
   return Pipeline.ok({
@@ -1609,7 +1625,95 @@ async function renderFastChanging(_props, slowCarryForward, _wixStores) {
     hasProducts: products.length > 0
   }).toPhaseOutput((viewState) => ({ viewState, carryForward: {} }));
 }
-const relatedProducts = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withSlowlyRender(renderSlowlyChanging$1).withFastRender(renderFastChanging);
+const categoryProducts = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withSlowlyRender(renderSlowlyChanging$2).withFastRender(renderFastChanging$1);
+async function renderSlowlyChanging$1(props, _wixStores) {
+  const Pipeline = RenderPipeline.for();
+  return Pipeline.try(async () => {
+    if (!props.slug) {
+      throw new Error("No product slug provided");
+    }
+    const card = await getProductBySlug({ slug: props.slug });
+    if (!card) {
+      throw new Error(`Product not found: ${props.slug}`);
+    }
+    return card;
+  }).recover((error) => {
+    return handleError(error);
+  }).toPhaseOutput((product) => {
+    return {
+      viewState: {
+        hasProduct: true,
+        product: {
+          _id: product._id,
+          name: product.name,
+          slug: product.slug,
+          productUrl: product.productUrl,
+          categoryPrefix: product.categoryPrefix,
+          mainMedia: product.mainMedia,
+          thumbnail: product.thumbnail,
+          hasDiscount: product.hasDiscount,
+          inventory: product.inventory,
+          ribbon: product.ribbon,
+          hasRibbon: product.hasRibbon,
+          brand: product.brand,
+          productType: product.productType,
+          quickAddType: product.quickAddType,
+          quickOption: {
+            _id: product.quickOption?._id,
+            name: product.quickOption?.name,
+            optionRenderType: product.quickOption?.optionRenderType,
+            choices: (product.quickOption?.choices ?? []).map((c) => ({
+              choiceId: c.choiceId,
+              name: c.name,
+              choiceType: c.choiceType,
+              colorCode: c.colorCode
+            }))
+          },
+          secondQuickOption: {
+            _id: product.secondQuickOption?._id,
+            name: product.secondQuickOption?.name,
+            optionRenderType: product.secondQuickOption?.optionRenderType,
+            choices: (product.secondQuickOption?.choices ?? []).map((c) => ({
+              choiceId: c.choiceId,
+              name: c.name,
+              choiceType: c.choiceType,
+              colorCode: c.colorCode
+            }))
+          }
+        }
+      },
+      carryForward: { product }
+    };
+  });
+}
+async function renderFastChanging(_props, carryForward, _wixStores) {
+  const Pipeline = RenderPipeline.for();
+  const { product } = carryForward;
+  return Pipeline.ok({
+    product: {
+      price: product.price,
+      strikethroughPrice: product.strikethroughPrice,
+      isAddingToCart: false,
+      quickOption: {
+        choices: (product.quickOption?.choices ?? []).map((c) => ({
+          choiceId: c.choiceId,
+          inStock: c.inStock,
+          isSelected: c.isSelected
+        }))
+      },
+      secondQuickOption: {
+        choices: (product.secondQuickOption?.choices ?? []).map((c) => ({
+          choiceId: c.choiceId,
+          inStock: c.inStock,
+          isSelected: c.isSelected
+        }))
+      }
+    }
+  }).toPhaseOutput((viewState) => {
+    return { viewState, carryForward: { product } };
+  });
+}
+const productSpotlight = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withSlowlyRender(renderSlowlyChanging$1).withFastRender(renderFastChanging);
 async function findCategoryBySlug(categoriesClient, slug) {
   const result = await categoriesClient.queryCategories({ treeReference: { appNamespace: "@wix/stores" } }).eq("slug", slug).eq("visible", true).limit(1).find();
   return result.items?.[0] ?? null;
@@ -1807,12 +1911,12 @@ function buildCategoryPrompt(config, entry) {
     );
   }
   lines.push(
-    `  related-products — pass categorySlug="${node.slug}" alongside a productId when showing related items in this category`,
+    `  category-products — pass categorySlug="${node.slug}" to show products from this category; optionally pass productId to exclude a product`,
     "",
     "Contracts:",
     "  agent-kit/materialized-contracts/wix-stores/product-search.jay-contract",
     "  agent-kit/materialized-contracts/wix-stores/category-list.jay-contract",
-    "  agent-kit/materialized-contracts/wix-stores/related-products.jay-contract",
+    "  agent-kit/materialized-contracts/wix-stores/category-products.jay-contract",
     "",
     "Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md."
   );
@@ -1843,16 +1947,39 @@ function buildCategoryAddMenuItems(roots, config) {
     prompt: buildCategoryPrompt(config, entry)
   }));
 }
+const PUBLIC_THUMBNAIL_ROOT = path.join("public", "aiditor-add-menu-thumbnails");
+function copyAiditorAddMenuThumbnails(ctx, resolvePackagePath, pluginName) {
+  const sourceDir = resolvePackagePath(
+    path.join("agent-kit", "aiditor", "thumbnails", pluginName)
+  );
+  if (!fs.existsSync(sourceDir)) return [];
+  const destDir = path.join(ctx.projectRoot, PUBLIC_THUMBNAIL_ROOT, pluginName);
+  const created = [];
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const src = path.join(sourceDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+    if (!fs.existsSync(dest) || ctx.force) {
+      fs.copyFileSync(src, dest);
+      created.push(path.posix.join(PUBLIC_THUMBNAIL_ROOT, pluginName, entry.name));
+    }
+  }
+  return created;
+}
 const CONFIG_FILE_NAME = ".wix-stores.yaml";
 const ADD_MENU_OUTPUT_REL = "agent-kit/aiditor/add-menu/wix-stores.yaml";
 const ADD_MENU_GENERATED_REL = "agent-kit/aiditor/add-menu/wix-stores.generated.yaml";
-function resolveAddMenuTemplatePath() {
+function resolvePackageAgentKitPath(relativePath) {
   const thisDir = path.dirname(fileURLToPath(import.meta.url));
-  const fromDist = path.join(thisDir, "agent-kit/aiditor/add-menu.template.yaml");
+  const fromDist = path.join(thisDir, relativePath);
   if (fs.existsSync(fromDist)) {
     return fromDist;
   }
-  return path.join(thisDir, "..", "agent-kit/aiditor/add-menu.template.yaml");
+  return path.join(thisDir, "..", relativePath);
+}
+function resolveAddMenuTemplatePath() {
+  return resolvePackageAgentKitPath("agent-kit/aiditor/add-menu.template.yaml");
 }
 function writeAddMenuCatalog(ctx) {
   const outputPath = path.join(ctx.projectRoot, ADD_MENU_OUTPUT_REL);
@@ -1933,6 +2060,9 @@ async function setupWixStores(ctx) {
   if (addMenuCreated) {
     configCreated.push(addMenuCreated);
   }
+  configCreated.push(
+    ...copyAiditorAddMenuThumbnails(ctx, resolvePackageAgentKitPath, "wix-stores")
+  );
   const message = `Wix Stores configured (product URL: ${service.urls.product})`;
   return {
     status: "configured",
@@ -2276,6 +2406,7 @@ export {
   cartIndicator,
   cartPage,
   categoryList,
+  categoryProducts,
   findCategoryImage,
   findRootCategoryId,
   findRootCategorySlug,
@@ -2287,10 +2418,10 @@ export {
   productPage,
   generator as productPageContractGenerator,
   productSearch,
+  productSpotlight,
   provideWixCartContext,
   provideWixCartService,
   provideWixStoresService,
-  relatedProducts,
   searchProducts,
   setupWixStores
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/wix-stores",
-  "version": "0.19.6",
+  "version": "0.20.0",
   "type": "module",
   "description": "Wix Stores API client for Jay Framework",
   "license": "Apache-2.0",
@@ -17,7 +17,8 @@
     "./media.jay-contract": "./dist/contracts/media.jay-contract",
     "./media-gallery.jay-contract": "./dist/contracts/media-gallery.jay-contract",
     "./product-search.jay-contract": "./dist/contracts/product-search.jay-contract",
-    "./related-products.jay-contract": "./dist/contracts/related-products.jay-contract",
+    "./category-products.jay-contract": "./dist/contracts/category-products.jay-contract",
+    "./product-spotlight.jay-contract": "./dist/contracts/product-spotlight.jay-contract",
     "./category-list.jay-contract": "./dist/contracts/category-list.jay-contract",
     "./search-products.jay-action": "./dist/actions/search-products.jay-action",
     "./get-product-by-slug.jay-action": "./dist/actions/get-product-by-slug.jay-action",
@@ -30,7 +31,7 @@
     "validate": "jay-stack-cli validate-plugin",
     "build:client": "vite build",
     "build:server": "vite build --ssr",
-    "build:copy-contract": "mkdir -p dist/contracts && cp lib/contracts/*.jay-contract* dist/contracts/ && mkdir -p dist/actions && cp lib/actions/*.jay-action dist/actions/ && mkdir -p dist/agent-kit/aiditor && cp agent-kit/aiditor/add-menu.template.yaml dist/agent-kit/aiditor/",
+    "build:copy-contract": "mkdir -p dist/contracts && cp lib/contracts/*.jay-contract* dist/contracts/ && mkdir -p dist/actions && cp lib/actions/*.jay-action dist/actions/ && mkdir -p dist/agent-kit/aiditor && cp agent-kit/aiditor/add-menu.template.yaml dist/agent-kit/aiditor/ && cp -R agent-kit/aiditor/thumbnails dist/agent-kit/aiditor/",
     "build:types": "tsup lib/index.ts --dts-only --format esm",
     "build:check-types": "tsc",
     "clean": "rimraf dist",
@@ -38,16 +39,16 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.19.6",
-    "@jay-framework/fullstack-component": "^0.19.6",
-    "@jay-framework/reactive": "^0.19.6",
-    "@jay-framework/runtime": "^0.19.6",
-    "@jay-framework/secure": "^0.19.6",
-    "@jay-framework/stack-client-runtime": "^0.19.6",
-    "@jay-framework/stack-server-runtime": "^0.19.6",
-    "@jay-framework/wix-cart": "^0.19.6",
-    "@jay-framework/wix-server-client": "^0.19.6",
-    "@jay-framework/wix-utils": "^0.19.6",
+    "@jay-framework/component": "^0.20.0",
+    "@jay-framework/fullstack-component": "^0.20.0",
+    "@jay-framework/reactive": "^0.20.0",
+    "@jay-framework/runtime": "^0.20.0",
+    "@jay-framework/secure": "^0.20.0",
+    "@jay-framework/stack-client-runtime": "^0.20.0",
+    "@jay-framework/stack-server-runtime": "^0.20.0",
+    "@jay-framework/wix-cart": "^0.20.0",
+    "@jay-framework/wix-server-client": "^0.20.0",
+    "@jay-framework/wix-utils": "^0.20.0",
     "@wix/categories": "^1.0.185",
     "@wix/data-extension-schema": "^1.0.221",
     "@wix/sdk": "^1.21.5",
@@ -59,10 +60,10 @@
     "@babel/core": "^7.23.7",
     "@babel/preset-env": "^7.23.8",
     "@babel/preset-typescript": "^7.23.3",
-    "@jay-framework/compiler-jay-stack": "^0.19.6",
-    "@jay-framework/jay-cli": "^0.19.6",
-    "@jay-framework/jay-stack-cli": "^0.19.6",
-    "@jay-framework/vite-plugin": "^0.19.6",
+    "@jay-framework/compiler-jay-stack": "^0.20.0",
+    "@jay-framework/jay-cli": "^0.20.0",
+    "@jay-framework/jay-stack-cli": "^0.20.0",
+    "@jay-framework/vite-plugin": "^0.20.0",
     "nodemon": "^3.0.3",
     "rimraf": "^5.0.5",
     "tslib": "^2.6.2",

package/plugin.yaml

@@ -7,10 +7,14 @@ contracts:
     component: productSearch
     description: Headless product search page
   # category-page removed — use product-search with prefix/category params instead
-  - name: related-products
-    contract: related-products.jay-contract
-    component: relatedProducts
-    description: Related products from the same category
+  - name: category-products
+    contract: category-products.jay-contract
+    component: categoryProducts
+    description: Products from a category — use for showcases or as related products (exclude current product via productId)
+  - name: product-spotlight
+    contract: product-spotlight.jay-contract
+    component: productSpotlight
+    description: A single product card by product ID — use to feature a product on any page
   - name: category-list
     contract: category-list.jay-contract
     component: categoryList

package/dist/contracts/related-products.jay-contract

@@ -1,31 +0,0 @@
-name: related-products
-description: Related products grid showing products from the same category. Use on product pages alongside the product-page component.
-props:
-  - name: productId
-    type: string
-    description: Product ID to exclude from results
-  - name: categorySlug
-    type: string
-    description: Category slug to filter related products by
-  - name: limit
-    type: number
-    description: Maximum number of related products to show (default 4)
-tags:
-  - tag: products
-    type: sub-contract
-    repeated: true
-    trackBy: _id
-    phase: fast+interactive
-    description: Related product cards
-    link: ./product-card
-
-  - tag: hasProducts
-    type: variant
-    dataType: boolean
-    phase: fast+interactive
-    description: Whether there are related products to show
-
-  - tag: categoryName
-    type: data
-    dataType: string
-    description: Name of the category these products belong to

package/dist/contracts/related-products.jay-contract.d.ts

@@ -1,36 +0,0 @@
-import {JayContract} from "@jay-framework/runtime";
-import {ProductCardViewState, ProductCardRefs, ProductCardRepeatedRefs} from "./product-card.jay-contract";
-
-export interface RelatedProductsViewState {
-  products: Array<ProductCardViewState>,
-  hasProducts: boolean,
-  categoryName: string
-}
-
-export type RelatedProductsSlowViewState = Pick<RelatedProductsViewState, 'categoryName'>;
-
-export type RelatedProductsFastViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
-    products: Array<RelatedProductsViewState['products'][number]>;
-};
-
-export type RelatedProductsInteractiveViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
-    products: Array<RelatedProductsViewState['products'][number]>;
-};
-
-
-export interface RelatedProductsRefs {
-  products: ProductCardRepeatedRefs
-}
-
-
-export interface RelatedProductsRepeatedRefs {
-  products: ProductCardRepeatedRefs
-}
-
-export interface RelatedProductsProps {
-  productId?: string;
-  categorySlug?: string;
-  limit?: number;
-}
-
-export type RelatedProductsContract = JayContract<RelatedProductsViewState, RelatedProductsRefs, RelatedProductsSlowViewState, RelatedProductsFastViewState, RelatedProductsInteractiveViewState, RelatedProductsProps>