@wix/agent-skills 1.19.1 → 1.20.0

package/package.json

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

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

@@ -110,7 +110,7 @@ extension configuration, and supporting files.
 | Trigger | Read |
 | --- | --- |
 | Interactive/selectable part or custom state | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
-| Public event callbacks added or changed | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
+| Creating interactive components or changing interactions/callbacks | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
 | Browser APIs, effects, or time-dependent output | [`SSR.md`](editor-react-component/SSR.md) |
 | Non-established CSS feature or DOM API, or user asks for one by name | [`BROWSER-SUPPORT.md`](editor-react-component/BROWSER-SUPPORT.md) |
 | `npx wix build` or manifest generation exits with an error | [`MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md) |

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

@@ -1,7 +1,7 @@
 
 # Wix Service Plugin (SPI) Builder
 
-Service plugins are a set of APIs defined by Wix that let you inject custom logic into the existing backend flows of Wix business solutions or introduce entirely new flows. When you implement a service plugin, Wix calls your custom functions during specific flows. Common use cases include eCommerce customization (shipping, fees, payment settings, validations) and Bookings customization (staff sorting).
+Service plugins are a set of APIs defined by Wix that let you inject custom logic into the existing backend flows of Wix business solutions or introduce entirely new flows. When you implement a service plugin, Wix calls your custom functions during specific flows. Common use cases include eCommerce customization (shipping, fees, payment settings, validations), Bookings customization (staff sorting, booking validation, policies, pricing, availability), Realtime channel permissions, and exposing tools to the Wix AI assistant.
 
 ## Scaffold
 
@@ -16,12 +16,19 @@ Use `wix generate --params` with `extensionType: SERVICE_PLUGIN`. `pluginType` i
 | `ECOM_PAYMENT_SETTINGS` | Payment Settings | No |
 | `GIFT_CARDS_PROVIDER` | Gift Cards Provider | **Yes** |
 | `STAFF_SORTING_PROVIDER` | Bookings Staff Sorting | No |
+| `BOOKINGS_VALIDATION_PROVIDER` | Bookings Validation | No |
+| `BOOKING_POLICY_PROVIDER` | Booking Policy | No |
+| `BOOKINGS_PRICING_PROVIDER` | Bookings Pricing Provider | No |
+| `AVAILABILITY_TIME_SLOTS_CONFIGURATION_PROVIDER` | Availability Time Slots Configuration | No |
 | `REALTIME_PERMISSIONS_PROVIDER` | Realtime Permissions Provider | No |
+| `TOOLS_PROVIDER_CONFIG` | Tools Provider | No |
 
 > **Singular types** — `ECOM_SHIPPING_RATES`, `ECOM_DISCOUNTS_TRIGGER`, and `GIFT_CARDS_PROVIDER` are **singular**: only one component of each type is allowed per app. Never scaffold or include two components of the same singular type in the same app payload.
 
 `name` must be lowercase alphanumeric + hyphens, max 19 characters. The CLI generates the folder, `plugin.ts`, the builder file, the UUID, and the `src/extensions.ts` registration with the appropriate builder method for the SPI type. Some SPI types (e.g., `ECOM_SHIPPING_RATES`) get a `description` placeholder field in the generated builder — replace it with your real copy.
 
+> **Missing dependency after scaffolding:** `wix generate` adds the SPI's SDK package (e.g. `@wix/bookings`, `@wix/realtime`) to `package.json`, but does not always install it into `node_modules`. If `tsc`/`wix build` reports the import as unresolved right after scaffolding, run `npm install <package>` for just that package (no need for a full reinstall) before debugging further.
+
 ## References
 
 **You MUST read the relevant reference document before implementing an SPI**, and **call `ReadFullDocsMethodSchema`** with the docs URL it points at to get the exact request/response types — **do NOT edit code until you have the schema**. If the schema alone isn't enough, follow up with `ReadFullDocsArticle` on the same URL for prose explanations and additional code examples. Each reference also contains the correct imports, handler signatures, response structures, and a worked example.
@@ -35,6 +42,12 @@ Use `wix generate --params` with `extensionType: SERVICE_PLUGIN`. `pluginType` i
 | Shipping Rates | [SHIPPING-RATES.md](service-plugin/SHIPPING-RATES.md) |
 | Validations | [VALIDATIONS.md](service-plugin/VALIDATIONS.md) |
 | Bookings Staff Sorting | [BOOKINGS-STAFF-SORTING.md](service-plugin/BOOKINGS-STAFF-SORTING.md) |
+| Bookings Validation | [BOOKINGS-VALIDATION.md](service-plugin/BOOKINGS-VALIDATION.md) |
+| Booking Policy | [BOOKING-POLICY.md](service-plugin/BOOKING-POLICY.md) |
+| Bookings Pricing Provider | [BOOKINGS-PRICING.md](service-plugin/BOOKINGS-PRICING.md) |
+| Availability Time Slots Configuration | [AVAILABILITY-TIME-SLOTS-CONFIGURATION.md](service-plugin/AVAILABILITY-TIME-SLOTS-CONFIGURATION.md) |
+| Realtime Permissions Provider | [REALTIME-PERMISSIONS.md](service-plugin/REALTIME-PERMISSIONS.md) |
+| Tools Provider | [TOOLS_PROVIDER.md](service-plugin/TOOLS_PROVIDER.md) |
 
 ## Implementation Pattern
 

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

@@ -192,13 +192,18 @@ the `a11y` contract, and SSR safety. Verify what it cannot see:
   meaning stays in the accessibility tree.
 - State hidden through `--display` or transforms agrees with focusability and
   the accessibility tree; disabled and inert states behave consistently.
-- Custom widgets (tabs, menus, dialogs, sliders) implement their keyboard
-  pattern: arrow keys, Home/End, Escape, roving `tabIndex`.
+- Custom widgets (tabs, menus, dialogs, sliders) implement their full APG
+  keyboard pattern (arrow keys, Home/End, Escape, roving `tabIndex`) and
+  structural relationships, or use a plain native element instead of
+  borrowing the role.
 - Interactive controls have a hit area of at least 24×24 CSS px and visible
   focus.
 - The root implements the direction contract, and every `ReactNode` slot
   isolates nested content with `dir="ltr"`.
 
+- An auto-rotating set of readable parallel items uses `aria-live="off"` while
+  it is rotating and `aria-live="polite"` while it is stopped.
+
 ## Pre-Fix Checks for Non-Interactive Controls
 
 Before adding `role="button"`, `tabIndex`, and keyboard handlers to a non-native

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

@@ -9,10 +9,12 @@ Every such component must ship an on-stage **play/pause button**.
 
 - [Apply When](#apply-when)
 - [Required Contract](#required-contract)
+- [Announce Manually Selected Parallel Content](#announce-manually-selected-parallel-content)
 - [Define Props](#1-define-props)
 - [Manage Playback State](#2-manage-playback-state)
 - [Add the Play/Pause Button](#3-add-the-playpause-button)
 - [Suppress Autoplay in `component.preview.tsx`](#4-suppress-autoplay-in-componentpreviewtsx)
+- [Edit the generated `component.preview.tsx`](#edit-the-generated-componentpreviewtsx)
 - [Checklist](#checklist)
 
 ## Apply When
@@ -41,12 +43,26 @@ implementation detail.
    existing playback prop names and add only the missing safety contract.
    Carousels, sliders, slideshows, and galleries **must** define `autoPlay`
    (default `true`).
-2. **Playback state** — `isPlaying` + `handlePause` / `handleResume`
+2. **Playback state** — play/pause toggle state, derived `isPlaying`, and
+   `handlePause` / `handleResume`
 3. **Play/pause button** — overlay `<button>` with inline SVG icon and CSS
    positioning; it must be a named part with `elementProps` wiring, a hover
    design state, and a standalone `:focus-visible` keyboard indicator
 4. **Modify `component.preview.tsx`** — suppress autoplay in editor design mode
-5. **Respect `prefers-reduced-motion`** — suppress autoplay when the OS requests reduced motion
+5. **Respect `prefers-reduced-motion`** — start paused when the OS requests reduced motion
+
+### Announce Manually Selected Parallel Content
+
+For carousel-like components that swap readable parallel items, make the item
+wrapper a live region:
+
+- Use `aria-live={isPlaying ? 'off' : 'polite'}` and `aria-atomic="false"`.
+- `isPlaying = isPlayOn && !isHovered && !isStoppedByFocus`. Reduced motion
+  starts paused; editor mode, `autoPlay={false}`, and pause set it false.
+  Keyboard focus remains stopped until the rotation control restarts; hover
+  pauses temporarily.
+- Previous/next changes items. Use root `onMouseEnter`/`onMouseLeave`;
+  leaving resumes unless focus has stopped rotation.
 
 ## 1. Define Props
 
@@ -83,40 +99,48 @@ support repeat behavior; do not add it only to match the example.
 
 ## 2. Manage Playback State
 
-Track play/pause state with `useState`. Initialize it from `autoPlay` and the OS reduced-motion preference — when the visitor has requested reduced motion, the animation starts paused:
+Track play/pause button state with `useState`. Initialize it from `autoPlay`
+and reduced motion; reduced motion starts paused, but a visitor can start it.
 
 ```tsx
 import { useReducedMotion } from '@wix/react-component-utils';
 
-// inside the component:
 const reducedMotion = useReducedMotion();
 
-const [isPlaying, setIsPlaying] = React.useState((autoPlay ?? true) && !reducedMotion);
-
-// when autoPlay prop changes, re-sync (but still respect reduced motion)
-React.useEffect(() => {
-  setIsPlaying((autoPlay ?? true) && !reducedMotion);
-}, [autoPlay]);
+const [isPlayOn, setIsPlayOn] = React.useState(() => (autoPlay ?? true) && !reducedMotion);
 
-// when reduced motion is enabled, suppress playback; never re-enable on its own
-// (visitor may have manually paused — don't restart against their will)
+const skipInitialAutoPlaySync = React.useRef(true);
 React.useEffect(() => {
-  if (reducedMotion) {
-    setIsPlaying(false);
+  if (skipInitialAutoPlaySync.current) {
+    skipInitialAutoPlaySync.current = false;
+    return;
   }
-}, [reducedMotion]);
+  setIsPlayOn(autoPlay ?? true);
+}, [autoPlay]);
 
-const handlePause = () => setIsPlaying(false);
-const handleResume = () => setIsPlaying(true);
+const handlePause = () => setIsPlayOn(false);
+const handleResume = () => setIsPlayOn(true);
 ```
 
-**`reducedMotion`** is `true` when the hook reports that reduced motion is enabled. When active, the animation starts paused — the visitor can still press the play button to start it manually. It is a runtime browser signal, not a manifest/data prop; never expose it as a component prop or in the manifest.
+`reducedMotion` is a runtime signal, not a manifest/data prop.
+
+Derive runtime playback from `isPlayOn` plus only needed conditions. Without
+another condition, use `const isPlaying = isPlayOn`. A carousel, slideshow,
+slider, or gallery also uses hover and focus-stop state:
+
+```tsx
+const isPlaying = isPlayOn && !isHovered && !isStoppedByFocus;
+```
 
-Pass `isPlaying` to the animation renderer and toggle between `handlePause` / `handleResume` on button click.
+Pass `isPlaying` to the renderer. The button uses `isPlayOn` and toggles
+between `handlePause` / `handleResume` on click. In a carousel-like component,
+focus entering anything except that button sets `isPlayOn` to `false` and
+`isStoppedByFocus` to `true`; `handleResume` sets `isPlayOn` to `true` and
+clears `isStoppedByFocus`.
 
 ## 3. Add the 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.
+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 and color of SVG should be controlled by CSS variables declared on the button level: --icon-size and --icon-color.
 
 Position the button absolutely so it overlays the content without pushing other elements out of place:
 
@@ -128,14 +152,14 @@ Position the button absolutely so it overlays the content without pushing other
 }
 
 .playButton {
+  --icon-size: 20px;
+  --icon-color: #ffffff;
   position: absolute;
   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. */
+/* Design-state selectors: pair native pseudo-class with editor-injected modifier class. */
 .playButton:global(.my-animation-play-button--hover),
 .playButton:hover {
   /* e.g. background: rgba(255, 255, 255, 1); */
@@ -177,12 +201,12 @@ Wire the named part completely:
     styles.playButton,
     elementProps?.playButton?.className,
   )}
-  onClick={isPlaying ? handlePause : handleResume}
+  onClick={isPlayOn ? handlePause : handleResume}
   aria-label={
-    isPlaying ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton
+    isPlayOn ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton
   }
 >
-  {isPlaying ? <PauseIcon /> : <PlayIcon />}
+  {isPlayOn ? <PauseIcon /> : <PlayIcon />}
 </button>
 ```
 
@@ -233,8 +257,7 @@ const ComponentNamePreview: FC<ComponentProps<typeof Component>> = (props) => {
 };
 ```
 
-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.
+Design mode stops autoplay and exposes the control; preview uses the user's values.
 
 ## Checklist
 
@@ -243,6 +266,8 @@ In preview mode (`isEditMode` is `false`) → both use the user's configured val
       present only when repeat behavior is supported.
 - [ ] Reduced motion starts paused and never restarts playback automatically.
 - [ ] The play/pause button is a fully wired named part with a stable accessible name.
+- [ ] Both icons inherit button-owned `--icon-size` for width and height and
+      `--icon-color` via `color` and `currentColor` for fill or stroke.
 - [ ] Hover has a paired editor design state; `:focus-visible` remains a
       standalone keyboard indicator.
 - [ ] Hover-only visibility changes behavior, not the button's editable styling surface.

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

@@ -33,6 +33,10 @@ export type PlanCardProps = {
   heading?: string;
   plans?: Array<Plan>;
   onClick?: (event: React.MouseEvent) => void;
+  onMouseIn?: (event: React.MouseEvent) => void;
+  onMouseOut?: (event: React.MouseEvent) => void;
+  onFocus?: (event: React.FocusEvent) => void;
+  onBlur?: (event: React.FocusEvent) => void;
 
   elementProps?: {
     cta?: { className?: string; href?: string };
@@ -47,9 +51,8 @@ Rules:
   code. Do not add one-off ARIA props or spread the whole object.
 - Expose only content and behavior that the site owner controls. Keep derived
   values internal.
-- Add only callbacks required by the component specification. Use supported SDK
-  event names and types for public callbacks; keep implementation-only handlers
-  internal.
+- Default to common optional SDK callbacks by capability; add specialized ones
+  when requested. Keep implementation handlers internal.
 - Use `Array<T>`, not `T[]`, for exported arrays.
 
 ## Numeric Range Constraints
@@ -176,7 +179,16 @@ export const defaultProps = {
 ### Wix Data Types
 
 Use `Image`, `Link`, `Video`, `Audio`, `VectorArt`, `RichText` from
-`@wix/editor-react-types`. See `node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts` for the full list.
+`@wix/editor-react-types`. Model authored media with the corresponding Wix
+media type, whether it is a top-level prop or a field in an array item. Name
+the field for the media itself (`image`, `video`, `audio`, and so on), not for
+one representation of it.
+
+Do not represent media as a URL/source string or split its metadata across
+primitive props. Preserve the media object through the public contract so the
+component can consume all of its supported data. See
+`node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts` for the
+full list.
 
 ## Defaults and Resources
 
@@ -242,5 +254,6 @@ Do not extract tiny fragments merely to satisfy a line-count threshold.
 - [ ] Named inner parts have `elementProps` wiring; leaf components avoid exported `children`.
 - [ ] One-body-visible arrays use the active-item contract and render all bodies.
 - [ ] Array elements are objects with semantic named fields. No separate `id` field added to item types; React keys use item fields (stable unique → slug → index), not a typed `id`.
+- [ ] Authored media uses the corresponding Wix media type, not URL/source strings or flattened metadata.
 - [ ] Defaults live only in the props file (no JSX fallbacks).
 - [ ] Resources are Wix-hosted, prop-supplied, or locally bundled.

package/skills/wix-app/references/editor-react-component/FUNCTION-HANDLERS.md

@@ -1,57 +1,92 @@
 # Function Handlers
 
-Use this reference only when the component specification exposes callbacks to
-site owners. Keep implementation-only handlers out of the public props type.
+When creating a component or changing interactions, expose common optional
+callbacks by capability, without requiring an explicit request.
+
+## Default Support
+
+Apply defaults to the public interaction surface:
+
+| Component capability | Default optional props |
+| --- | --- |
+| Pointer/click interaction, including native controls | `onClick`, `onMouseIn`, `onMouseOut` |
+| Focusable control | `onFocus`, `onBlur` |
+| Editable value, text, or selection | `onChange` |
+
+Combine matching rows; leave decorative elements alone. Explicit API restrictions
+override defaults. Specialized callbacks (`onDblClick`, `onPlay`, `onEnded`,
+`onActivate`, etc.) require a request.
+
+Classify composite controls by their interactive descendants. For example, a
+radio-based rating input matches all three rows and exposes all six callbacks.
 
 ## Standard SDK Handlers
 
 Use the exact SDK prop name and wire it to the matching React DOM event.
 
-| SDK prop | React DOM prop | 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` |
-
-Declare only the handlers the component actually exposes.
+| SDK prop | React DOM prop | Type | Zero config `domEvent` |
+| --- | --- | --- | --- |
+| `onClick` | `onClick` | `(event: React.MouseEvent) => void` | `POINTER` |
+| `onDblClick` | `onDoubleClick` | `(event: React.MouseEvent) => void` | `POINTER` |
+| `onChange` | `onChange` | `(event: React.ChangeEvent<HTMLElement>) => void` | `CHANGE` |
+| `onFocus` | `onFocus` | `(event: React.FocusEvent) => void` | `FOCUS` |
+| `onBlur` | `onBlur` | `(event: React.FocusEvent) => void` | `FOCUS` |
+| `onMouseIn` | `onMouseEnter` | `(event: React.MouseEvent) => void` | `POINTER` |
+| `onMouseOut` | `onMouseLeave` | `(event: React.MouseEvent) => void` | `POINTER` |
+
+React `onChange` fires on live text edits and selection changes. Pass that
+`ChangeEvent` directly. Do not synthesize a commit callback from blur or cast a
+`FocusEvent` to `ChangeEvent`.
+
+Callbacks only notify; they never enable controlled mode. Internal handlers run
+component logic, then call the optional callback once, preserving event payloads
+and disabled/read-only guards. Behavior must work without callbacks or consumer
+prop updates. Forward directly when no internal logic is needed. Add controlled
+state only when requested; preserve existing controlled APIs when editing.
 
 ```tsx
+import * as React from 'react';
+
 export type ActionProps = {
   onClick?: (event: React.MouseEvent) => void;
-  onDblClick?: (event: React.MouseEvent) => void;
   onMouseIn?: (event: React.MouseEvent) => void;
   onMouseOut?: (event: React.MouseEvent) => void;
+  onFocus?: (event: React.FocusEvent) => void;
+  onBlur?: (event: React.FocusEvent) => void;
 };
 
 export const Action: React.FC<ActionProps> = (props) => {
-  const { onClick, onDblClick, onMouseIn, onMouseOut } = props;
+  const { onClick, onMouseIn, onMouseOut, onFocus, onBlur } = props;
+  const [count, setCount] = React.useState(0);
+
+  const handleClick = (event: React.MouseEvent) => {
+    setCount((value) => value + 1);
+    onClick?.(event);
+  };
 
   return (
     <button
       type="button"
-      onClick={onClick}
-      onDoubleClick={onDblClick}
+      onClick={handleClick}
       onMouseEnter={onMouseIn}
       onMouseLeave={onMouseOut}
-    />
+      onFocus={onFocus}
+      onBlur={onBlur}
+    >
+      Clicked {count} times
+    </button>
   );
 };
 ```
 
-Do not expose DOM names such as `onDoubleClick`, `onMouseEnter`, or
-`onMouseLeave` in the component API; zero config recognizes the SDK names.
+Zero config requires SDK names, not `onDoubleClick`, `onMouseEnter`, or
+`onMouseLeave`, in public props.
 
 ## Custom Callbacks
 
-A component-level notification that is not one of the standard SDK DOM events
-uses `() => void` unless the component contract explicitly defines a serializable
-payload. Do not expose a React synthetic event for custom callbacks.
-
-Use this pattern:
+Custom notifications use `() => void`; zero config emits no event parameter for
+unrecognized callback names. Custom callbacks must not declare React event
+parameters. Use a standard SDK handler above when the event is public:
 
 ```tsx
 export type VideoPlayerProps = {
@@ -62,14 +97,19 @@ export type VideoPlayerProps = {
 
 export const VideoPlayer: React.FC<VideoPlayerProps> = (props) => {
   const { onPlay, onPause, onEnded } = props;
-  return <video onPlay={onPlay} onPause={onPause} onEnded={onEnded} />;
+  return (
+    <video
+      controls
+      onPlay={() => onPlay?.()}
+      onPause={() => onPause?.()}
+      onEnded={() => onEnded?.()}
+    />
+  );
 };
 ```
 
 ## Checklist
 
-- [ ] The specification explicitly requires each public callback.
-- [ ] Standard handler names match the SDK contract exactly.
-- [ ] Mismatched SDK/DOM names are mapped at the rendered element.
-- [ ] Custom callbacks do not leak React event objects.
-- [ ] Internal handlers remain implementation details.
+- [ ] Defaults match capabilities; specialized callbacks are requested.
+- [ ] SDK names, DOM mappings, and payloads match the contract.
+- [ ] Internal behavior works independently and notifies callbacks once.

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

@@ -12,8 +12,7 @@ contracts changed by the request:
 2. Separate user-authored content and stable behavior from derived values and
    visual styling.
 3. Identify interaction and selectable states affected by the request.
-4. Keep implementation behavior internal unless the component specification
-   requests a public callback.
+4. Include common callbacks by capability; keep implementation handlers internal.
 5. Identify runtime concerns such as browser APIs, autoplay, editor-only
    behavior, or live site context before implementation.
 
@@ -49,8 +48,8 @@ export const ProfileCard: React.FC<ProfileCardProps> = (props) => {
 - When local state intentionally mirrors a prop, synchronize it when that prop
   changes. Do not use effect-managed state for a value that can be derived
   during render.
-- Keep implementation-only handlers internal. Expose a callback only when the
-  specification makes it part of the component API.
+- Internal handlers run component behavior, then notify optional callbacks.
+  Callback presence never enables controlled mode.
 
 ### Structure and Parts
 

package/skills/wix-app/references/service-plugin/ADDITIONAL-FEES.md

@@ -87,6 +87,10 @@ additionalFees.provideHandlers({
 });
 ```
 
+## Manual Setup Required
+
+None — confirmed live. Once the app is installed and released, Wix calls this plugin automatically on every cart/checkout calculation; no dashboard configuration or extra API call is needed to "turn it on."
+
 ## Key Implementation Notes
 
 1. **Elevate permissions for API calls** - Use `auth.elevate` from `@wix/essentials` when calling Wix APIs from service plugins

package/skills/wix-app/references/service-plugin/AVAILABILITY-TIME-SLOTS-CONFIGURATION.md

@@ -0,0 +1,118 @@
+# Availability Time Slots Configuration Service Plugin Reference
+
+## Overview
+
+The Availability Time Slots Configuration SPI lets you customize how Wix calculates available time slots for booking services: duration, split interval, buffer time, locations, and required/available resources. Wix calls your `listAvailabilityTimeSlotConfigurations` handler whenever a customer views available times or books a service. [Resources](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/introduction) must already exist before time slot calculation runs.
+
+## ⚠️ `resourceTypeId` is not a placeholder you can invent
+
+`resourceTypes[].resourceTypeId` must be a real resource type ID or Wix rejects every availability query for the service — confirmed live: a made-up GUID here 500s `List Availability Time Slots` and fails booking creation with `FAILED_VALIDATING_AVAILABILITY`, for every service on the site, not just the one you're configuring. If the service is staffed (the common case), use the universal Wix Bookings staff-member resource type ID, which is the same across every site — it is not something you provision or look up per site:
+
+```typescript
+const STAFF_MEMBER_RESOURCE_TYPE_ID = '1cd44cf8-756f-41c3-bd90-3e2ffcaf1155';
+```
+
+For a non-staff resource (a room, piece of equipment, etc.), get the real ID from [Get Resource](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/get-resource) (`resource.typeId`) — never fabricate one.
+
+## ⚠️ `resourceTypes[].resourceIds` — populate it, don't leave it implicit
+
+`resourceIds` ("IDs of resources available for booking within this resource type... may be a subset of all resources in the type") tells Wix *which* resources of that type are valid for this specific service. Omitting it (relying on `resourceTypeId` alone) was part of the same live 500 chain above — once `resourceTypeId` and `scheduleId` were both fixed, availability queries still failed until `resourceIds` was populated too. Get the service's actual assigned staff from [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service)'s `service.staffMemberIds`.
+
+## ⚠️ `scheduleId` is required — omitting it also 500s
+
+The response schema requires `scheduleId` (confirmed live: leaving it out 500s the same as a bad `resourceTypeId`), but it's easy to miss since it's not mentioned in the request/response summary above. Fetch it from the service itself — [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service)'s `service.schedule._id` (REST docs call this field `id`; the SDK's `Service.schedule` type names it `_id`):
+
+```typescript
+import { auth } from "@wix/essentials";
+import { services } from "@wix/bookings";
+
+const elevatedGetService = auth.elevate(services.getService);
+const service = await elevatedGetService(serviceId);
+const scheduleId = service.schedule?._id;
+```
+
+## ⚠️ `locations[]._id` is required when `locationType` is `BUSINESS`
+
+The schema notes `_id` is "returned only for business locations" — read that as *required whenever `locationType: BUSINESS`*, not optional. Omitting it was the third and last piece of the same live 500 chain. Get the service's actual configured locations from [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service)'s `service.locations[]` (each has its own `_id`) rather than hardcoding a bare `{ locationType: "BUSINESS" }`.
+
+## Manual Setup Required
+
+None for activation — Wix calls this plugin automatically once installed and released. But get all three fields above right, or every availability query for every service on the site fails with a bare 500, not just a validation error on the one service you're configuring.
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `listAvailabilityTimeSlotConfigurations` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/availability-time-slots-configuration-service-plugin/list-availability-time-slot-configurations?apiView=SDK |
+
+The request's `services` array (up to 100 entries) lists each service to configure, with the customer's `customerChoices` (selected duration variant and/or add-ons) — the same service GUID can appear more than once with different choices. Your response's `configurations` array must contain exactly one configuration per requested entry, **in the same order**, with `resourceTypes`, `locations`, and `scheduleId` fully populated.
+
+For services with a bookable duration **range** (the customer picks how long to book), return `durationUnit` (`HOUR` or `DAY`) with `minDuration`/`maxDuration` instead of a fixed `duration`; for hourly ranges also return `duration.defaultInMinutes` as the minimum.
+
+## Example: Duration From Add-Ons, Single Resource Type
+
+```typescript
+import { availabilityTimeSlotsConfiguration } from "@wix/bookings/service-plugins";
+import { auth } from "@wix/essentials";
+import { services } from "@wix/bookings";
+
+// Universal Wix Bookings staff-member resource type ID — same on every site, not per-site data.
+const STAFF_MEMBER_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155";
+
+availabilityTimeSlotsConfiguration.provideHandlers({
+  listAvailabilityTimeSlotConfigurations: async (payload) => {
+    const { request } = payload;
+    // services is optional on the request type — default it, or the .map()
+    // calls below fail `tsc` with "possibly undefined."
+    const { services: requestedServices = [] } = request;
+
+    // scheduleId is required in the response but isn't in the request — fetch it per service.
+    const elevatedGetService = auth.elevate(services.getService);
+    const serviceById = new Map(
+      await Promise.all(
+        requestedServices.map(async ({ serviceId }) =>
+          [serviceId, serviceId ? await elevatedGetService(serviceId) : undefined] as const
+        )
+      )
+    );
+
+    const configurations = requestedServices.map(({ serviceId, customerChoices }) => {
+      const baseDuration = 60;
+      const addOnMinutes = (customerChoices?.addOnIds ?? []).length * 15;
+      const service = serviceById.get(serviceId);
+
+      return {
+        serviceId,
+        resourceTypes: [
+          {
+            resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID,
+            resourceIds: service?.staffMemberIds ?? [],
+            numberOfResourcesRequired: 1,
+          },
+        ],
+        locations: (service?.locations ?? []).map((location) => ({
+          _id: location._id,
+          locationType: availabilityTimeSlotsConfiguration.LocationType.BUSINESS,
+        })),
+        splitIntervalInMinutes: baseDuration + addOnMinutes,
+        duration: { defaultInMinutes: baseDuration + addOnMinutes },
+        bufferTimeInMinutes: 10,
+        scheduleId: service?.schedule?._id,
+      };
+    });
+
+    return { configurations };
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **One configuration per requested entry, same order** — the response array must line up positionally with the request's `services`, even when the same service GUID repeats with different `customerChoices`.
+2. **Prefer `addOnIds` over `durationInMinutes`** in the request — when both are present they must agree, so let Wix Bookings compute total duration from add-ons rather than passing a duration you'd have to keep in sync.
+3. **`splitIntervalInMinutes` vs `duration`** — when the split interval matches the service duration, `splitIntervalInMinutes` is `duration.defaultInMinutes + bufferTimeInMinutes`.
+4. **Duration ranges** — use `durationUnit` for services where the customer picks the length of the booking; leave `duration` empty for `DAY`-unit ranges.
+5. **Called on the hot path** — this handler runs on every availability query, so keep it fast.
+6. **`services` is optional on the request type** — default it to `[]` when destructuring, or the `.map()` calls fail `tsc` with "possibly undefined."