@wix/agent-skills 1.19.1 → 1.19.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.19.1",
+  "version": "1.19.2",
   "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/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,36 +99,44 @@ 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
 
@@ -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>
 ```
 

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-base44-connector/SKILL.md

@@ -23,8 +23,8 @@ they also surface from a search that began at the methods.
 
 In this skill:
 
-- **What are you building?** — route each feature to its identity: visitor token, admin token
-  in a backend function, or admin ad hoc in exec_tool
+- **What are you building?** — for visitors, for the owner, or management done for them —
+  decided per request from the user's intent, each on its own flow
 - **The helpers** — the `wx.*` loader every exec opens with
 - **Gather context** — `wx.context`, the report of what the site actually has
 - **Learn Wix** — find the APIs, learn their contracts
@@ -40,28 +40,41 @@ In this skill:
 
 ## What are you building?
 
-Choose the token by who the code acts for. A headless app can serve visitors, provide admin
-management tools, or do both.
-
-**A site for visitors** — use a visitor token for public reads and actions on behalf of the
-visitor, never the admin connector token. Call Wix directly from the browser through one shared
-visitor client (Write the code, below). Redirect sessions for Wix-hosted flows also require a
-visitor token minted for the headless OAuth app; see Visitor authentication and Wix-hosted flows below.
-**The OAuth app is a one-call prerequisite, not a dead end**: `wx.ensureOAuthApp` returns its
-`clientId`, creating the app when the site has none, so it is a visitor flow's first step — never
-a reason to move the flow onto the admin token or leave it for later.
-Anyone can mint an anonymous visitor token from the
-OAuth app's public `clientId`; no visitor login is required. APIs for the "current visitor"
-use that token to identify whose data and state to access. This applies both to a standalone
-headless frontend and to a frontend extending an existing Wix site.
-
-**An admin tool for the owner** — use the admin connector token in backend functions implementing
-admin logic; keep it secret and server-side. The frontend calls those functions, not Wix with
-visitor tokens. A custom headless management site extending the Wix back office follows this
-flow too. Ad hoc management calls in `exec_tool` also use the admin token. Backend functions
-also handle work requiring the owner's permissions, such as webhooks, scheduled jobs, and
-explicitly authorized elevated operations. For an app with both visitor and admin features,
-keep each feature on its corresponding flow.
+Wix has two identities, visitor and admin, and each has its own flow. Decide which one every
+request is for before acting on it — from what the user wants, not from the technology:
+
+- **Visitor** — the people using the site: browsing, booking, buying, signing in as a member.
+  Visitor token, called from the browser through one shared visitor client.
+- **Admin, built** — a management surface of the owner's own: a custom view, a bulk operation,
+  an internal tool. Admin connector token, server-side in backend functions the frontend calls.
+- **Admin, done for them** — the user wants the business managed now, not an app: create the
+  products, change a setting, import the contacts. Admin token, ad hoc in exec_tool; nothing
+  ships in the app.
+
+The owner already has a full Wix dashboard for running the business — orders, products,
+bookings, settings, and more — so an admin build is a choice the user makes, not a gap to fill by
+default. When a request has both visitor and admin parts, each keeps its own flow.
+
+When the request doesn't say which, ask the user — in their terms (who the thing is for), not in
+technical ones (identities, tokens, flows). When you decide without asking, tell them what you
+chose the same way.
+
+The rules that follow from the split:
+
+- **Checkout runs on a visitor token, never the admin token** — including a checkout this app
+  creates for the visitor. The admin token *will* hand back a checkout URL, and that is the trap:
+  it belongs to the site rather than the buyer (no cart persistence, no abandoned-checkout
+  recovery, no attribution), and a redirect session refuses it outright (`403`). Returns reach
+  this app only from URLs in the OAuth app's redirect list (Visitor authentication and
+  Wix-hosted flows, below).
+- **No OAuth app yet is not a reason to use the admin token.** `wx.ensureOAuthApp` returns the
+  `clientId`, creating the app when the site has none — a visitor flow's first step. Anyone can
+  mint an anonymous visitor token from that public `clientId`; no visitor login is required.
+- **No login still means visitors.** `asServiceRole` governs this app's own data access and says
+  nothing about which identity Wix sees: a public page's Wix calls run on a visitor token. Reach
+  for the admin token because a feature is owner-side, never because nobody signs in.
+- **Owner-side work beyond pages** — webhooks, scheduled jobs, explicitly authorized elevated
+  operations — is admin flow too, in backend functions.
 
 ```
 visitor pages ──(visitor token)────────────────────────► wixapis.com
@@ -69,6 +82,11 @@ admin pages   ──► base44/functions/… ──(admin token)────►
 exec_tool     ──(admin token, ad hoc management)────────► wixapis.com
 ```
 
+**The connected site owns its payments.** Whatever the visitor buys is paid on the Wix-hosted page
+this app hands them off to, with the provider the site already has. Base44's
+`<available_payment_providers>` note is about checkout that Base44 hosts instead — it does not
+apply to these flows, and asks nothing of them, whichever providers it names or rules out.
+
 ## The helpers
 
 Research and probing run in exec_tool, and one loader opens every exec (execs share no state —
@@ -118,6 +136,10 @@ One report: installed apps **with ids** (incl. Stores' catalog version — V1 vs
 endpoints), the OAuth app id (**also the visitor `clientId`**), locale, currency, CMS collections.
 An empty report = bad token, never an empty site.
 
+No OAuth app in the report means the site has none **yet**. For anything a visitor operates,
+create it with `wx.ensureOAuthApp` — one call, returns the `clientId` the frontend mints visitor
+tokens from — and build the feature on the visitor flow.
+
 Reports over 4,000 characters are saved in full to a temporary Markdown file. The result includes
 its path, byte and line counts, and a heading outline. Read that file to inspect the site context.
 

package/skills/wix-headless/SKILL.md

@@ -124,6 +124,7 @@ Compute `<SKILL_ROOT>` from this file (`<SKILL_ROOT>/SKILL.md` — strip `/SKILL
 | Image generation (opt-in; agnostic) | `<SKILL_ROOT>/references/IMAGE_GENERATION.md` |
 | Design — fallback visual quality bar for the built frontend, when the user gave no design direction of their own (managed **create** only) | `<SKILL_ROOT>/references/DESIGN.md` |
 | Content — fallback copy quality bar for the built frontend, when the user gave no copy/voice direction of their own (managed **create** only) | `<SKILL_ROOT>/references/CONTENT.md` |
+| Experience overlays — a vertical's own design + copy bar on top of DESIGN/CONTENT (optional per vertical; read when that vertical is loaded) | `<SKILL_ROOT>/references/inline-recipes/experience-<vertical>.md` (today: `experience-store.md`) |
 | AI features — text/chat + embeddings (opt-in; agnostic) | `<SKILL_ROOT>/references/AI_FEATURES.md` |
 | Feedback — relay the user's headless-experience feedback to Wix (opt-in; user-approved) | `<SKILL_ROOT>/references/FEEDBACK.md` |
 | **Authentication** — obtain `$TOKEN`/`$SITE_ID`/`clientId` (project-type-specific) | `<TYPE_DIR>/AUTHENTICATION.md` |

package/skills/wix-headless/references/CAPABILITIES.md

@@ -23,8 +23,13 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 
 ### stores — sell products
 - **Intent:** sell / shop / products / catalog / merch / store.
-- **Required site features:** a product list or grid; a page per product; categories to browse by; a cart; a checkout.
-- **Implementation checklist:** show each product's image, name, and price; show options and variants (size, colour…) where they exist; show availability / out-of-stock; a quantity picker and an add-to-cart that updates a visible cart; the product description; link each product to its category.
+- **Required site features:** a homepage that sells (what the store offers, real products, one clear shopping action); a shop / category gallery with sort, the filters the catalog supports, and paging; a page per product; categories to browse by; a cart the shopper can review and edit, opening as a side drawer after every add; checkout reachable directly from that cart.
+- **Implementation checklist:**
+  - *Homepage:* say what the store sells in the first screen; real products from the catalog under truthful headings — never a repeat of the shop page, never a heading like "Best Sellers" without data behind it.
+  - *Gallery:* a real product — image, name, price, link — visible in the first screen before any scrolling; a result count; loading, empty-catalog, no-results-for-these-filters, and error states that look different from each other.
+  - *Product page:* in the first screen, the product image, name, price, the first choice to make, and the buy button — disabled with a plain reason until every choice is made; every ribbon the merchant set; the current price and, when there is one, the labelled original price; a gallery of every product image; options with unavailable choices marked; quantity; the full description and information sections; pre-order, subscriptions, and notify-me only when the catalog has them.
+  - *Cart:* each line's image, name, chosen options, quantity (editable) and price; subtotal and discounts as Wix calculates them; "shipping and taxes calculated at checkout" rather than invented numbers; survives a reload; checkout from the drawer.
+  - *Everywhere:* availability / out-of-stock shown truthfully; each product linked to its category; no reviews, ratings, scarcity, or delivery promises the merchant didn't supply; no Wix IDs or technical words in shopper-facing text.
 
 ### blog — publish posts
 - **Intent:** blog / posts / articles / publication / news.

package/skills/wix-headless/references/SDK_HANDOFF.md

@@ -36,7 +36,7 @@ Before implementing a capability, Read the local recipe linked in its row.
 
 | Capability | Package(s) | Required recipe |
 |---|---|---|
-| stores | `@wix/stores` (+ `@wix/ecom`, `@wix/redirects` for cart/checkout) | `how-to-code-a-store.md` — Catalog V3 read + cart/checkout. |
+| stores | `@wix/stores` + `@wix/categories` (+ `@wix/ecom`, `@wix/redirects` for cart/checkout) | `how-to-code-a-store.md` — Catalog V3 gallery (sort/filter/paging), product page (variants, prices, ribbons), Cart V2 + checkout, and what a complete storefront shows. |
 | blog | `@wix/blog` (+ `@wix/ricos` to render `richContent`; **`@wix/comments` + `@wix/members`** when the blog has comments/members; `@wix/blog` `likes` when the site has members) | `how-to-code-a-blog.md` — Blog V3 read/render + member features (likes, comments). Supplement: <https://dev.wix.com/docs/sdk/business-solutions/blog.md>. |
 | cms | `@wix/data` | `how-to-code-cms.md` — `items.query` read contract. |
 | forms | `@wix/forms` | `how-to-code-forms.md` — schema-driven render (read the live form schema, visitor token/no elevate) + Form Submissions v4 write contract. |
@@ -77,6 +77,7 @@ Everything else the host resolves live from the queries in §3. (Static platform
 For each loaded capability, carry its **Required site features** and **Implementation checklist** from `references/CAPABILITIES.md` into the guide — in plain product language, lightly tailored to what was seeded. **This is the build spec, not optional polish:** the host should build every *required feature* and cover every *checklist* item. For example, a blog must show the **author** (name + photo), the publish date and reading time, the cover image, and the **full formatted content** (not flattened text) — a posts-list-plus-plain-text-body is incomplete. The host maps these onto its own components using the packages/docs in §3 and the seeded schema in §4.
 
 - State them as the *what* (product behaviour), not the *how* (no component code, no API calls) — the host owns the build.
+- **When a loaded vertical ships an experience overlay** (`references/inline-recipes/experience-<vertical>.md`; today `experience-store.md`), point the host at it alongside the checklist — it is that vertical's design and copy bar (surfaces, first-viewport rules, truthful copy), read after the general `DESIGN.md`/`CONTENT.md`.
 - If a *required feature* depends on backend support that **Seed** enabled (e.g., comments), note it's available so the host wires it. If Seed could **not** enable it, say so plainly rather than implying the site is complete.
 - **When pricing-plans is loaded, `login / account / gated content` is a *required* feature, not optional polish** — a plans grid with no way to log in and subscribe is incomplete (subscribing requires a member; §5 member-auth note). Point the host at the matching `how-to-code-members-*.md` recipe. For the other verticals, a "my …" surface (my orders / my bookings / my registrations) is a member-gated *enhancement* — list it only if the run's intent calls for an account view, and flag it needs the same login mechanism.
 - **Curation / hero / nav must come from a LIVE query, never a pinned slug/id.** A "featured" or "latest" item, a hero, and every nav/category bar must be driven by a query — "next upcoming" (`queryEvents` filtered to `UPCOMING`/`STARTED`, sorted by start date), "newest" (`queryPosts`), `queryCategories`, etc. — resolved at request time. A pinned "featured event" slug not only fails to rotate as the owner adds content, it can go **stale/past**. Even a **single-item** site (one event, one product) must drive its homepage from the *listing query*, not a hardcoded lone slug — so a second item the owner adds later surfaces automatically instead of staying invisible.

package/skills/wix-headless/references/inline-recipes/experience-store.md

@@ -0,0 +1,48 @@
+---
+name: "Storefront Experience"
+description: The storefront's own design and copy bar, on top of DESIGN.md and CONTENT.md — how to derive a store's direction from its catalog, what the homepage, gallery, product page, and cart must show, the overlay contract, truthful commerce copy, and image discipline. Read when building or wiring a store frontend; the API contract lives in how-to-code-a-store.md.
+---
+**EXPERIENCE OVERLAY**: What makes a storefront good — read after `DESIGN.md` and `CONTENT.md`
+
+`DESIGN.md` and `CONTENT.md` are the floor for every site. This file adds what is specific to a store. It is the *what* of a good storefront — the API *how* is `how-to-code-a-store.md`. The wiring is necessary, not sufficient: a store whose calls all work but whose homepage repeats the shop page, whose first screen shows no product, or whose cart hides checkout behind a page is not done.
+
+**These are defaults for when the brief doesn't say otherwise.** Whatever the user asked for in their prompt — a layout, a page they don't want, a cart page instead of a drawer, a specific look — wins over any line here.
+
+## 1 · Design from the catalog, not from the category
+
+Before choosing tokens, **look at the catalog**: the categories and their depth, the assortment size, the media (count, aspect ratios, background consistency, focal points), the options and price points, the ribbons and sales. Then write the store's direction as a few lines, held with the design tokens:
+
+- a **one-sentence thesis** — the offer, the shopper, the character;
+- **three traits**;
+- an **avoid-list** of the stereotypes this store would fall into by default: "premium" does not mean dark, serif, minimal; "kids" does not mean primary colors; a bakery is not automatically cream and script. Keep the conventions of the store's own vertical that genuinely help shoppers compare and choose;
+- one **signature decision** that makes the store recognizable with the logo hidden, backed by real content — a product form, a material, the category structure, a typographic move;
+- a **media treatment** per placement (product, category, hero, fallback): frame ratio, `cover`/`contain`, focal behavior.
+
+Two stores with the same vertical and different catalogs should look nothing alike. Never ask the user for a reference store; if they supply one, take only portable principles (hierarchy, image prominence, rhythm, density), never its layout, palette, typefaces, or taxonomy.
+
+**Audit the media before giving it a role.** Never stretch an image, enlarge a thumbnail into a hero, or crop the product away; give every image a stable aspect ratio and `object-fit` so the grid doesn't jump. When hero-scale media is absent, compose the hero from typography, a product tile, or a collage of what exists. Product photography informs compatible backgrounds and contrast; it does not automatically dictate the UI's dominant color.
+
+## 2 · The surfaces and their bar
+
+- **Global shell:** category navigation from the live tree (a curated menu is fine, but every product-bearing category stays reachable); a persistent cart control with a live count; a footer sized to the real destinations. Announcement, shipping, and returns text only from the merchant.
+- **Homepage — a merchandising surface, not the shop page again.** Say what the store sells and give one dominant shopping action in the first viewport; real products from live queries under truthful headings; category discovery when the taxonomy is meaningful. Don't reuse the same first product as hero, first card, and feature. No section exists to fill space — a claim-dependent module with no truthful source is omitted.
+- **Gallery — a discovery surface.** Title, result count, sort, the filters the catalog supports, paging; in its default state a **real product card — image, name, price, link — is inside the first viewport**, also on a short desktop window. Skeletons while loading, a distinct "no results for these filters" with a reset, an honest empty catalog, a recoverable error. Filters that stay visible with the results commit immediately; filters in a sheet stage changes until Apply.
+- **Product page — a complete purchase decision.** In the first viewport at mobile, tablet, and desktop: a recognizable product image, name, price, the first required choice (or a control that jumps to it), and the buy action with its neutral disabled reason. Then every ribbon, the full description and info sections, a gallery of **every** image, quantity, and — when the catalog has them — subscriptions, preorder, group navigation, notify-me. A sticky buy region must never cover a control.
+- **Cart — a side drawer by default**, opened after every successful add and from the header: image, name, the chosen options and text, quantity editing with pending and failure states, line prices, the calculated subtotal and discount, "shipping and taxes calculated at checkout", and checkout **from the drawer**. Persists across navigation and refresh. A separate cart page is optional, never a mandatory step before checkout.
+- **Quick add** anchors to its card (an inline or attached panel; a bottom sheet on mobile); a centered dialog is the exception for a demonstrably large configuration, not the default. Its first view shows identity, price, the first required choice, and the action.
+
+## 3 · Overlays (cart drawer, quick add, mobile nav, filter sheet)
+
+Mount at the document root — a `position: fixed` panel inside a header with a `transform`, `filter`, or `backdrop-filter` gets clipped. Full-viewport scrim; background scroll locked and inert; the panel scrolls independently with Close and the primary action always reachable; focus moves in and is trapped while modal; Escape closes; focus returns to the trigger on close (or moves to a successor surface when one overlay opens another). Verify this in the browser — CSS alone doesn't prove it.
+
+## 4 · Truthful commerce copy
+
+- **Claims come from the merchant or the data, never from the page's need for a section.** No invented reviews, ratings, "X people bought this", scarcity, delivery promises, certifications, guarantees, or payment/trust badges.
+- **Labels match their source.** "Best Sellers" needs sales data or a category the merchant named that way; the catalog's default order is not a ranking. "Featured" or the category's real name is always safe.
+- **Write for shoppers, not implementers.** No Wix IDs, API names, "catalog", "current catalog", "headless", or integration words in headings, labels, buttons, or empty states.
+- **Prices tell the truth.** A ribbon is a label, never proof of a discount; a struck price is labelled ("was") and shown only when it is real and higher; a range never gets a lone struck minimum; savings are never computed in the client.
+- **Operational text is the merchant's.** A cart says "shipping and taxes calculated at checkout" rather than a number nobody configured.
+
+## 5 · Images
+
+Responsive delivery (`srcset` + `sizes` from scaled Wix media candidates — `how-to-code-a-store.md` § Rendering product images), stable aspect ratios with `width`/`height`, lazy loading below the fold, meaningful `alt` text from the catalog's `altText` or the product name. Failed images get a visible fallback, never a broken icon.