@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-app/references/auto-patterns-dashboard/pages-configuration.md

@@ -0,0 +1,94 @@
+# Pages Configuration Rules
+
+## Type Definitions
+```typescript
+interface PageConfig {
+  id: string; // Unique ID
+  type: 'collectionPage' | 'entityPage';
+  appMainPage?: boolean; // EXACTLY ONE page must have true
+}
+
+interface CollectionPage extends PageConfig {
+  type: 'collectionPage';
+  collectionPage: {
+    route: { path: '/' };
+    components: [{
+      entityPageId: string; // REQUIRED: Links to entity page ID
+      // ... component config
+    }];
+  };
+}
+
+interface EntityPage extends PageConfig {
+  type: 'entityPage';
+  entityPage: {
+    parentPageId: string; // REQUIRED: Links to collection page ID
+    route: {
+      path: string; // MUST be '/[segment]/:entityId'
+      params: { id: 'entityId' };
+    };
+  };
+}
+
+interface StickyConfig {
+  stickyColumns?: number; // Count of columns to stick from left
+  columns: Array<{
+    reorderDisabled?: boolean; // Recommended for sticky cols
+  }>;
+}
+```
+
+## Validation Logic
+- **IF** `pages` array length != 2 **THEN** Invalid (Must be exactly 2).
+- **IF** `appMainPage: true` count != 1 **THEN** Invalid (Must be exactly 1).
+- **IF** `type: 'entityPage'` **THEN** `route.path` MUST match `/[segment]/:entityId`.
+- **IF** `route.path` is `/:entityId` **THEN** Invalid (Conflict with root).
+- **IF** `stickyColumns` is set **THEN** value must be > 0 AND <= total columns.
+
+## Implementation Rules
+- **MUST** generate exactly one `collectionPage` and one `entityPage`.
+- **MUST** link pages bidirectionally:
+    - `collectionPage` references `entityPageId` (in component).
+    - `entityPage` references `parentPageId` (in page config).
+- **MUST** use `entityId` as the dynamic parameter name.
+- **MUST** use position-based stickiness (first N columns).
+- **SHOULD** set `reorderDisabled: true` for sticky columns to prevent user breakage.
+
+## Canonical Example
+```typescript
+[
+  {
+    id: 'product-list',
+    type: 'collectionPage',
+    appMainPage: true,
+    collectionPage: {
+      route: { path: '/' },
+      components: [{
+        type: 'collection',
+        entityPageId: 'product-details', // Link to Entity Page
+        layout: [{
+          type: 'Table',
+          table: {
+            stickyColumns: 1,
+            columns: [
+              { id: 'name', name: 'Name', reorderDisabled: true }, // Sticky & Locked
+              { id: 'price', name: 'Price' }
+            ]
+          }
+        }]
+      }]
+    }
+  },
+  {
+    id: 'product-details',
+    type: 'entityPage',
+    entityPage: {
+      parentPageId: 'product-list', // Link to Collection Page
+      route: {
+        path: '/product/:entityId', // Correct format
+        params: { id: 'entityId' }
+      }
+    }
+  }
+]
+```

package/skills/wix-app/references/auto-patterns-dashboard/resolved-action.md

@@ -0,0 +1,43 @@
+# ResolvedAction Rules
+
+## Type Definitions
+```typescript
+interface ResolvedAction {
+  label: string; // Display text
+  icon: IconElement; // React Icon Component
+  onClick: () => void; // async handlers compile due to TS void-return bivariance
+  biName?: string; // type-optional; project convention is to ALWAYS set it (see Implementation Rules)
+  disabled?: boolean;
+  hidden?: boolean;
+  tooltip?: string;
+  skin?: string; // recommended values: 'standard' | 'inverted' | 'premium' | 'dark' | 'destructive'
+}
+```
+
+## Validation Logic
+- **IF** `disabled` is true **THEN** `tooltip` is **RECOMMENDED**.
+- **IF** implementing a custom action **THEN** return object MUST match `ResolvedAction`.
+- **IF** `biName` is provided **THEN** value MUST match configuration `biName`.
+
+## Implementation Rules
+- **MUST** include `label`, `icon`, `onClick`, and `biName`.
+- **MUST** use valid icon element (e.g. `<Icon />`).
+- **MUST** handle async `onClick` operations properly (use try/catch or SDK helpers).
+- **SHOULD** use `hidden` for permission checks.
+- **SHOULD** use `skin="destructive"` for delete/dangerous actions.
+
+## Canonical Example
+```typescript
+// Resolver Function Return Value
+return {
+  label: 'Export',
+  icon: <Download />,
+  biName: 'export-action',
+  onClick: async () => {
+    // Action logic
+  },
+  disabled: !hasData,
+  tooltip: !hasData ? 'No data to export' : undefined,
+  skin: 'standard'
+};
+```

package/skills/wix-app/references/auto-patterns-dashboard/sdk-utilities.md

@@ -0,0 +1,66 @@
+# SDK Utilities Rules
+
+## Type Definitions
+```typescript
+interface AutoPatternsSDK {
+  closeModal: () => void;
+  getOptimisticActions: (collectionId: string) => OptimisticActions;
+  getSchema: (collectionId: string) => SchemaConfig | undefined;
+  refreshCollection: () => void;
+  collectionId: string;
+}
+
+interface OptimisticActions {
+  createOne: (item: any, params: OptimisticParams) => void;
+  createMany: (items: any[], params: OptimisticParams) => void;
+  updateOne: (item: any, params: OptimisticParams) => void;
+  updateMany: (items: any[], params: OptimisticParams) => void;
+  updateAll: (transformFn: (item: any) => Partial<any>, params: OptimisticParams) => void;
+  deleteOne: (item: any, params: DeleteParams) => void;
+  deleteMany: (items: any[], params: DeleteParams) => void;
+  deleteAll: (params: DeleteParams) => void;
+}
+
+interface OptimisticParams {
+  submit: (items: any[]) => Promise<any>;
+  successToast: string | ToastConfig;
+  errorToast: (error: Error, actions: { retry: () => void }) => string | ToastConfig;
+}
+
+type DeleteParams = OptimisticParams & { showUndoToast: true };
+
+interface ToastConfig {
+  message: string; // Must use 'message' (not 'text')
+  action?: { text: string; onClick: () => void };
+}
+```
+
+## Validation Logic
+- **IF** using `delete*` operations **THEN** `showUndoToast: true` is **REQUIRED**.
+- **IF** returning `ToastConfig` **THEN** use `message` property (NOT `text`).
+- **IF** using schema in submit **THEN** check `schema` existence first (can be undefined).
+
+## Implementation Rules
+- **MUST** use `optimisticActions` for data mutations (create/update/delete).
+- **MUST** handle async submit failures in `errorToast`.
+- **MUST** use `sdk.collectionId` for current context.
+- **NEVER** use OptimisticActions for read-only operations.
+
+## Canonical Example
+```typescript
+const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+const schema = sdk.getSchema(sdk.collectionId);
+
+optimisticActions.updateOne(item, {
+  submit: async (items) => {
+    // Check schema existence
+    if (!schema) return items[0];
+    return await schema.actions.update(items[0]);
+  },
+  successToast: 'Item updated successfully',
+  errorToast: (err, { retry }) => ({
+    message: 'Update failed', // Use 'message'
+    action: { text: 'Retry', onClick: retry }
+  })
+});
+```

package/skills/wix-app/references/auto-patterns-dashboard/views.md

@@ -0,0 +1,76 @@
+# Views Configuration Rules
+
+## Type Definitions
+```typescript
+interface ViewsConfig {
+  enabled?: boolean;
+  presets?: ViewsPreset | CategoriesPreset;
+  saveViewModalProps?: { placeholderName?: string; learnMore?: { url?: string } };
+  viewsDropdownProps?: {
+    showTotal?: boolean;
+    hideAllItemsView?: boolean;
+    customAllItemsViewLabel?: string;
+  };
+}
+
+interface ViewsPreset {
+  type: 'views';
+  views: PresetView[];
+}
+
+interface CategoriesPreset {
+  type: 'categories';
+  categories: {
+    id: string;
+    label: string;
+    views: PresetView[];
+    icon?: { tooltipContent: string; size?: 'small' | 'medium' };
+  }[];
+}
+
+interface PresetView {
+  id: string; // Forbidden: predefined-views, saved-views, all-items-view
+  label: string;
+  isDefaultView?: boolean;
+  columnPreferences?: { id: string; direction?: 'asc' | 'desc'; show?: boolean }[];
+  filters?: Record<string, AutoFilterValue>; // Key matches filter config ID
+}
+```
+
+## Validation Logic
+- **IF** `views.enabled` is false **THEN** all other settings ignored.
+- **IF** controlling columns in views **THEN** `table.customColumns.enabled` MUST be true.
+- **IF** setting `columnPreferences` **THEN** must list ALL visible columns if reordering/hiding.
+- **IF** setting filters **THEN** keys MUST match defined filter IDs.
+
+## Implementation Rules
+- **MUST** set `enabled: true` to activate.
+- **MUST** use valid filter structures (Date/Number/Boolean/Enum/Reference) matching `AppConfig`.
+- **MUST** avoid reserved IDs (`predefined-views`, `saved-views`, `all-items-view`).
+- **SHOULD** set `isDefaultView: true` on exactly one preset if default override needed.
+
+## Canonical Example
+```typescript
+views: {
+  enabled: true,
+  presets: {
+    type: 'categories',
+    categories: [{
+      id: 'status-cat',
+      label: 'By Status',
+      views: [{
+        id: 'active-items',
+        label: 'Active Only',
+        isDefaultView: true,
+        filters: {
+          'status-filter': { filterType: 'boolean', value: [{ id: 'checked', name: 'Active' }] }
+        },
+        columnPreferences: [
+          { id: 'name', show: true },
+          { id: 'status', show: true, direction: 'asc' }
+        ]
+      }]
+    }]
+  }
+}
+```

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/ACCESSIBILITY.md

@@ -13,20 +13,6 @@ Rules and patterns for ARIA accessibility support in Editor React components.
 - The `A11y` type includes: `ariaLabel`, `ariaDescribedBy`, `ariaLabelledBy`, `role`, `ariaHidden`, `ariaLive`, and all other ARIA attributes.
 - Users provide ARIA values through the `a11y` prop: `<Component a11y={{ ariaLabel: "..." }} />`
 
-### Stable IDs for Element Relationships
-
-ARIA relationships (`aria-controls`, `aria-labelledby`, `aria-describedby`) and `htmlFor` need element ids. Generate them with `useStableId` from `@wix/react-component-utils` — passing the `id` prop as the override — never `Math.random()`, a manual counter, or a bare `React.useId()` (those break SSR/hydration). See [`SSR.md`](SSR.md) for the full rule.
-
-```tsx
-import { useStableId } from '@wix/react-component-utils';
-
-const rootId = useStableId(id);
-const panelId = `${rootId}-panel`;
-
-<button aria-controls={panelId}>{label}</button>
-<div id={panelId} role="tabpanel">{content}</div>
-```
-
 ### ARIA Label Rules
 
 ARIA labels are user-facing content and must NEVER be hardcoded as string literals in JSX.
@@ -150,3 +136,4 @@ export interface TabsProps {
 ```
 
 **Why:** The `A11y` type from `@wix/editor-react-types` provides a standardized way to handle ALL ARIA attributes (ariaLabel, ariaDescribedBy, ariaLabelledBy, role, ariaHidden, ariaLive, etc.). Individual ARIA props fragment the API and make it harder to use.
+

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-API.md

@@ -7,23 +7,17 @@ Rules and patterns for props structure, elementProps, data types, file structure
 ## Should This Use elementProps or CSS?
 
 ```
-Does this element need:
-- Configuration/data beyond styling
-- Direction override
-- State management
-- Event handlers
-
+Is this element a named part (carries a global class string)?
 │
 ├─ YES
-│   └─ ✅ Use elementProps
+│   └─ ✅ It gets an elementProps entry — spread it + merge its className.
+│         Add config fields inside the entry only as needed
+│         (data, direction, event handlers).
 │
-└─ NO → Is it purely visual/decorative (including conditionally displayed)?
-    │
-    ├─ YES (icons, separators, decorations, elements only hidden/shown via CSS)
-    │   └─ ❌ CSS class only (no elementProps)
-    │
-    └─ NO
-        └─ Re-evaluate: likely needs elementProps
+└─ NO → purely visual/decorative non-part
+        (icons, separators, decorations, layout wrappers,
+         elements only hidden/shown via CSS)
+    └─ ❌ CSS class only — no elementProps entry
 ```
 
 ---
@@ -58,23 +52,53 @@ interface ComponentProps {
 }
 ```
 
-### When to Use elementProps
+### Propagate `elementProps` to inner elements
+
+`elementProps` is a map keyed by the manifest's inner-element keys; each entry
+carries that element's `className` (the editor sets it — this is how design
+states reach the element) plus any data.
+
+**Every named inner element — every element that carries a global class
+string — gets an `elementProps` entry, and you spread that entry onto the
+element.** This is mandatory, even when the element needs no other config:
+without it the editor cannot style that element or drive its states.
 
-**Use `elementProps`** for parts that need:
+How `className` gets merged depends on what the element is:
+
+- **Raw HTML element** (`<button>`, `<li>`, `<div>`): merge
+  `elementProps?.<key>.className` inline, alongside the global string and module
+  class — there's no component to do it.
+- **Sub-component built with this skill** (`<Inner/>`): the spread alone is
+  enough. `className` rides along inside it, and the sub-component merges it onto
+  its own root (every skill component merges its incoming `className`). Don't
+  merge it again at the call site.
+
+```tsx
+interface PlanCardProps {
+  className?: string;
+  elementProps?: {
+    cta?: { className?: string; href?: string };
+  };
+}
 
-- Configuration/data beyond just styling
-- Direction override
-- State management
-- Event handlers
+// Raw HTML element — spread + merge className inline.
+// Note: the elementProps key is the short part name (`cta`), while the global
+// class is prefixed with the component name (`plan-card-cta`). Keep them as-is.
+<button {...elementProps?.cta} className={classNames('plan-card-cta', styles.cta, elementProps?.cta?.className)}>
+  {label}
+</button>
 
-**DO NOT use `elementProps`** for:
+// Sub-component built with this skill — spread is enough (it merges className itself):
+<PlanRow {...elementProps?.planRow} />
+```
 
-- Elements with only visual styling (use CSS classes)
-- Elements where conditional display is the only requirement (visibility controlled via CSS for per-breakpoint hiding, not React props)
-- Elements that would only have `className` — skip them entirely
-- Icons, decorations, separators
+**Non-parts** (module-class-only elements: icons, decorations, separators,
+layout wrappers — no global class) get no entry. Style them with CSS.
 
-**Minimal elementProps rule:** If an element would only have `className?: string` in elementProps, do NOT include it.
+**Inside each entry**, add only the config the element needs (data, direction,
+event handlers). Never add a bare `className?` as the *only* field to decide
+whether an element qualifies — `className` always flows through; the entry
+exists because the element is a named part.
 
 ### What Qualifies as a Part
 
@@ -178,8 +202,8 @@ editor) or imported local assets bundled with the component.
 
 ### Default values for `Image` props
 
-Image defaults belong in the component file's exported `defaultProps`
-constant (the one consumed by `withDefaults(Component, defaultProps)` in
+Image defaults belong in the `<componentName>.props.ts` file's exported
+`defaultProps` constant (consumed by `withDefaults(Component, defaultProps)` in
 `component.tsx`). Use a Wix-hosted image from the Free-from-Wix public
 media catalog and populate **only** `uri`, `url`, and `alt` — leave
 `width`, `height`, `focalPoint`, etc. unset so the editor fills them when
@@ -426,7 +450,7 @@ elementProps?: {
 // Style via CSS classes directly
 ```
 
-**Why:** If element only has `className` (even if it can be hidden/shown via CSS), skip elementProps entirely. Conditional display is controlled via CSS, not React props.
+**Why:** Don't declare a `className?:` field — `className` already flows through each named inner element's `elementProps` entry (see "Propagate `elementProps` to inner elements"). Conditional display is controlled via CSS, not React props.
 
 ### Using T[] array syntax
 
@@ -452,3 +476,4 @@ interface ComponentProps {
 ```
 
 See also: [Array Element Types: Always Objects with Named Keys](#array-element-types-always-objects-with-named-keys) — items must be objects with named keys.
+

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

@@ -128,14 +128,14 @@ resizeDirection: LAYOUT.RESIZE_DIRECTION.aspectRatio,
 
 ## 3. Wiring defaults into the manifest
 
-1. **Export `defaultProps` from `component.tsx`** so the extension file can import it.
+1. **Define and export `defaultProps` from `<componentName>.props.ts`** — this is the single source of truth used by both `component.tsx` and the extension file.
 2. **Import `componentUrl` from `'./component.tsx?url'`** (the wrapped component), not from `'./ComponentName.tsx?url'` (the raw component).
 3. **Wrap `editorElement` with `withEditorElementDefaults`** using the same `defaultProps`.
 
 ```ts
 import { withEditorElementDefaults } from '@wix/react-component-utils';
 import componentUrl from './component.tsx?url';
-import { defaultProps } from './component';
+import { defaultProps } from './<componentName>.props';
 
 // in the extension:
 editorElement: withEditorElementDefaults({

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.