@wix/agent-skills 1.16.1 → 1.16.2

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

@@ -0,0 +1,172 @@
+# @wix/patterns Component Documentation
+
+## Prerequisites
+
+The docs are pre-built at `node_modules/@wix/patterns/dist/docs/` (160+ markdown files + `index.json`). This requires `@wix/patterns` version **1.367.0** or later. Verify they exist:
+
+```bash
+ls node_modules/@wix/patterns/dist/docs/   # expect ~165 .md files + index.json
+```
+
+If the directory is missing, install the package at the minimum version:
+
+```bash
+npm install @wix/patterns@^1.367.0
+```
+
+## Library Architecture
+
+### Composition Hierarchy
+
+```
+Provider                     <- WixPatternsProvider or WixPatternsBMProvider
+  +-- Page                   <- CollectionPage, EntityPage, or SettingsPage
+       +-- Collection        <- Table, Grid, TableGridSwitch, etc.
+            +-- Features     <- filters, actions, sorting, drag-and-drop, etc.
+```
+
+### The Collection Triad
+
+Each collection type follows the same Component + State + Hook pattern:
+
+| Collection       | Component          | State Type              | Hook                            |
+|------------------|--------------------|-------------------------|---------------------------------|
+| Table            | `Table`            | `TableState`            | `useTableCollection()`          |
+| Grid             | `Grid`             | `GridState`             | `useGridCollection()`           |
+| TableGridSwitch  | `TableGridSwitch`  | `TableGridSwitchState`  | `useTableGridSwitchCollection()`|
+| TableFolders     | `TableFolders`     | `TableFoldersState`     | `useTableFolders()`             |
+| GridFolders      | `GridFolders`      | `GridFoldersState`      | `useGridFolders()`              |
+
+This table covers the common collection types — the full, authoritative list is in `node_modules/@wix/patterns/dist/docs/index.json`.
+
+Create state with the hook -> pass it to the component's `state` prop -> wrap in a page component.
+
+### Choosing the Right Provider
+
+| Provider                        | When to Use                                                                          |
+|---------------------------------|--------------------------------------------------------------------------------------|
+| `WixPatternsProvider`           | **Default — start here.** Auto-detects the environment (BM, Essentials, Giza) and supplies the right context. |
+| `WixPatternsBMProvider`         | Optional alternative for Yoshi BM Flow over Business Manager.                        |
+| `WixPatternsGizaProvider`       | Optional alternative for Yoshi BM Flow over Giza.                                    |
+| `WixPatternsEssentialsProvider` | Yoshi Fullstack.                                                                     |
+| `WixPatternsBaseProvider`       | App does **not** run under a Giza/WixEssentials environment and you inject services (i18n, sentry) yourself. |
+
+Prefer `WixPatternsProvider` unless the project is on one of the specific Yoshi flows above — it is the documented recommendation for most apps, and it resolves the environment for you rather than making you pick.
+
+**Confirm the import path in the provider's own doc file** — these do not all come from the same subpath (`WixPatternsEssentialsProvider` and `WixPatternsBaseProvider` are under `@wix/patterns/essentials`, for instance). Check the project's `package.json` to identify the flow.
+
+### Keep Provider and Page Separate
+
+The provider **must** be in a separate parent component from the page content. Hooks like `useTableCollection` require the provider's context to already exist above them in the React tree.
+
+**Wrong — provider and page in the same component:**
+```tsx
+function BadApp() {
+  const state = useTableCollection({
+    queryName: 'my-items',
+    itemKey: (item) => item.id,
+    itemName: (item) => item.name,
+    fetchData: async () => ({ items: [], total: 0 }),
+    filters: {},
+  }); // fails at runtime — no provider context above this component
+  return (
+    <WixPatternsProvider>
+      <CollectionPage>
+        <Table state={state} columns={[{ title: 'Name', render: (item) => item.name }]} />
+      </CollectionPage>
+    </WixPatternsProvider>
+  );
+}
+```
+
+**Correct — provider in root, page in a separate file:**
+```tsx
+// App.tsx
+import { WixPatternsProvider } from '@wix/patterns/provider';
+
+function App() {
+  return (
+    <WixPatternsProvider>
+      <MyCollectionPage />
+    </WixPatternsProvider>
+  );
+}
+
+// MyCollectionPage.tsx
+import { Table, useTableCollection } from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+
+function MyCollectionPage() {
+  const state = useTableCollection({
+    queryName: 'my-items',
+    itemKey: (item) => item.id,
+    itemName: (item) => item.name,
+    fetchData: async () => ({ items: [], total: 0 }),
+    filters: {},
+  }); // works — the provider context exists above this component
+  return (
+    <CollectionPage>
+      <Table state={state} columns={[{ title: 'Name', render: (item) => item.name }]} />
+    </CollectionPage>
+  );
+}
+```
+
+Always keep the provider (and router if needed) in the app's root component, and each page in its own file.
+
+When the user needs **multiple pages**, use the `@wix/patterns` routing solution (`PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate`) instead of a separate router. Look up the relevant doc files for setup details.
+
+## How to Look Things Up
+
+**Don't guess which components or props exist — read the doc files first.**
+
+### Finding the right file
+
+- **By name:** Read `node_modules/@wix/patterns/dist/docs/index.json` — it maps every component name to its doc file and category.
+- **By browsing:** List the `dist/docs/` folder. Filenames match component names directly (e.g., `Table.md`, `useTableCollection.md`). Note some names contain spaces (`AI Assistant.md`) or dots (`CollectionPage.Header.md`) — quote paths when searching.
+- **By concept:** Search filenames for keywords (e.g., "filter"). Check `index.json` categories — related components share a category prefix.
+
+### Reading doc files
+
+Each doc contains the component's category, import path, description, code examples, and API props table. **Always check the import statement** — not everything comes from `@wix/patterns` (some use subpaths like `@wix/patterns/provider`).
+
+### Following cross-references
+
+Docs contain relative Storybook URLs like `[TableState](./?path=/story/...--tablestate)`. To resolve these, **use the link text as the filename**: `[TableState](...)` -> read `TableState.md`.
+
+Links to `https://www.docs.wixdesignsystem.com/` are external (Wix Design System) — not part of `@wix/patterns` docs.
+
+## The Collection → Entity Flow
+
+A collection page and its item form are **two patterns pages**, not a page plus a modal. Getting the table right and then hand-building the "add item" form in a dashboard modal is the most common way this goes wrong.
+
+| Step | What owns it |
+| --- | --- |
+| Navigate from a row / primary action to the item | `usePatternsNavigate()` → `navigateToEntityPage({ path, entity })` |
+| Register the route | `PatternsReactRoute` inside `PatternsReactRouter` |
+| Fetch, save, validation, dirty state, skeletons, errors | `useEntityPage({ fetch, onSave })` |
+| Form state and field binding | `useForm` / `useController` from `@wix/patterns/form` |
+| Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
+| The individual fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
+
+`navigateToEntityPage` is preferred over a plain route change because the entity header (title, subtitle, breadcrumbs) renders immediately, without waiting for the fetch.
+
+Read `EntityPage.md`, `useEntityPage.md`, and `usePatternsNavigate.md` before implementing — and note that `useCreateCollection` is **not** about creating items; it returns a function that initializes collection state.
+
+Reserve dashboard modals for genuine dialogs — delete confirmations, short prompts — not entity editing.
+
+## When Patterns Has No Equivalent
+
+A concept is only "missing" from patterns after you've checked `index.json` **and** searched the docs folder by keyword. Then, and only then:
+
+1. Look the component up in `@wix/design-system` via the `wix-design-system` skill.
+2. Render it *inside* the patterns page shell / collection, not as a replacement for it.
+3. If WDS lacks it too, compose from WDS primitives (`Box`, `Card`, `Text`) — never restyle patterns internals or add another UI library.
+
+Anything page- or collection-shaped (page shell, header, table, grid, filters, sorting, paging, row actions, bulk actions) is patterns' territory. If you're about to build one of those from WDS parts, you skipped a lookup.
+
+## Tips
+
+- **Compound components** have separate docs per sub-part: `CollectionPage.md`, `CollectionPage.Header.md`, `CollectionPage.Content.md`.
+- **Hook docs** list configuration options as props in the API table.
+- **Type docs** (e.g., `TableState.md`) describe the shape of state objects.

package/skills/wix-app/references/dashboard-page/WDS_LAYOUT.md

@@ -0,0 +1,187 @@
+# Dashboard Page Layout Guidelines
+
+Layout and spacing guidance for dashboard page content. Wix Design System design language — the 6px base unit, the 12-column grid, spacing tokens, and the common content layouts.
+
+> **Scope — read this in the right order.** On a dashboard page, `@wix/patterns` owns the page shell (`CollectionPage` / `EntityPage` / `SettingsPage`) and everything collection-shaped: tables, grids, filters, sorting, paging, row and bulk actions, empty states. This file describes how to lay out content **inside** that shell. It is not a licence to build the shell, a table, or a filter bar out of raw WDS — see [Component Selection Order](../../SKILL.md#component-selection-order) and [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md) first.
+>
+> Where a patterns page component already establishes structure (page header, content area, sticky footer, table/grid layout), follow the patterns component's own API rather than reproducing the grid by hand. Use the guidance below for the parts patterns leaves to you: cards, forms, statistics rows, marketing sections, and spacing between them.
+
+
+Layout determines how users interact with your dashboard content. It establishes the structure, hierarchy, and rhythm of your dashboard page, contributing to the overall coherence and user experience. By making mindful and calculated choices in how you organize your content, users can move around more smoothly, saving time and frustration when completing tasks.
+
+### Design Principles
+
+To create dashboard pages optimized for user experience, follow these design principles:
+
+1. **Consistent:** Maintain repetitive layouts and content patterns for intuitive and easy-to-read pages.
+2. **Inclusive:** Create layouts and content that adapt well to various screen sizes.
+3. **Balanced:** Emphasize the priority of regions and content elements through deliberate management of size and white space.
+4. **Connected:** Minimize the distance between related regions or content elements to enhance cohesion and navigation.
+
+
+### Screen Size
+
+Dashboard pages are designed to accommodate various screen sizes rather than being tailored to one specific resolution. The primary content should be at the top of the page to ensure users immediately understand the purpose of the page.
+
+> **Note:** Content displayed in the top 600 pixels of the page will be visible for the majority of users.
+
+
+### Base Unit
+
+The base unit establishes the increment by which all elements and measurements are multiplied. This practice ensures consistency in the spacing and sizing of design elements.
+
+> **Note:** The design system is based on a 6px unit.
+
+The layout grid, spacing tokens, and nearly all visual elements and sizes adhere to multiples of six (6, 12, 18, 24, etc.), with only occasional exceptions.
+
+| TOKEN | SIZE | USE FOR |
+|-------|------|---------|
+| SP1 | 6px | Spacing between components |
+| SP2 | 12px | Spacing between components |
+| SP3 | 18px | Spacing between components |
+| SP4 | 24px | Spacing between components, layout spacing |
+| SP5 | 30px | Layout spacing |
+| SP6 | 36px | Layout spacing |
+| SP7 | 42px | Layout spacing |
+| SP8 | 48px | Layout spacing |
+| SP10 | 54px | Layout spacing |
+| SP11 | 60px | Layout spacing |
+
+
+### Layout Structure
+
+To best design the layout for your app, understand:
+
+1. The core frame of the app (Application frame)
+2. The placement and alignment of each segment within the grid layout (Grid layout)
+3. The content to appear in the grid (Common layouts)
+
+#### Application Frame
+
+The dashboard app frame is used by the majority of Wix applications settings. Dashboard pages consist of 4 areas:
+
+| AREA | USAGE |
+|------|-------|
+| 1. Global navigation (top bar) | General navigation at the top of a page which allows users to navigate between different environments. Full width container with a fixed height of 48px. |
+| 2. Sidebar navigation | Local navigation of an environment. Container with a fixed width of 228px. |
+| 3. Content area | Page content area with a width that's adaptive to screen size. |
+| 4. Side panel (optional) | An optional panel that shows additional actions or content associated with the content of a page. Fixed width of 420px. Can either overlay the main content area or push it from the right side. |
+
+**Side Panel Guidelines:**
+- Let the side panel overlay main content when it contains supplementary actions or settings, such as data filters
+- Push main content with the side panel when users must see the full context to continue
+
+
+#### Grid Layout
+
+The system uses a fluid grid layout with a fixed maximum width. It uses columns that scale and resize the content accordingly.
+
+The grid is constructed from 3 elements:
+- **Columns** - The design system uses a 12-column grid. Column width is fluid and changes according to the page width.
+- **Gutters** - The gaps between the columns. Gutter width has a fixed value of 24px.
+- **Margins** - By default, a page's content area has 48px side margins and a 48px bottom margin.
+
+**Grid Specifications:**
+- Minimum content area width: 864 pixels (each grid column is 50px wide)
+- Maximum content area width: 1248px (each column is 82px wide)
+- Wider screens maintain 1248px content width with side margins stretching to center content
+- Use 24px gap between cards both vertically and horizontally
+
+
+### Common Layouts
+
+Page layouts can be divided by intention into the following types:
+
+#### 1. Form Layouts
+
+Forms are pages that allow users to fill in data or edit existing data. Two variations:
+
+- **2/3 layout with optional sidebar (8/4 column split)** - Provides flexibility to expose primary and secondary content at the same time
+- **Full width (12 columns)** - Supports advanced product needs with complex structures
+
+Both form page layouts include mandatory **Save** and **Cancel** actions in the header and footer areas.
+
+**2/3 Layout Best Practices:**
+- Use to expose primary and secondary content at the same time
+- Keep the form easy to scan and comprehend
+- Display a live content preview on the side (widget can be sticky)
+- Use 8 columns for forms to keep text lines and input fields narrow for quicker reading
+- Bring actions closer to related titles (e.g., toggle switches near settings)
+
+**Full Width Layout Best Practices:**
+- Use when a form includes complex structures such as tables
+- Use for list items that contain many data columns
+
+**Combining Layouts:**
+- Avoid coast-to-coast inputs; keep inputs to 2/3 width of a card, or lay them out in two columns
+- Use white space on the right side for content preview
+- Use full width for tables with many columns and dividers that separate sections
+
+> **Note:** A column is easy to read if it is wide enough to accommodate an average of 10 words per line.
+
+#### 2. Display Layouts
+
+Display pages showcase data or content without accepting input from users. They can contain minor actions such as data filtering.
+
+**List (Table):**
+- Tables display large data sets and provide users with a quick overview
+- Use a 12-column layout for tables
+- Enables users to manipulate and act on a data set
+
+**List (Grid) Options:**
+- 2 columns (6/6 split) - For items with lengthy descriptions
+- 3 columns (4/4/4 split) - For visual items with multiple data types
+- 4 columns (3/3/3/3 split) - For user-generated galleries and collections, reveals up to 50% more content above the fold than 4/4/4
+- Custom - For mixed content needs
+
+**Grid Selection Considerations:**
+- Total amount of items to show
+- Content to display in each list item
+- What objects the list items reflect (match physical shapes when applicable)
+
+**Dashboards:**
+Display different types of data on a specific topic using a combination grid.
+
+Column span recommendations:
+- **3 or 4 columns** - For list items, previews, marketing, statistics, and charts
+- **12 columns (full width)** - For tables and marketing content
+- **8 columns** - For lists, tables with few data columns, setup wizards, and charts
+- **6 columns** - For lists, tables with few data columns, and statistics
+
+**Empty States:**
+- Use full width layout for empty state of a page
+- Indicates feature/product has no data yet, all data cleared, or not set up yet
+- Include clear CTA indicating what to do to fill the page
+- Can combine with other layout elements such as tabs, statistics widgets, or marketing cards
+
+#### 3. Marketing Layouts
+
+Marketing pages promote new products that site owners are not aware of yet. Built using the `<MarketingPageLayout/>` component split into 2 columns:
+
+1. Promo messaging
+2. Visual representation of product and features
+
+Optional footer area can display features or testimonials list.
+
+#### 4. Wizard Layouts
+
+Wizard pages guide users through setting up a product or feature. They split complex forms into steps for easier completion.
+
+**Entry Points:**
+- A marketing page
+- A marketing card
+- The primary action of a page
+- An empty state
+
+> **Note:** Wizards must have a final destination. After completing all steps, users should end up on a relevant page: a dashboard, a details page, or any other relevant location.
+
+
+### Related WDS Components (content inside the shell)
+
+These are content-level building blocks. They do **not** replace the `@wix/patterns` page shell.
+
+- `<Layout />` / `<Cell />` - Grid layout container for content within a page's content area
+- `<Card />` - Content container with 24px gaps between cards
+- `<MarketingPageLayout />` - Marketing page wrapper (marketing pages only — these have no collection, so no patterns shell applies)
+
+> **On WDS `<Page />`:** do not use it as the wrapper for a `@wix/patterns` dashboard page. The patterns page component (`CollectionPage` / `EntityPage` / `SettingsPage`) is the shell and already provides the header, content area, and scroll behavior. Reach for WDS `<Page />` only on a page that uses no patterns shell at all.

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

@@ -32,7 +32,7 @@ implementation detail.
 
 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
+3. **Play/pause button** — overlay `<button>` with inline SVG icon + CSS positioning and optional hover-only visibility; **must be a named part** (`classNames('component-name-play-button', styles.playButton)`) with hover/focus design-state selectors
 4. **Modify `component.preview.tsx`** — suppress autoplay in editor design mode
 5. **Respect `prefers-reduced-motion`** — suppress autoplay when the OS requests reduced motion
 
@@ -117,10 +117,39 @@ Position the button absolutely so it overlays the content without pushing other
   inset-inline-end: 5px;
   inset-block-start: 5px;
 }
+
+/* Design-state selectors: pair native pseudo-class with editor-injected modifier class.
+   The editor applies the modifier class (e.g. my-animation-play-button--hover) when
+   the site owner previews that state in the design panel, so both selectors must exist. */
+.playButton:global(.my-animation-play-button--hover),
+.playButton:hover {
+  /* e.g. background: rgba(255, 255, 255, 1); */
+}
+
+.playButton:global(.my-animation-play-button--focus),
+.playButton:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+}
+```
+
+```tsx
+{/* ✅ Named part: play/pause is always a named part — site owners can style it independently */}
+<button
+  type="button"
+  className={classNames('my-animation-play-button', styles.playButton)}
+  onClick={isPlaying ? handlePause : handleResume}
+  aria-label={isPlaying ? 'Pause' : 'Play'}
+>
+  {isPlaying ? <PauseIcon /> : <PlayIcon />}
+</button>
 ```
 
 ```css
-/* pauseButtonVisibility variants — structural CSS, not named-part rules */
+/* pauseButtonVisibility visibility behavior — descendant CSS is allowed here
+   because these rules control the button's *visibility*, not its styling surface.
+   The button itself is a named part (classNames('...-play-button', styles.playButton))
+   and must carry both a global class and design-state selectors (see above). */
 
 /* showOnHover (default) */
 .root[data-pause-button-visibility="showOnHover"] .playButton {

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

@@ -187,6 +187,12 @@ When creating TypeScript interfaces for component props, use types from `@wix/ed
 import type { Link } from "@wix/editor-react-types"; // Reference at node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts
 ```
 
+For **function event handler props** (`onClick`, `onDblClick`, `onChange`, `onFocus`, `onBlur`, `onMouseIn`, `onMouseOut`) and custom callbacks, follow [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md). Key rules:
+
+- Use the exact SDK prop names from that file — the manifest system recognizes them
+- Wire them to the correct DOM events (note: `onDblClick` → `onDoubleClick`, `onMouseIn` → `onMouseEnter`, `onMouseOut` → `onMouseLeave`)
+- Custom callbacks not tied to DOM events use `() => void` (no React event parameter)
+
 ### External resources are forbidden
 
 All resources rendered or fetched by the component (images, icons, fonts,
@@ -476,4 +482,3 @@ 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/FUNCTION-HANDLERS.md

@@ -0,0 +1,167 @@
+# Function Event Handlers
+
+Rules and patterns for adding function event handler props to an Editor React component's TypeScript interface, wiring them to DOM events, and declaring custom callbacks.
+
+---
+
+## Rules
+
+### Standard SDK Event Handlers
+
+These are the standard event handler props the editor SDK exposes to site owners. Use the exact prop names — ZeroConfig and the manifest system recognize them.
+
+| Prop name    | React DOM event | Type                                             |
+| ------------ | --------------- | ------------------------------------------------ |
+| `onClick`    | `onClick`       | `(event: React.MouseEvent) => void`              |
+| `onDblClick` | `onDoubleClick` | `(event: React.MouseEvent) => void`              |
+| `onChange`   | `onChange`      | `(event: React.ChangeEvent<HTMLElement>) => void` |
+| `onFocus`    | `onFocus`       | `(event: React.FocusEvent) => void`              |
+| `onBlur`     | `onBlur`        | `(event: React.FocusEvent) => void`              |
+| `onMouseIn`  | `onMouseEnter`  | `(event: React.MouseEvent) => void`              |
+| `onMouseOut` | `onMouseLeave`  | `(event: React.MouseEvent) => void`              |
+
+Three props have a **name mismatch** between the SDK prop and the DOM event: `onDblClick` → `onDoubleClick`, `onMouseIn` → `onMouseEnter`, `onMouseOut` → `onMouseLeave`.
+
+### Declaring Standard Handler Props
+
+Declare standard handlers inline with the exact SDK prop names and React event types:
+
+```typescript
+interface MyComponentProps {
+  label?: string;
+  onClick?: (event: React.MouseEvent) => void;
+  onDblClick?: (event: React.MouseEvent) => void;
+  onChange?: (event: React.ChangeEvent<HTMLElement>) => void;
+  onFocus?: (event: React.FocusEvent) => void;
+  onBlur?: (event: React.FocusEvent) => void;
+  onMouseIn?: (event: React.MouseEvent) => void;
+  onMouseOut?: (event: React.MouseEvent) => void;
+}
+```
+
+Only declare handlers the component actually exposes. Do not add all seven if the component only handles two.
+
+### Wiring Standard Handlers to DOM Events
+
+Destructure the props and pass them to the correct DOM event — applying the name mappings:
+
+```typescript
+export const MyComponent = (props: MyComponentProps) => {
+  const { onClick, onDblClick, onFocus, onBlur, onMouseIn, onMouseOut } = props;
+  return (
+    <div
+      onClick={onClick}
+      onDoubleClick={onDblClick}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      onMouseEnter={onMouseIn}
+      onMouseLeave={onMouseOut}
+    >
+      {/* ... */}
+    </div>
+  );
+};
+```
+
+### Custom Callbacks
+
+Component-specific callbacks that do not correspond to a DOM event (e.g., `onPlay`, `onPause`, `onEnded`, `onTimeupdate`) are **not** standard SDK event handlers. Type them as `() => void` — no React event parameter:
+
+```typescript
+interface VideoPlayerProps {
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+}
+```
+
+Pass them directly to the underlying element — no name remapping needed:
+
+```typescript
+export const VideoPlayer = (props: VideoPlayerProps) => {
+  const { onPlay, onPause, onEnded } = props;
+  return <video onPlay={onPlay} onPause={onPause} onEnded={onEnded} />;
+};
+```
+
+---
+
+## Common Mistakes
+
+### Passing SDK prop name directly to DOM instead of remapping
+
+**❌ Wrong:**
+
+```typescript
+export const MyComponent = (props: MyComponentProps) => {
+  const { onMouseIn, onMouseOut, onDblClick } = props;
+  return (
+    <div
+      onMouseIn={onMouseIn} // ❌ not a valid React DOM prop
+      onMouseOut={onMouseOut} // ❌ not a valid React DOM prop
+      onDblClick={onDblClick} // ❌ not a valid React DOM prop
+    />
+  );
+};
+```
+
+**✅ Correct:**
+
+```typescript
+export const MyComponent = (props: MyComponentProps) => {
+  const { onMouseIn, onMouseOut, onDblClick } = props;
+  return (
+    <div
+      onMouseEnter={onMouseIn} // ✅ onMouseIn → onMouseEnter
+      onMouseLeave={onMouseOut} // ✅ onMouseOut → onMouseLeave
+      onDoubleClick={onDblClick} // ✅ onDblClick → onDoubleClick
+    />
+  );
+};
+```
+
+### Adding a React event parameter to custom callbacks
+
+**❌ Wrong:**
+
+```typescript
+interface VideoPlayerProps {
+  onPlay?: (event: React.SyntheticEvent) => void; // ❌ event param on custom callback
+  onEnded?: (event: React.SyntheticEvent) => void; // ❌ event param on custom callback
+}
+```
+
+**✅ Correct:**
+
+```typescript
+interface VideoPlayerProps {
+  onPlay?: () => void; // ✅ no event param
+  onEnded?: () => void; // ✅ no event param
+}
+```
+
+**Why:** Custom callbacks are component-level notifications to the site owner, not DOM event forwarders. They carry no event object — the SDK passes no event to them.
+
+### Using the DOM event name as the SDK prop name
+
+**❌ Wrong:**
+
+```typescript
+interface MyComponentProps {
+  onDoubleClick?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+  onMouseEnter?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+  onMouseLeave?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+}
+```
+
+**✅ Correct:**
+
+```typescript
+interface MyComponentProps {
+  onDblClick?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+  onMouseIn?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+  onMouseOut?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+}
+```
+
+**Why:** The SDK prop names (`onDblClick`, `onMouseIn`, `onMouseOut`) are what ZeroConfig and the manifest system register. Using DOM names breaks the editor's event wiring.

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

@@ -9,6 +9,7 @@ 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
+- [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md) — Standard SDK event handler props, DOM wiring, custom callbacks
 - [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
 - [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
 
@@ -110,7 +111,7 @@ Unless explicitly specified as a component capability/API in the specification,
 **External handlers (only when specified):**
 
 - Only expose handlers that are explicitly listed as component capabilities
-- Example: If specification says "onClick callback for external control", then add `onClick?: () => void` to props
+- Use the standard SDK prop names and DOM wiring rules from [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md)
 
 **Child component handlers:**
 
@@ -170,4 +171,3 @@ See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.
 **Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; toggle custom-state classes from data ([`DESIGN-STATES.md`](DESIGN-STATES.md))
 
 **Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md)). If the request uses the words **branded**, **themed**, or **brand-aware**, also apply [`BRANDED-COMPONENTS.md`](BRANDED-COMPONENTS.md) before writing CSS.
-