@wix/agent-skills 1.16.2 → 1.16.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.16.2",
+  "version": "1.16.3",
   "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

@@ -67,10 +67,12 @@ File where you can override the generated manifest from `<componentName>.generat
 3. Edit the generated React and CSS files in
    `src/extensions/site/components/component-name/`. Apply
    [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) while
-   authoring: every interactive named part must use interactive markup and
-   pair each native state selector with its prefixed global modifier (for
-   example, `.cta:global(.component-name-cta--hover), .cta:hover`). A
-   pseudo-class without the matching global modifier is incomplete.
+   authoring: every interactive named part must use interactive markup, and
+   every native design state supported by the eligibility table must pair its
+   selector with the prefixed global modifier (for example,
+   `.cta:global(.component-name-cta--hover), .cta:hover`). A standalone
+   `:focus-visible` keyboard indicator on a non-input control is not an editor
+   design state and intentionally has no global modifier.
 4. **MANDATORY** — execute the full A11y Review on the edited component per [`editor-react-component/A11Y-REVIEW.md`](editor-react-component/A11Y-REVIEW.md). Run both scanners over the component's `.tsx`/`.jsx` files, complete the Phase 3 manual semantic review, fix confirmed findings, and re-run the scanners after fixes. Reading the reference without executing these steps is not a review. Do not proceed to the build or report completion until the review is complete.
 5. Run `npx wix build && npx wix generate manifest` so the editor picks up
    the new/updated prop schema. This command regenerates manifest
@@ -79,7 +81,7 @@ File where you can override the generated manifest from `<componentName>.generat
    ≥ 1.1.210, but prop-triggered `ElementState` states need ≥ 1.1.215). If a
    design state is missing from `<componentName>.generated.ts`, the installed
    CLI is older than required — tell the user, and let them decide whether to
-   upgrade.
+   upgrade. If the command exits with an error, diagnose using [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 6. Update `Component.extensions.ts` file according to [`editor-react-component/COMPONENT-CONFIGURATION.md`](editor-react-component/COMPONENT-CONFIGURATION.md)
 
 If the component's primary content is a **playable animation** (Lottie/JSON,
@@ -102,6 +104,11 @@ before writing the code. Triggers, and the only cases that warrant it:
 
 Otherwise, do not reach for a hook at all — data the site owner can type or pick
 belongs in props.
+If the component displays **an array of items where only one body is visible at a
+time** (tabs, slides, steps), follow the
+[active-item rules](editor-react-component/COMPONENT-API.md#active-item-components-one-body-visible-at-a-time)
+in [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) (`ActiveItemIndex<>`,
+`name` on each item, render-all-panels visibility).
 
 Reference: when modifying an _existing_ component, follow
 [`editor-react-component/EDIT-FLOW.md`](editor-react-component/EDIT-FLOW.md).
@@ -117,7 +124,7 @@ Topic-focused references (rules + patterns + common mistakes in one place):
 - [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) — Which design states a part supports (heuristic) and how to author them
 - [`editor-react-component/DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`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/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props, active-item components
 - [`editor-react-component/FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) — Standard SDK event handler props, DOM wiring, custom callbacks
 - [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
 - [`editor-react-component/COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) — Editor-specific entry point (`component.preview.tsx`), `useIsEditMode()`, when to modify

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

@@ -230,6 +230,12 @@ await embeddedScripts.embedScript({
 });
 ```
 
+## Releasing Updates
+
+`embedScript()` is not only a one-time setup step. A site only ever renders whatever content was active the last time `embedScript()` was called for it — releasing a new app version (even a minor one, e.g. via `wix release`, that only changes the script's HTML/JS with no dynamic-parameter changes) does **not** re-embed the script on sites that already called it. Always prompt the site owner to re-run the dashboard-page action (or call `embedScript()` yourself) after any release that changes an embedded script's content, or production sites will silently keep serving the old version.
+
+Adding, removing, or renaming a dynamic parameter is additionally a **major** version change — those sites only pick up the new version after the user clicks Update on the Manage Apps page (or you drive them through the app-installer update flow). See [About App Versioning](https://dev.wix.com/docs/build-apps/manage-your-app/versioning/about-app-versioning).
+
 ## Enable Embedded Script Permission
 
 After implementation, the app developer must manually enable the embedded script permission:

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; **must be a named part** (`classNames('component-name-play-button', styles.playButton)`) with hover/focus design-state selectors
+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 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
 
@@ -126,7 +126,8 @@ Position the button absolutely so it overlays the content without pushing other
   /* e.g. background: rgba(255, 255, 255, 1); */
 }
 
-.playButton:global(.my-animation-play-button--focus),
+/* Keyboard indicator only — deliberately unpaired: focus is not an editor
+   design state on a non-input control. Do not add a --focus modifier here. */
 .playButton:focus-visible {
   outline: 2px solid currentColor;
   outline-offset: 2px;

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

@@ -130,6 +130,38 @@ when arithmetic is needed: `price: number`, not `price: string`).
 
 When the parent component defines an array prop (e.g., `items`), child/item components receive a single item directly. They do NOT redeclare the data structure in their own props.
 
+### Active-item components (one body visible at a time)
+
+Apply when the UI shows **one array item body at a time** (tabs, slideshow,
+steps). Skip for always-visible lists, multi-select, or multi-expand accordion.
+
+- Each item needs **`name: string`** — Studio hat labels (not `label` or other keys).
+- Pair the array with **`ActiveItemIndex<'arrayPropName'>`** from
+  `@wix/react-component-utils`; the type param must match the array prop name.
+  Default the index to `0` in `defaultProps`.
+- Render **all** item bodies (`.map`); toggle visibility with `--active` +
+  `display: none` on inactive panels (functional visibility — see
+  [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md)), plus `aria-hidden` and `inert` on
+  inactive bodies.
+- Keyboard navigation between triggers; ARIA roles per
+  [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
+
+```typescript
+import type { ActiveItemIndex } from '@wix/react-component-utils';
+
+export type ItemType = { name: string; body: string };
+
+export type MyComponentProps = {
+  items: Array<ItemType>;
+  activeItem: ActiveItemIndex<'items'>;
+};
+
+export const defaultProps = {
+  items: [{ name: 'Item 1', body: '…' }],
+  activeItem: 0,
+} satisfies Omit<MyComponentProps, 'id' | 'className'>;
+```
+
 ### Array Element Types: Always Objects with Named Keys
 
 Array elements MUST be objects with named keys. This enables stable item identity (each item can carry its own `id`/`key`), non-breaking extension (new fields can be added later without changing the prop signature), and semantic naming (each value has meaning instead of being an opaque scalar).

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

@@ -9,14 +9,31 @@ and `.module.css`.
 
 | Element | Author these states |
 |---|---|
-| Interactive — `button`/`a`/`input`/`select`/`textarea`/`summary`, an interactive `role` (`button`/`link`/`tab`/`switch`/`checkbox`/`radio`/`menuitem`/`option`), or an interactive handler (`onClick`/`onMouseEnter`/`onFocus`/…) | `hover`, `focus` |
+| Interactive — `button`/`a`/`input`/`select`/`textarea`/`summary`, an interactive `role`, or an interactive handler (`onClick`/`onMouseEnter`/`onFocus`/…) | `hover` |
+| Input field — `select`/`textarea`; `input` except `hidden`/`button`/`submit`/`reset`/`image`; or an input-widget `role` (`checkbox`/`radio`/`switch`/`slider`/`spinbutton`/`textbox`/`searchbox`/`combobox`/`listbox`) | `focus` |
+| Other interactive element whose editable focus appearance the user explicitly requests | `focus` |
 | Disableable — `button`/`input`/`select`/`textarea`/`fieldset` or a disableable role | `disabled` (+ `invalid` for `input`/`select`/`textarea`) |
 | Has a selectable/variant value in its data — `selected`/`active`/`current`/`open`/`expanded`/`checked`/`featured` | that custom state |
 | None of the above | no states — resting style only |
 
+An explicit `role` overrides the tag's implicit semantics: `<input role="button">`
+is a non-input control, and `<div role="checkbox">` is an input field.
+
+A `focus` design state is an editor styling control, not the keyboard focus
+indicator itself. Do not add a global `--focus` modifier to a non-input control
+unless the user explicitly asks for an editable focus state. A control that
+restyles its own `outline`, `background`, or `border` MUST still carry a
+standalone `:focus-visible` rule — that rule is its only keyboard affordance.
+
 A custom state may also be driven by a root-level boolean prop (e.g.
 `isFeatured`) instead of by markup or item data — see §5.
 
+For **active-item components** (tabs, slideshow, steps), the `--active` state on
+each item is driven by comparing the item's index to the active-index prop
+(`index === activeItem`), not by a per-item boolean flag — see
+[Active-item components](COMPONENT-API.md#active-item-components-one-body-visible-at-a-time)
+in [`COMPONENT-API.md`](COMPONENT-API.md).
+
 ## 2. Name the state class
 
 Flat: the element's own global class + `--<state>`. Because inner-part
@@ -31,9 +48,12 @@ nested (`card__row--selected`).
 Put the resting value in the bare class; put only the state override in the
 state selector.
 
-- **Native** — pair the pseudo-class with the `:global` modifier. Every native
-  state needs both selectors in the same rule; do not split the pair across
-  states (for example, pseudo-only `hover` plus global-only `disabled`).
+- **Native design state** — pair the pseudo-class with the `:global` modifier.
+  Every exposed native state needs both selectors in the same rule; do not
+  split the pair across states (for example, pseudo-only `hover` plus
+  global-only `disabled`). A standalone `:focus-visible` accessibility rule on
+  a non-input control is intentionally not an editor design state and therefore
+  has no `:global` modifier.
 - **Custom** — the `:global` modifier alone.
 
 The bare selector is the short **module** class (`.cta`); the `:global(...)`
@@ -51,6 +71,9 @@ state class is the **prefixed** global one.
 .cta:disabled {
   opacity: 0.5;
 }
+.cta:focus-visible {
+  outline: 2px solid currentColor;
+} /* keyboard indicator only; not an editor design state */
 .plan-row:global(.pricing-card-plan-row--selected) {
   border-color: #6366f1;
 }

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

@@ -0,0 +1,19 @@
+# Manifest Build Errors
+
+The error name is always the first token before the colon (`IoError:`, `ParseError:`, `NotFoundError:`). Find the matching row, apply the fix, then re-run both commands.
+
+| Error | Fix |
+|---|---|
+| `IoError: Failed to load compiled bundle` | Re-run `npx wix build`; fix any TypeScript/build errors it reports first |
+| `IoError: Failed to access component "X" from compiled bundle` | Corrupted artifact — delete `dist/`, re-run `npx wix build` from scratch |
+| `IoError: CSS selector matching failed for "X"` | Fix invalid selector syntax in `<componentName>.module.css` |
+| `IoError: Component "X" render produced no root element` | Component returns null or bare text — ensure it always renders a root JSX element |
+| `IoError` (render phase, no other pattern) | SSR crash — remove browser-only APIs (`window`, `document`, `localStorage`) used at render time; ensure props have defaults |
+| `NotFoundError: File not found` | Source `.tsx` missing — restore it or re-scaffold with `npx wix generate` |
+| `NotFoundError: Component "X" was not found as a named export` | Confirm `component.tsx` has a default export and re-run `npx wix build` |
+| `ParseError: Failed to parse TypeScript config` | Fix `tsconfig.json`; run `npx tsc --noEmit` to surface the error |
+| `ParseError: Failed to extract component types from "X"` | TypeScript error in the component — run `npx tsc --noEmit` and fix |
+| `ParseError: Failed to compile "<file.scss>"` | SCSS syntax error — line/column is in the error message |
+| `ParseError: Failed to parse CSS file for component "X"` | CSS syntax error in `.module.css` — line/column is in the error message |
+
+After each fix, re-run `npx wix build && npx wix generate manifest` to confirm.

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

@@ -23,7 +23,7 @@ An element deserves its own named part if a site owner would plausibly need to i
 - ❌ **State or variant** (`active`, `selected`, `current`, `disabled`, `open`, `checked`) — not a part, it's a **design state** of a part. Implement it per [`DESIGN-STATES.md`](DESIGN-STATES.md): native states from interactive markup; custom states as a flat global modifier on the element's own (component-name-prefixed) class (e.g. `carousel-slide--active`, toggled in JSX) plus a `:global(.carousel-slide--active)` CSS rule. The modifier is a state, not a named part.
 - ❌ **Hidden/shown state of an existing part** — the hidden and shown states of a part are not separate parts. The element itself should be a named part (so the editor can control its visibility per breakpoint); creating an additional part to represent its hidden or shown variant is wrong.
 - ❌ **Pure grouping wrapper** — not a part. A `<div>` whose only role is to hold already-named siblings has no independent editor surface; let layout live in the parent's CSS.
-- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs. **Exception — interactive HTML elements (`<button>`, `<a>`, `<input>`) are never excluded by this criterion.** They always carry an independent styling surface: background, border, border-radius, hover/focus states, color, and typography are all meaningfully tunable per element in the editor. Apply this exclusion only to purely static structural elements (layout wrappers, grouping containers, decorative dividers). This makes an interactive element a named part **when it is an inner element** — if it is the elected root (Step 0), it is already named by `'<component-name>'` and must not be given a prefixed inner-part class as well.
+- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs. **Exception — interactive HTML elements (`<button>`, `<a>`, `<input>`) are never excluded by this criterion.** They always carry an independent styling surface: background, border, border-radius, interaction states, color, and typography are all meaningfully tunable per element in the editor. Apply this exclusion only to purely static structural elements (layout wrappers, grouping containers, decorative dividers). This makes an interactive element a named part **when it is an inner element** — if it is the elected root (Step 0), it is already named by `'<component-name>'` and must not be given a prefixed inner-part class as well.
 - ❌ **Positional duplicate** — not separate parts. Elements that are semantically identical and differ only in position (e.g. prev/next buttons) are one part; differentiate position with CSS (`:first-of-type` / `:last-of-type`, `data-` attribute, or `:nth-child`).
 - ✅ **Passes all checks** — a named part. Classify as **Semantic** (needs `elementProps`: data, behavior, direction, event handlers) or **Styling-only** (CSS class is sufficient).
 
@@ -36,4 +36,3 @@ Before finalising, verify each proposed part against its parent:
 If yes — the part adds no independent editor surface and should be removed. This catches rationalisation after-the-fact ("the parent *could* expose this CSS property too, but so could the child separately"). When in doubt, fewer parts is usually better.
 
 Then run the same question in reverse, on the root: if the root has exactly one child part and no editor surface of its own, it is a plumbing wrapper — delete it and promote the child per Step 0.
-

package/skills/wix-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-manage
-description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, analytics, accessibility, dashboard-navigation."
+description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, ricos rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, analytics, accessibility, dashboard-navigation."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
@@ -341,11 +341,13 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ## Rich Content
 
+> **Routing rule (READ FIRST).** For every request to hand-author, output, or return Ricos / `richContent` JSON (`nodes` tree) for Blog, Stores, Events, or CMS, use the available full-documentation reading capability to retrieve and read the canonical [Author Ricos Rich Content](references/rich-content/author-ricos-rich-content.md) recipe before using API schema search, convert/validate APIs, or memory. This also applies when the user asks for JSON only.
+
 ### [Ricos Converter Service](references/rich-content/ricos-converter-service.md)
 **Technical:** Validates and converts content between Ricos documents and HTML/Markdown/plain text using the Ricos Documents API. Covers plugin configuration, format conversion in both directions, and document validation.
 
 ### [Author Ricos Rich Content](references/rich-content/author-ricos-rich-content.md)
-**Technical:** Hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) reused across Blog, Stores, Events, and CMS. Covers every common node shape — paragraphs, headings, lists, blockquotes, dividers, tables with cell fills, code blocks, images — plus inline text decorations and the nesting rules the format enforces.
+**Technical:** Required first source for every request to hand-author, output, or return Ricos / `richContent` JSON (`nodes` tree) for Blog, Stores, Events, or CMS. Retrieve and read this full article before API schema search or constructing the JSON. Covers node shapes — paragraphs, headings, lists, blockquotes, dividers, tables with cell fills, code blocks, images, buttons, audio, video, galleries, collapsible lists, HTML embeds — plus inline text decorations (including spoiler) and nesting rules.
 
 ---
 

package/skills/wix-manage/references/bookings/create-class-service.md

@@ -149,7 +149,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `defaultCapacity` is **required** — sets max participants per session
 - After creation, class sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
 
-Save the `serviceId` from the response: `results[0].item.service.id`
+**Response:** Save the service ID from `results[0].itemMetadata.id`
 
 ---
 

package/skills/wix-manage/references/rich-content/author-ricos-rich-content.md

@@ -1,10 +1,12 @@
 ---
 name: "Author Ricos Rich Content"
-description: Hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) used across Wix Blog posts, Stores product descriptions, Events, and CMS rich-text fields. Covers every common node shape — paragraphs, headings, lists, blockquotes, dividers, tables (with cell fills), code blocks, images — plus inline text decorations and the nesting rules the format enforces.
+description: Authoritative recipe for hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) used across Wix Blog posts, Stores product descriptions, Events, and CMS rich-text fields. Use whenever a user asks to create, output, or return Ricos, richContent, or nodes-tree JSON; retrieve and read this full recipe before API schema search or constructing the JSON. Covers paragraphs, headings, lists, blockquotes, dividers, tables, code blocks, images, buttons, audio, video, galleries, collapsible lists, HTML embeds, inline decorations, and nesting rules.
 ---
 
 # Author Ricos Rich Content
 
+> **Routing rule (READ FIRST).** When hand-authoring or returning Ricos / `richContent` JSON, use **this recipe** — the shapes, nesting rules, spacer paragraphs, and plugin nodes below. Do not rely on API schema search alone; it misses those details. After this recipe loads, do not perform additional schema or documentation searches for node types covered here; compose and self-audit the JSON from this file. When the user only wants JSON output, **do not** call Ricos convert/validate APIs.
+
 Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON. The same structure is embedded by many products: a Blog post's `draftPost.richContent`, a Store product's rich description, an Events description, and CMS rich-text fields all expect a Ricos document. This recipe is the **authoring reference for that node tree**: the valid shape of each node, how nodes nest, and how to format text. It is intentionally product-agnostic — the consuming API decides *where* the document goes; this recipe governs *what a valid document looks like*.
 
 > A Ricos document is an object with a `nodes` array: `{ "nodes": [ /* block nodes */ ] }`. Whatever field the consuming API exposes (e.g. `richContent`), it holds this object. For validating or converting an existing document to/from HTML/Markdown, see [Ricos Converter Service](ricos-converter-service.md).
@@ -15,10 +17,58 @@ Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON.
 - Every node carries a `type`, an optional `id`, and (for container nodes) a `nodes` array of children. Node `id`s are optional when authoring for a create request — the API generates them; the examples below omit `id` for brevity.
 - **TEXT is a leaf.** A TEXT node only ever lives inside a `PARAGRAPH`, `HEADING`, or `CODE_BLOCK`. It must **never** sit directly in the root `nodes` array or inside a `LIST_ITEM`, `BLOCKQUOTE`, or `TABLE_CELL` — those must contain a `PARAGRAPH` (or `HEADING`) that then contains the TEXT. See [Nesting rules](#nesting-rules).
 - Failing to wrap TEXT correctly produces the parse error **"Expected a paragraph node but found TEXT"**.
+- **Block nodes do not get automatic vertical gap when rendered** — insert empty `PARAGRAPH` spacer nodes between sibling blocks when you need breathing room. See [Vertical spacing between blocks](#vertical-spacing-between-blocks).
+
+## Required plugin shape checklist
+
+Use this checklist while composing and again before returning JSON. Treat every path below as required for the described request:
+
+- **Button CTA:** emit a root-level `BUTTON`, never a `PARAGRAPH` with an inline `LINK`. Include `buttonData.type: "LINK"`, `buttonData.text`, `buttonData.link.url`, `buttonData.link.target`, and `buttonData.containerData`.
+- **Hosted audio:** emit `{ "type": "AUDIO", "nodes": [], "audioData": { ... } }`. The empty `nodes` array is on the AUDIO node beside `audioData` — never inside `audioData`. Include `audioData.containerData.alignment`, `width`, and `textWrap`, plus `audioData.audio.src.id`.
+- **Video with thumbnail:** place `videoData.video.src` and `videoData.video.duration` inside `video`; place `videoData.thumbnail` beside `video`, with `src.id`, `width`, and `height`.
+- **Gallery:** emit one root-level `GALLERY`. Put images in `galleryData.items`, not as child IMAGE nodes. Every item uses `image.media` with `src`, `width`, and `height`; include `galleryData.options.layout.type` and `numberOfColumns`.
+- **Collapsible FAQ:** use `COLLAPSIBLE_LIST → COLLAPSIBLE_ITEM → COLLAPSIBLE_ITEM_TITLE | COLLAPSIBLE_ITEM_BODY → PARAGRAPH → TEXT`. Every PARAGRAPH includes `paragraphData`, and every item includes both title and body.
+- **HTML embed:** emit a root-level `HTML` with `htmlData.source`, either `url` or `html`, and `htmlData.containerData.width`, `height`, and `alignment`.
+
+## Vertical spacing between blocks
+
+The renderer does **not** add margin between stacked block nodes. Adjacent paragraphs, headings, images, videos, tables, collapsible lists, buttons, galleries, and other blocks will sit flush against each other unless you separate them explicitly.
+
+**Use an empty `PARAGRAPH` as a spacer** — a paragraph with no `nodes` (no TEXT children):
+
+```json
+{ "type": "PARAGRAPH" }
+```
+
+Place spacer paragraphs at the root `nodes` level (or inside a `CARD` page) wherever layout needs vertical rhythm:
+
+- **After headings** — before the following body copy or media block.
+- **Between paragraphs** — when two text blocks should not run together visually.
+- **After block plugins** — images, videos, audio, galleries, tables, collapsible lists, HTML embeds, buttons, dividers, and lists often need a spacer before the **next distinct section** (not between every adjacent block in a minimal snippet the user enumerated).
+- **After blockquotes** — only when the following block is a separate section; skip the spacer when the user asked for a blockquote immediately followed by a specific paragraph in one compact output.
+- **Before major sections** — optional extra spacer when transitioning from one content group to another.
+
+When the user requests **only** specific nodes in one JSON output (e.g. "a blockquote and then a paragraph"), include exactly those nodes — do not add spacer paragraphs they did not ask for.
+
+Do **not** rely on `\n` inside `textData.text` for spacing — that does not create a real line break between blocks. Do **not** expect `paragraphData` margins or `containerData` alone to separate unrelated sibling nodes; the empty paragraph is the supported spacing mechanism.
+
+**Example — spacer after an image and before a table:**
+
+```json
+{
+  "nodes": [
+    { "type": "IMAGE", "imageData": { /* … */ } },
+    { "type": "PARAGRAPH" },
+    { "type": "TABLE", "nodes": [ /* … */ ], "tableData": { /* … */ } },
+    { "type": "PARAGRAPH" },
+    { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Next section.", "decorations": [] } } ], "paragraphData": {} }
+  ]
+}
+```
 
 ## Block node shapes
 
-**PARAGRAPH** — the base text container. An empty paragraph — `{ "type": "PARAGRAPH" }` — acts as a vertical spacer. `paragraphData.textStyle.textAlignment` accepts `AUTO`·`LEFT`·`CENTER`·`RIGHT`·`JUSTIFY`:
+**PARAGRAPH** — the base text container. An empty paragraph — `{ "type": "PARAGRAPH" }` — is the **vertical spacer** between block nodes (the renderer adds no gap on its own). See [Vertical spacing between blocks](#vertical-spacing-between-blocks). `paragraphData.textStyle.textAlignment` accepts `AUTO`·`LEFT`·`CENTER`·`RIGHT`·`JUSTIFY`:
 
 ```json
 {
@@ -142,6 +192,122 @@ Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON.
 }
 ```
 
+**BUTTON** — a standalone call-to-action block. **Not the same as an inline `LINK` decoration** on TEXT (that is hyperlinked body copy; this is a labeled button control). **`buttonData.type` is required** on every BUTTON node — use `"LINK"` for URL navigation or `"ACTION"` for viewer click handlers (never omit `type` even when `link` is present). Two `buttonData.type` values:
+
+- **`LINK`** — navigates to a URL when clicked (`link.url`, `link.target`: `BLANK`·`SELF`, optional `link.rel`).
+- **`ACTION`** — triggers a viewer `onClick` handler (store the node in JSON; behavior is configured in the Ricos viewer, not in the document body).
+
+```json
+{
+  "type": "BUTTON",
+  "buttonData": {
+    "type": "LINK",
+    "text": "Get Started",
+    "link": { "url": "https://example.com", "target": "BLANK", "rel": { "nofollow": true } },
+    "containerData": { "alignment": "CENTER", "width": { "size": "ORIGINAL" }, "textWrap": true },
+    "styles": { "borderRadius": 4, "borderWidth": 0, "backgroundColor": "#116DFF", "textColor": "#FFFFFF" }
+  }
+}
+```
+
+**AUDIO** — uploaded audio via Wix Media `src.id`, or an embed variant whose `audioData.html` holds an iframe (SoundCloud, Spotify). Include `audioData.containerData` with `alignment` and width settings, and use an empty `nodes: []` array because AUDIO has no child nodes. Optional fields include `coverImage` (`src.id`, `width`, `height`), `name`, `authorName`, and `disableDownload`:
+
+```json
+{
+  "type": "AUDIO",
+  "nodes": [],
+  "audioData": {
+    "containerData": { "alignment": "CENTER", "width": { "size": "CONTENT" }, "textWrap": true },
+    "audio": { "src": { "id": "mp3/f0f74f_48772df0375c41cd88e8e29370ccf899" } },
+    "disableDownload": true,
+    "coverImage": { "src": { "id": "f0f74f_2973832f552e4002b58ec6abbe7fce71~mv2.png" }, "width": 436, "height": 524 },
+    "name": "Track title",
+    "authorName": "Artist name"
+  }
+}
+```
+
+**VIDEO** — Wix Media `video.src.id`, `duration` (seconds), and a `thumbnail` (`src.id`, `width`, `height`). YouTube and other embeds use the same `VIDEO` node shape with the appropriate media id:
+
+```json
+{
+  "type": "VIDEO",
+  "videoData": {
+    "containerData": { "width": { "size": "CONTENT" }, "alignment": "CENTER" },
+    "video": { "src": { "id": "video/11062b_a552731f40854d16a91627687fb8d1a6/1080p/mp4/file.mp4" }, "duration": 14.08 },
+    "thumbnail": { "src": { "id": "media/11062b_a552731f40854d16a91627687fb8d1a6f000.jpg" }, "width": 1920, "height": 1080 }
+  }
+}
+```
+
+**GALLERY** — multiple images in one block. Each `items[]` entry wraps `image.media` with `src` (`id` or `url`), `width`, and `height`. `galleryData.options` controls layout (`layout.type`: `GRID`, `numberOfColumns`, `orientation`; `item.ratio`, `item.crop`; `thumbnails.placement`):
+
+```json
+{
+  "type": "GALLERY",
+  "galleryData": {
+    "containerData": { "width": { "size": "CONTENT" }, "alignment": "CENTER", "textWrap": true },
+    "items": [
+      { "image": { "media": { "src": { "id": "8bb438_36726a2d14ec44ee9edc5693bade1092.jpg" }, "width": 3648, "height": 5472 } } },
+      { "image": { "media": { "src": { "id": "8bb438_6bbf8e82fe8f4b79b6e03ee79b66fd6a.jpg" }, "width": 1920, "height": 1280 } } }
+    ],
+    "options": {
+      "layout": { "type": "GRID", "horizontalScroll": false, "orientation": "COLUMNS", "numberOfColumns": 3 },
+      "item": { "ratio": 1, "crop": "FILL" },
+      "thumbnails": { "placement": "NONE" }
+    }
+  }
+}
+```
+
+**COLLAPSIBLE_LIST** — FAQ-style expandable items. Nesting is `COLLAPSIBLE_LIST → COLLAPSIBLE_ITEM → COLLAPSIBLE_ITEM_TITLE | COLLAPSIBLE_ITEM_BODY → PARAGRAPH → TEXT` (body cells may also contain other supported block plugins such as IMAGE or VIDEO). The item wrapper type is **`COLLAPSIBLE_ITEM`** — not `COLLAPSIBLE_LIST_ITEM` or other variants:
+
+```json
+{
+  "type": "COLLAPSIBLE_LIST",
+  "nodes": [
+    {
+      "type": "COLLAPSIBLE_ITEM",
+      "nodes": [
+        {
+          "type": "COLLAPSIBLE_ITEM_TITLE",
+          "nodes": [
+            { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Question?", "decorations": [] } } ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } }
+          ]
+        },
+        {
+          "type": "COLLAPSIBLE_ITEM_BODY",
+          "nodes": [
+            { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Answer text.", "decorations": [] } } ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } }
+          ]
+        }
+      ]
+    }
+  ],
+  "collapsibleListData": {
+    "containerData": { "alignment": "CENTER", "textWrap": true },
+    "expandOnlyOne": false,
+    "initialExpandedItems": "FIRST",
+    "direction": "LTR"
+  }
+}
+```
+
+`initialExpandedItems`: `NONE`·`FIRST`·`ALL`. Set `isQapageData: true` in list metadata when the list should render as FAQ structured data in search results.
+
+**HTML** — embeds external content in an iframe. Provide either `url` (page URL) or inline `html` markup; `source` is typically `"HTML"`. Size via `containerData.width` / `height` (`custom` pixel strings or `size`):
+
+```json
+{
+  "type": "HTML",
+  "htmlData": {
+    "containerData": { "width": { "custom": "550" }, "height": { "custom": "550" }, "alignment": "CENTER" },
+    "url": "https://example.com/embed",
+    "source": "HTML"
+  }
+}
+```
+
 ## Inline text formatting (decorations)
 
 Apply formatting with the `decorations` array on a TEXT node. Each decoration is an object with a `type` and (for some types) a data field:
@@ -169,6 +335,7 @@ Apply formatting with the `decorations` array on a TEXT node. Each decoration is
 | `COLOR`                                    | `colorData: { foreground: "#hex" }` (add `background` for highlight) |
 | `LINK`                                     | `linkData: { link: { url, target: "BLANK" } }`             |
 | `FONT_SIZE`                                | `fontSizeData: { unit: "PX", value: 24 }`                  |
+| `SPOILER`                                  | _(none — `{ "type": "SPOILER" }` hides text behind a reveal control)_ |
 
 - **Mixed formatting in one paragraph → split into multiple TEXT nodes** (one per style run) inside the same PARAGRAPH. A single TEXT node carries one consistent set of decorations.
 - Use a plain hex string in `foreground` for colors.
@@ -229,12 +396,16 @@ Note the mixed-run paragraph at the end: the linked words are their own TEXT nod
 
 | Parent | Valid children |
 | ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| Root `nodes`                         | PARAGRAPH, HEADING, BULLETED_LIST, ORDERED_LIST, BLOCKQUOTE, DIVIDER, IMAGE, TABLE, CODE_BLOCK         |
+| Root `nodes`                         | PARAGRAPH, HEADING, BULLETED_LIST, ORDERED_LIST, BLOCKQUOTE, DIVIDER, IMAGE, TABLE, CODE_BLOCK, BUTTON, AUDIO, VIDEO, GALLERY, COLLAPSIBLE_LIST, HTML |
 | PARAGRAPH / HEADING / CODE_BLOCK     | TEXT                                                                                                  |
 | BULLETED_LIST / ORDERED_LIST         | LIST_ITEM                                                                                             |
 | LIST_ITEM / BLOCKQUOTE               | PARAGRAPH (which then contains TEXT)                                                                  |
 | TABLE → TABLE_ROW → TABLE_CELL       | cell contains PARAGRAPH / HEADING / IMAGE                                                              |
-| IMAGE                                | CAPTION (optional)                                                                                    |
+| IMAGE / VIDEO                        | CAPTION (optional)                                                                                    |
+| COLLAPSIBLE_LIST                     | COLLAPSIBLE_ITEM                                                                                      |
+| COLLAPSIBLE_ITEM                     | COLLAPSIBLE_ITEM_TITLE, COLLAPSIBLE_ITEM_BODY                                                        |
+| COLLAPSIBLE_ITEM_TITLE / _BODY       | PARAGRAPH (and other plugins supported inside collapsible cells — see COLLAPSIBLE_LIST above)           |
+| BUTTON / AUDIO / GALLERY / HTML      | _(leaf — `nodes: []` or omit)_                                                                        |
 
 ## Self-audit before returning the document
 
@@ -246,4 +417,10 @@ All decidable from the JSON itself — check before handing the document to a co
 4. **Headings carry a `level`** (1–6) and nest logically (don't jump H2 → H4).
 5. **No `\n` inside `textData.text`** — split into sibling nodes; mixed inline formatting → split into multiple TEXT runs.
 6. **Images** use a Wix Media `id` (not a raw URL), with `width`, `height`, and meaningful `altText`.
-7. **Links** — every `LINK` decoration has a valid `url` and `target`.
+7. **Links** — every `LINK` decoration has a valid `url` and `target`. Use a `BUTTON` block with `buttonData.type: "LINK"` for CTAs — not an inline `LINK` decoration styled to look like a button.
+8. **Buttons** — every BUTTON includes **`buttonData.type`** (`LINK` requires `link.url`; `ACTION` has no URL). Omitting `type` is invalid even when `link` is set. `LINK` buttons and inline `LINK` decorations serve different purposes.
+9. **Media blocks** — AUDIO has root-level `nodes: []` and `audioData.containerData`; VIDEO keeps `thumbnail` beside `video` under `videoData`; every GALLERY item is under `galleryData.items` and carries `image.media.src`, `width`, and `height`.
+10. **Collapsible lists** — every item has both `_TITLE` and `_BODY`, each wrapping content through `PARAGRAPH → TEXT`, and every PARAGRAPH has `paragraphData`.
+11. **HTML embeds** — `htmlData` includes `source`, `containerData.width`, `containerData.height`, and either `url` or `html` (not both empty).
+12. **Spoiler** — `SPOILER` is a decoration on `TEXT` (or `containerData.spoiler` on some block plugins in editor output); preserve it verbatim on edit.
+13. **Vertical spacing** — stacked block nodes that should not appear cramped are separated by empty `{ "type": "PARAGRAPH" }` spacers — especially after images, videos, tables, collapsible lists, galleries, buttons, and between consecutive paragraphs. Missing spacers produce a wall-of-blocks layout with no renderer-added margin.