@wix/agent-skills 1.15.0 → 1.15.1

package/README.md

@@ -91,6 +91,14 @@ When a major bump is required (a breaking change in the underlying `wix-cli`), t
 
 Run the [`release-bump`](.github/workflows/release-bump.yml) workflow from the **Actions** tab and pick a `version_strategy`. The rest is automatic — the bump PR auto-merges once checks pass and [`release.yml`](.github/workflows/release.yml) publishes to npm via Trusted Publishing.
 
+## Serving & caching (`www.wix.com/skills`)
+
+Besides the npm package, skills are served as raw markdown / `.tgz` at `https://www.wix.com/skills/<name>` (also `dev.wix.com/skills`). That registry is **not** in this repo — it's an Express service in [`wix-private/docs`](https://github.com/wix-private/docs) (`docs-web-app`) that serves this repo's `main` branch directly, with no build step.
+
+Responses are cached at the Wix edge (Pepyaka, tag `skills`) plus a ~5-min per-pod tarball cache. A push to `main` touching `skills/**` **auto-invalidates** the edge tag (via `md-resolver`'s GitHub-push consumer), so a merge reflects within a few minutes. To force it immediately, hit the manual flush (`POST /api/v1/invalidate-ssr-cache/skills`, BO staff) or the Fire Console `invalidateCache` call.
+
+Full details — endpoints, `wix-` prefix stripping, host-relative links, invalidation — are in the [docs-web-app skills README](https://github.com/wix-private/docs/blob/main/packages/docs-web-app/express/skills/README.md).
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new skills.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.15.0",
+  "version": "1.15.1",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/references/DATA_COLLECTION.md

@@ -80,18 +80,20 @@ export default {
 | `ARRAY_DOCUMENT`  | Array of documents               | File collections       |
 | `ANY`             | Any type                         | Most flexible          |
 
-**CRITICAL: OBJECT fields require `objectOptions`.** When using `type: "OBJECT"`, you MUST include the `objectOptions` property — the API will reject OBJECT fields without it. Use an empty object `{}` if you don't need schema validation:
+**CRITICAL: OBJECT fields require `objectOptions` with a `fields` array.** When using `type: "OBJECT"`, you MUST include `objectOptions: { fields: [] }` — the API will reject OBJECT fields without it. Use an empty `fields` array if you don't need a fixed schema (the object will still accept arbitrary JSON):
 
 ```json
 {
   "key": "settings",
   "displayName": "Settings",
   "type": "OBJECT",
-  "objectOptions": {}
+  "objectOptions": { "fields": [] }
 }
 ```
 
-For structured objects, define nested fields inside `objectOptions.fields`:
+> ⚠️ `objectOptions: {}` (without the `fields` key) is **not valid** and will cause a runtime error. Always include `fields`, even as an empty array.
+
+For structured objects with a defined schema, list the nested fields inside `objectOptions.fields`:
 
 ```json
 {

package/skills/wix-app/references/EDITOR_REACT_COMPONENT.md

@@ -87,6 +87,8 @@ Topic-focused references (rules + patterns + common mistakes in one place):
 - [`editor-react-component/PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
 - [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, remaining common mistakes
+- [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) — Play/pause controls for animated components (Lottie, GIF, autoPlay props)
+- [`editor-react-component/COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) — `component.preview.tsx` patterns and `useIsEditMode()` usage
 
 ## CSS guidelines
 

package/skills/wix-app/references/STORES_VERSIONING.md

@@ -1,4 +1,3 @@
-
 # Wix Stores Catalog Versioning (V1 / V3)
 
 Wix Stores has two catalog versions that are **NOT backwards compatible**. Apps **must support both** — single-version apps cannot list in the App Market and break on new sites.
@@ -82,214 +81,6 @@ Handle `STORES_NOT_INSTALLED` gracefully — return empty results, do not throw.
 
 ---
 
-## Copy-Paste Recipes
-
-Each recipe handles both versions. `V3Product` and V1 `Product` types are **not** re-exported from `@wix/stores` top-level — let TS infer or use structural types.
-
-### List products with pagination
-
-Both versions expose a fluent query builder, but the paging method differs:
-
-| Aspect | V1 (`products.queryProducts()`) | V3 (`productsV3.queryProducts()`) |
-|--------|--------------------------------|----------------------------------|
-| API style | Fluent builder: `.skip().limit().find()` | Fluent builder: `.skipTo(cursor).limit().find()` |
-| Pagination | Offset (`.skip(n)`) | Cursor (`.skipTo(cursor)`) |
-| Result `items` | `res.items` (V1 `Product[]`) | `res.items` (V3 `Product[]`) |
-| Total count | `res.totalCount` | **None** — V3 only has `cursors.next` + `hasNext()` |
-| `hasNext` | `res.hasNext()` (method) | `res.hasNext()` (method) |
-| Next cursor | n/a | `res.cursors.next` (string) |
-
-```typescript
-import { catalogVersioning, products, productsV3 } from '@wix/stores';
-
-export interface ProductsPage {
-  products: unknown[];        // narrow at call site
-  nextCursor: string | null;  // V3 only
-  hasNext: boolean;
-  totalCount: number | null;  // V1 only
-}
-
-export async function listProductsPage(
-  limit: number,
-  cursorOrSkip: string | number | undefined,
-): Promise<ProductsPage> {
-  const v = await getVersion();
-  if (v === 'STORES_NOT_INSTALLED') {
-    return { products: [], nextCursor: null, hasNext: false, totalCount: 0 };
-  }
-
-  if (v === 'V3_CATALOG') {
-    let builder = productsV3.queryProducts().limit(limit);
-    if (typeof cursorOrSkip === 'string') builder = builder.skipTo(cursorOrSkip);
-    // Do NOT chain a sort — see gotcha #10.
-    const res = await builder.find();
-    return {
-      products: res.items,
-      nextCursor: res.cursors.next ?? null,
-      hasNext: res.hasNext(),
-      totalCount: null,
-    };
-  }
-
-  const skip = typeof cursorOrSkip === 'number' ? cursorOrSkip : 0;
-  const res = await products.queryProducts().skip(skip).limit(limit).find();
-  return {
-    products: res.items,
-    nextCursor: null,
-    hasNext: res.hasNext(),
-    totalCount: res.totalCount ?? null,
-  };
-}
-```
-
-> **Two ways to call V3 `queryProducts`:** the canonical builder shown above, and a direct-call form `productsV3.queryProducts({ cursorPaging: { limit, cursor } })` returning a `Promise<{ products, pagingMetadata }>`. Both compile and run, but the builder is more idiomatic and matches V1's shape.
-
-### Display price/stock without fetching variants
-
-V3 `queryProducts` does not return variants. Read product-level rollup fields instead:
-
-```typescript
-function displayPrice(p: { actualPriceRange?: { minValue?: { amount?: string }; maxValue?: { amount?: string } } }): string {
-  const min = p.actualPriceRange?.minValue?.amount;
-  const max = p.actualPriceRange?.maxValue?.amount;
-  if (!min) return '—';
-  return max && max !== min ? `${min} – ${max}` : min;
-}
-
-function stockLabel(status: string | undefined): string {
-  switch (status) {
-    case 'IN_STOCK': return 'In Stock';
-    case 'OUT_OF_STOCK': return 'Out of Stock';
-    case 'PARTIALLY_OUT_OF_STOCK': return 'Limited';
-    case 'PREORDER': return 'Pre-order';
-    default: return '—';
-  }
-}
-// V1 path: product.stock.inventoryStatus  (same UPPER_SNAKE_CASE values)
-// V3 path: product.inventory.availabilityStatus (adds PREORDER)
-// SKU lives on the variant — show "—" in lists, or use Read-Only Variants API.
-```
-
-### Get a single product
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const product = await productsV3.getProduct(id);  // returns Product directly
-  return product;
-}
-const { product } = await products.getProduct(id);  // V1 wraps in { product }
-return product;
-```
-
-### Create a product (single-variant, with price)
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const product = await productsV3.createProduct({
-    name: 'My Product',
-    productType: 'PHYSICAL',                            // UPPER_CASE
-    variantsInfo: {
-      variants: [{
-        price: { actualPrice: { amount: '19.99' } },    // string, on the variant
-        sku: 'SKU-001',
-      }],
-    },
-  });
-  return product;
-}
-
-const { product } = await products.createProduct({
-  name: 'My Product',
-  productType: 'physical',                              // lower-case
-  priceData: { price: 19.99 },                          // number, on the product
-  sku: 'SKU-001',
-});
-return product;
-```
-
-### Update a product (V3 needs `revision`)
-
-```typescript
-if (v === 'V3_CATALOG') {
-  // Signature: updateProduct(_id, productFields). Returns Product directly.
-  const current = await productsV3.getProduct(id);
-  if (current.revision == null) throw new Error(`Product ${id} has no revision`);
-  return await productsV3.updateProduct(id, {
-    revision: current.revision,  // narrowed — required under exactOptionalPropertyTypes
-    name: 'New name',
-  });
-}
-// V1: updateProduct(id, productFields). Returns { product }.
-const { product } = await products.updateProduct(id, { name: 'New name' });
-return product;
-```
-
-### Delete a product
-
-```typescript
-if (v === 'V3_CATALOG') await productsV3.deleteProduct(id);
-else await products.deleteProduct(id);
-```
-
-### Inventory: increment stock
-
-```typescript
-import { inventory, inventoryItemsV3 } from '@wix/stores';
-
-if (v === 'V3_CATALOG') {
-  // Per-variant; flat shape.
-  await inventoryItemsV3.bulkIncrementInventoryItems([
-    { inventoryItemId, incrementBy: 5 },
-  ]);
-} else {
-  // Per-product (variant optional).
-  await inventory.incrementInventory([
-    { productId, variantId, incrementBy: 5 },
-  ]);
-}
-```
-
-To find a V3 inventory item ID, use `inventoryItemsV3.searchInventoryItems` filtered by `productId` / `variantId`.
-
-### Query inventory
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const res = await inventoryItemsV3.queryInventoryItems().eq('productId', productId).find();
-  return res.items;
-}
-// V1: filter is a JSON-stringified expression.
-const res = await inventory.queryInventory({
-  query: { filter: JSON.stringify({ productId }) },
-});
-return res.inventoryItems;
-```
-
-### Collections (V1) ↔ Categories (V3)
-
-```typescript
-// V1 write ops (createCollection, updateCollection, addProductsToCollection, …)
-// live on the `products` namespace, NOT `collections`. The `collections` namespace is read-only.
-import { products } from '@wix/stores';
-import { categories } from '@wix/categories';
-
-if (v === 'V3_CATALOG') {
-  // V3 createCategory(category, options). treeReference is REQUIRED and goes in `options`.
-  // For Wix Stores categories: appNamespace MUST be the literal "@wix/stores", treeKey is null.
-  const category = await categories.createCategory(
-    { name: 'Sale' },
-    { treeReference: { appNamespace: '@wix/stores', treeKey: null } },
-  );
-  return category;
-}
-const { collection } = await products.createCollection({ name: 'Sale' });  // V1 returns { collection }
-return collection;
-```
-
-V3 categories are tree-structured. Reference them on a product via `directCategories[]`, not `collectionIds[]`. **All Stores category API calls must pass `treeReference: { appNamespace: '@wix/stores', treeKey: null }` in `options`** — applies to `createCategory`, `updateCategory`, `queryCategories`, etc.
-
----
-
 ## V1 → V3 Field Mapping (most common)
 
 For the full table see the [Catalog V1 to V3 Migration Guide](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/catalog-v1-to-v3-migration-guide?apiView=SDK).
@@ -311,6 +102,7 @@ For the full table see the [Catalog V1 to V3 Migration Guide](https://dev.wix.co
 | `collectionIds[i]` | `directCategories[i].id` |
 | `ribbon`, `brand` (string) | `ribbon.name`, `brand.name` (managed via `ribbonsV3` / `brandsV3`) |
 | `media.mainMedia.image.url` (main image URL) | `media.main.image ?? media.main.url` — in V3, `ProductMedia.image` is a `string` (Wix-hosted URL), `url` is a `string` (external URL); check both |
+| `lastUpdated` | `updatedDate` |
 
 **Pricing model** — V1 had a `discount` object; V3 removed it. Discounts are now expressed by the relationship between two fields on the variant: `actualPrice` (required, what the customer pays) vs `compareAtPrice` (optional, original price shown struck through). With discount: V1 `price`/`discountedPrice` → V3 `compareAtPrice`/`actualPrice`. Without discount: V1 `price` → V3 `actualPrice`, leave `compareAtPrice` empty.
 
@@ -330,6 +122,12 @@ Payload changes: V1 `changedFields` → V3 `modifiedFields`. Top-level `entityId
 
 ---
 
-## Falling back to MCP
+## Detailed references
+
+- [stores/QUERY.md](stores/QUERY.md) — list/query products, pagination, price and stock display
+- [stores/GET_PRODUCT.md](stores/GET_PRODUCT.md) — getProduct, options/choices, modifiers, variant choices
+- [stores/WRITE.md](stores/WRITE.md) — create, update, delete products
+- [stores/INVENTORY.md](stores/INVENTORY.md) — inventory read and write operations
+- [stores/CATEGORIES.md](stores/CATEGORIES.md) — collections (V1) ↔ categories (V3)
 
-This file covers the common 80%. For methods not listed (subscriptions, brands, ribbons, etc.) or full request schemas, use `SearchWixSDKDocumentation` then `ReadFullDocsArticle`. Always return the required permission scopes to the user.
+For methods not listed here, use `SearchWixSDKDocumentation` then `ReadFullDocsArticle`. Always return the required permission scopes to the user.

package/skills/wix-app/references/backend-event/COMMON-EVENTS.md

@@ -12,10 +12,15 @@ This reference lists common event types, SDK imports, permissions, and links. Fo
 
 ## eCommerce Events
 
+Order events use **`@wix/ecom`** (namespace `orders`). Order **refund** events are the exception: they live in **`@wix/payments`** (namespace `refunds`), not `@wix/ecom`.
+
 | Event | Import | Handler Call | Permission | API Reference |
 | --- | --- | --- | --- | --- |
 | Order created | `import { orders } from "@wix/ecom"` | `orders.onOrderCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-created?apiView=SDK) |
 | Order approved | `import { orders } from "@wix/ecom"` | `orders.onOrderApproved(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderApproved](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-approved?apiView=SDK) |
+| Order canceled | `import { orders } from "@wix/ecom"` | `orders.onOrderCanceled(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderCanceled](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-canceled?apiView=SDK) |
+| Refund created | `import { refunds } from "@wix/payments"` | `refunds.onRefundCreated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundCreated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-created?apiView=SDK) |
+| Refund updated | `import { refunds } from "@wix/payments"` | `refunds.onRefundUpdated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundUpdated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-updated?apiView=SDK) |
 | Cart created | `import { cart } from "@wix/ecom"` | `cart.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-created?apiView=SDK) |
 | Cart updated | `import { cart } from "@wix/ecom"` | `cart.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-updated?apiView=SDK) |
 

package/skills/wix-app/references/editor-react-component/ANIMATED-COMPONENTS.md

@@ -0,0 +1,151 @@
+# Animated Components (Play/Pause Control)
+
+Rules and patterns for components whose primary content is a **playable
+animation** — a Lottie/JSON animation, an animated GIF/SVG, a canvas/WebGL
+loop, or a video-like surface.
+
+Every such component MUST ship an on-stage **play/pause button**.
+
+---
+
+## When this applies
+
+Apply automatically — without being asked — whenever the component has an
+`autoPlay` prop **or** its primary content is a **startable / loopable**
+animation a visitor would reasonably want to start or stop:
+
+- Any component with an `autoPlay` prop (gallery, slider, carousel, etc.)
+- Lottie / JSON vector animations
+- Animated GIFs or animated SVGs
+- Canvas / WebGL animation loops
+- Any video-like playing surface
+
+**Key rule:** If the component accepts an `autoPlay` prop — even if the
+underlying mechanism is a `setInterval` advancing an index rather than a media
+player — it MUST expose a play/pause button so visitors can stop the
+auto-advancing behavior. "Autoplay" is a behavior contract, not an
+implementation detail.
+
+---
+
+## What to add (checklist)
+
+1. **Props** — `autoPlay`, `loop`, `pauseButtonVisibility`
+2. **Playback state** — `isPlaying` + `handlePause` / `handleResume`
+3. **Play/pause button** — overlay `<button>` with inline SVG icon + CSS positioning and optional hover-only visibility
+4. **Modify `component.preview.tsx`** — suppress autoplay in editor design mode
+
+---
+
+## 1. Props
+
+Playback controls are **behavior** props (see [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md)):
+
+```typescript
+import type { A11y, Direction } from '@wix/editor-react-types';
+
+export interface MyAnimationProps {
+  id?: string;
+  className?: string;
+  direction?: Direction;
+  a11y?: A11y;
+
+  /** Start playing on load. Default `true`. */
+  autoPlay?: boolean;
+
+  /** Repeat when finished. Default `true`. */
+  loop?: boolean;
+
+  /** Show play/pause button. Default `'showOnHover'`. */
+  pauseButtonVisibility?: 'showAlways' | 'showOnHover';
+}
+```
+
+---
+
+## 2. Playback state
+
+Track play/pause state with `useState`, initialized from the `autoPlay` prop:
+
+```tsx
+const [isPlaying, setIsPlaying] = React.useState(autoPlay ?? true);
+
+const handlePause = () => setIsPlaying(false);
+const handleResume = () => setIsPlaying(true);
+```
+
+Pass `isPlaying` to the animation renderer and toggle between `handlePause` / `handleResume` on button click.
+
+---
+
+## 3. Play/pause button
+
+Create play/pause icons that visually match the component's style. Use simple recognizable shapes — a triangle for play, two rectangles for pause — implemented as inline SVG so there is no external icon dependency. Size, stroke, and fill should feel native to the component's design.
+
+Position the button absolutely so it overlays the content without pushing other elements out of place:
+
+```css
+.animationContainer {
+  position: relative;
+  block-size: 100%;
+  inline-size: 100%;
+}
+
+.playButton {
+  position: absolute;
+  inset-inline-end: 5px;
+  inset-block-start: 5px;
+}
+```
+
+```css
+/* pauseButtonVisibility variants — structural CSS, not named-part rules */
+
+/* showOnHover (default) */
+.root[data-pause-button-visibility="showOnHover"] .playButton {
+  opacity: 0;
+  pointer-events: none;
+}
+
+.root[data-pause-button-visibility="showOnHover"]:hover .playButton {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* showAlways — no extra CSS needed; button is visible by default */
+```
+
+---
+
+## 4. Modify `component.preview.tsx` for autoplay suppression
+
+For animated components, modify the generated `component.preview.tsx` to suppress autoplay in editor design mode. See [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) for how the preview file works.
+
+### Target state of `component.preview.tsx`
+
+Replace the generated passthrough with the following. Replace `MyComponent` with the real component name.
+
+```tsx
+import React from 'react';
+import MyComponent from './component';
+import { useIsEditMode } from '@wix/react-component-utils';
+
+export default function MyComponentPreview(
+  props: React.ComponentProps<typeof MyComponent>,
+) {
+  const isEditMode = useIsEditMode();
+
+  return (
+    <MyComponent
+      {...props}
+      autoPlay={isEditMode ? false : props.autoPlay}
+      pauseButtonVisibility={isEditMode ? 'showAlways' : props.pauseButtonVisibility}
+    />
+  );
+}
+```
+
+In editor design mode (`isEditMode` is `true`) → `autoPlay` is forced to `false` and `pauseButtonVisibility` is forced to `'showAlways'` so the site owner can always see and interact with the button.  
+In preview mode (`isEditMode` is `false`) → both use the user's configured values.
+
+---

package/skills/wix-app/references/editor-react-component/COMPONENT-PREVIEW.md

@@ -0,0 +1,57 @@
+# Component Preview (`component.preview.tsx`)
+
+Rules and patterns for the editor-specific entry point that every Editor React
+component ships alongside its main `component.tsx`.
+
+---
+
+## What it is
+
+`component.preview.tsx` is the editor-specific entry point for a component. The
+Wix CLI loads it **instead of** `component.tsx` when rendering the component
+inside the Harmony Editor. It is generated automatically by the scaffold as a
+passthrough that forwards all props unchanged:
+
+```tsx
+const MyComponentPreview = (props: React.ComponentProps<typeof MyComponent>) => (
+  <MyComponent {...props} />
+);
+```
+
+The extension file is also pre-wired to load it — no manual wiring is needed:
+
+```ts
+import componentPreviewUrl from './component.preview.tsx?url';
+
+resources: {
+  client: { componentUrl },
+  editor: { componentUrl: componentPreviewUrl },
+},
+```
+
+---
+
+## `useIsEditMode()`
+
+When you need to distinguish **editor design mode** from **editor preview mode**,
+use `useIsEditMode()` from `@wix/react-component-utils`:
+
+```tsx
+import { useIsEditMode } from '@wix/react-component-utils';
+
+const isEditMode = useIsEditMode();
+// true  → editor is in design mode
+// false → editor is in preview mode
+```
+
+`@wix/react-component-utils` is already a base dependency — no additional install needed.
+
+---
+
+## When to modify it
+
+Modify `component.preview.tsx` whenever the component needs to behave differently
+inside the editor than it does on the live site. The most common case is
+suppressing autoplay so animations don't run while the site owner is designing.
+
+→ See [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) §4 for the autoplay suppression pattern.

package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md

@@ -465,6 +465,12 @@ slide instead.
 }
 ```
 
+**Media playback is functional, not decorative.** When the component's content
+*is* a playing animation (Lottie/JSON, animated GIF/SVG, canvas/WebGL, video),
+letting it play is allowed — the motion is the content. Such components get a
+play/pause control positioned in CSS. See
+[`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md).
+
 ### Set `pointer-events: auto` on the root and every interactive element
 
 The root selector and every nested class that the user can click,

package/skills/wix-app/references/editor-react-component/REACT-GUIDELINES.md

@@ -9,6 +9,8 @@ This guide defines rules and guidance on **how to implement** production-quality
 - [`DIRECTIONALITY.md`](DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`COMPONENT-API.md`](COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
+- [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
+- [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) — `component.preview.tsx` patterns and `useIsEditMode()` usage
 - [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
 
 ## React 18 features are not supported
@@ -23,7 +25,7 @@ Understand the component and infer its behavior. Extract what is provided; use r
 
 1. **Identity** — Component name.
 2. **Structure** — Identify named parts by applying the mandatory filter in [`PARTS.md`](PARTS.md) to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
-3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally.
+3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally. If the component's primary content is a **playable animation** (Lottie/JSON, animated GIF/SVG, canvas/WebGL loop, video-like surface), it gets a play/pause control — follow [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md).
 4. **States** — For every part, decide which design states it supports (native: `hover`/`focus`/`disabled`/`invalid`; custom: `selected`/`active`/`open`/… ) by applying the heuristic in [`DESIGN-STATES.md`](DESIGN-STATES.md), and record them in the plan. These become the editor's per-element state styling controls.
 
 **Understanding → implementation (checklist):** For every part, decide `elementProps` vs CSS-only and which design states it supports ([`DESIGN-STATES.md`](DESIGN-STATES.md)); build the props interface (data + behavior); wire interaction in React (`useState`, `useEffect`, refs, native event handlers); give every named inner element an `elementProps` entry and spread it + merge its `className` ([`COMPONENT-API.md`](COMPONENT-API.md)); generate TS + CSS. Infer reasonable defaults where anything is unspecified.

package/skills/wix-app/references/stores/CATEGORIES.md

@@ -0,0 +1,22 @@
+# Stores — Collections (V1) ↔ Categories (V3)
+
+```typescript
+// V1 write ops (createCollection, updateCollection, addProductsToCollection, …)
+// live on the `products` namespace, NOT `collections`. The `collections` namespace is read-only.
+import { products } from '@wix/stores';
+import { categories } from '@wix/categories';
+
+if (v === 'V3_CATALOG') {
+  // V3 createCategory(category, options). treeReference is REQUIRED and goes in `options`.
+  // For Wix Stores categories: appNamespace MUST be the literal "@wix/stores", treeKey is null.
+  const category = await categories.createCategory(
+    { name: 'Sale' },
+    { treeReference: { appNamespace: '@wix/stores', treeKey: null } },
+  );
+  return category;
+}
+const { collection } = await products.createCollection({ name: 'Sale' });  // V1 returns { collection }
+return collection;
+```
+
+V3 categories are tree-structured. Reference them on a product via `directCategories[]`, not `collectionIds[]`. **All Stores category API calls must pass `treeReference: { appNamespace: '@wix/stores', treeKey: null }` in `options`** — applies to `createCategory`, `updateCategory`, `queryCategories`, etc.