@wix/agent-skills 1.32.0 → 1.33.0

package/package.json

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

@@ -19,6 +19,24 @@ Keep the Wix CLI scaffold and file roles:
 
 Supplementary files are allowed; keep scaffold roles intact.
 
+## Required Reading (blocking)
+
+Before writing code, open and read in full every reference in the matching
+row. An unopened one is a failed run. Open paths directly; never skim or
+grep instead.
+
+| Scope | Required references |
+| --- | --- |
+| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md), [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
+| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
+| Changing public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
+| Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
+| Creating or changing layout/content | [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
+| Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
+| Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+
 ## Workflow
 
 1. **Scaffold only when creating.** Run in the Wix app (`wix.config.json`).
@@ -31,9 +49,9 @@ Supplementary files are allowed; keep scaffold roles intact.
    Never rerun the scaffold for an existing component.
    Write a meaningful `description` in 1-2 plain sentences (max 300 chars): what
    the user sees, when to use it, and capabilities that affect that choice.
-   Don't repeat the component name or add implementation details.
+   Don't repeat the name or add implementation details.
 
-2. **Run the dependency preflight.** Check required packages:
+2. **Run the dependency preflight.**
 
    ```bash
    deps=(@wix/react-component-schema @wix/react-component-utils @wix/editor-react-types)
@@ -56,16 +74,15 @@ Supplementary files are allowed; keep scaffold roles intact.
    }
    ```
 
-3. **Plan.** Identify props, root, parts, and states; read routed references.
-   Use the scaffold and references before inspecting package declarations.
-   Inspect only needed declarations resolved by the app for undocumented APIs
-   or fields, or typecheck failures. They govern API shapes; retain editor rules.
+3. **Plan.** Identify props, root, parts, and states; open all required references first.
+   Use them and the scaffold before inspecting package declarations; inspect
+   only for undocumented APIs or fields, or typecheck failures. Declarations
+   govern API shapes; retain editor rules.
 
 4. **Implement.** Keep props, logic, and styles in their scaffolded editable
-   files. Format edited source files with the app's configured formatter before
-   checking formatting. Never edit or format `*.generated.ts`.
+   files. Format edited source files with the app's formatter. Never edit or format `*.generated.ts`.
 
-5. **Run the accessibility review.** Once the JSX is complete, run from the
+5. **Run the accessibility review (mandatory).** Once the JSX is complete, run from the
    same folder (`<SKILL_ROOT>` is the directory containing the active `SKILL.md`):
 
    ```bash
@@ -89,43 +106,30 @@ Supplementary files are allowed; keep scaffold roles intact.
    ```
 
    Run `npx tsc --noEmit`, relevant tests/lint, and the accessibility review.
-   If later edits affect a check, rerun that
-   check. Inspect the manifest when generated; never hand-repair it. Diagnose
-   failures with
+   If later edits affect a check, rerun that check. Inspect the manifest when generated; never hand-repair it.
+   Diagnose failures with
    [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 
    For creation/layout changes, complete the routed overflow resize review.
 
-8. **Report.** Summarize files, checks, blockers, and checks that could not run.
+8. **Report.** Summarize files, checks, blockers, unrun checks.
+   List required references as read/unread; read any unread one and fix first.
 
 ## Reference Policy
 
-Read only matched references. Preserve unrelated behavior. `SKILL.md` routes;
-references are leaves.
-
-### Required References
-
-| Scope | Required references |
-| --- | --- |
-| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
-| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
-| Changing public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
-| Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
-| Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
-| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
-| Creating or changing layout/content | [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
-| Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
-| Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+Read every required reference for the matched scope, optional ones only on
+trigger. Preserve unrelated behavior. References are leaves.
 
 ### Optional References
 
 | Trigger | Read |
 | --- | --- |
 | Interactive/selectable part, custom state, or open/reveal toggle | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Disabled or invalid state | [`DISABLED-INVALID.md`](editor-react-component/DISABLED-INVALID.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) |
+| `npx wix build` or manifest generation errors or warns | [`MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md) |
 | Animation, video, carousel, or other playable/looped/autoplaying content | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
 | Site/runtime/editor context hooks needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) (+ [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) when design-mode behavior differs) |
 | Branded, themed, or brand-aware component requested | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
@@ -137,9 +141,7 @@ references are leaves.
 - Elected root: `dir={direction}`, fallback-direction class, logical CSS for
   direction-sensitive layout.
 - Deterministic render; no browser globals during render.
-- Explicit foreground colors need a known contrasting background; transparent
-  roots inherit from the host.
-- Baseline Widely Available CSS/DOM only, or supported fallbacks.
+- Baseline Widely Available CSS/DOM only, or fallbacks.
 - Accessibility per part, per [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md):
   read only `a11y.ariaLabel`, and only for a control without a visible name;
   never spread the `a11y` object or add one-off ARIA props.
@@ -149,17 +151,14 @@ references are leaves.
 - Native design states: interactive elements only, never a non-interactive root
   or part; pair selectors with injected modifiers; toggle custom state classes
   from data, each with a matching `:global()` rule.
-- Open/close/reveal (click/hover/focus): props-only root
+- Open/close/reveal: props-only root
   `isOpen: ElementState<boolean>` synced to state; module classes, no `--open` class.
 - Single-visible-body arrays: `name` per item, `ActiveItemIndex<'prop'>`, render
   all bodies, hide inactive accessibly.
 - No arrays inside array items; keep group fields flat (no object props).
 - Autoplay/loop: play/pause control, honor reduced motion, suppress autoplay in
   editor design mode.
-- Resizable layout: keep required content usable at 320px. Reflow visible
-  groups inside their page and cap track minima with
-  `minmax(min(100%, <minimum>), 1fr)`. Follow [`OVERFLOW.md`](editor-react-component/OVERFLOW.md).
-- Preview composition, inline or through variables:
-  `withDefaults(withFallbackPlaceholder(PreviewOrComponent, options), defaultProps)`.
-  Keep `withDefaults` outermost; use one crucial data field and match the root
-  class.
+- Resizable layout: keep required content usable at 320px, per
+  [`OVERFLOW.md`](editor-react-component/OVERFLOW.md).
+- Preview: `withDefaults` outermost, one crucial data field, matching root
+  class, per [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md).

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

@@ -64,19 +64,24 @@ export interface MyAnimationProps {
   direction?: Direction;
   a11y?: A11y;
 
-  /** Start playing on load. Default `true`. */
+  /** Start playing on load. */
   autoPlay?: boolean;
 
-  /** Repeat when finished. Default `true`. */
+  /** Repeat when finished. */
   loop?: boolean;
 
-  /** Show play/pause button. Default `'showOnHover'`. */
   pauseButtonVisibility?: 'showAlways' | 'showOnHover';
 
   elementProps?: {
     myAnimationPlayButton?: { className?: string };
   };
 }
+
+export const defaultProps = {
+  autoPlay: true,
+  loop: true,
+  pauseButtonVisibility: 'showAlways',
+} as const;
 ```
 
 Omit `loop` when repeat is unsupported.
@@ -183,7 +188,7 @@ Set the visibility data attribute on the existing elected root, preserving its
 full root contract:
 
 ```tsx
-data-pause-button-visibility={pauseButtonVisibility ?? 'showOnHover'}
+data-pause-button-visibility={pauseButtonVisibility}
 ```
 
 Wire the named part completely:
@@ -210,7 +215,7 @@ Wire the named part completely:
 /* Narrow behavior-only exception documented in CSS-GUIDELINES.md. Keep editable
    appearance on .playButton and use this relationship only for visibility. */
 
-/* showOnHover (default) */
+/* showOnHover */
 .root[data-pause-button-visibility="showOnHover"] .playButton {
   opacity: 0;
   pointer-events: none;
@@ -222,7 +227,7 @@ Wire the named part completely:
   pointer-events: auto;
 }
 
-/* showAlways — no extra CSS needed; button is visible by default */
+/* showAlways (default) — no extra CSS needed; button is visible by default */
 ```
 
 ## 4. Suppress Autoplay in `component.preview.tsx`

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

@@ -23,7 +23,8 @@ in the component's `.tsx` and `.module.css`.
 | 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`) |
+| `button`/`input`/`select`/`textarea`/`fieldset` when asked or its action can be unavailable | `disabled` |
+| `input`/`select`/`textarea` with a constraint or `setCustomValidity`; a `form`/`fieldset` with one | `invalid` |
 | Has a selectable/variant value in its data — `selected`/`active`/`current`/`checked`/`featured` | that custom state |
 | Whole component opens/collapses or reveals content (expandable panel, disclosure, dropdown, drawer, popup, tooltip) on click, hover or focus | root `isOpen` state, no part `open` state (§6) |
 | None of the above, incl. a non-interactive root or part | no states, and no `:hover`/`:active`/`:focus` rules, even decorative; resting style only |
@@ -110,8 +111,6 @@ The local static accessibility scan cannot measure rendered color contrast.
   spread alone suffices (it merges `className` itself). The key is the global
   class in camelCase (`COMPONENT-CONTRACT.md`).
 
-Wire native and custom states as follows:
-
 ```tsx
 <button
   type="button"

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

@@ -0,0 +1,31 @@
+# Disabled and Invalid Wiring
+
+Use after DESIGN-STATES.md §1 decides a part exposes `disabled` or `invalid`. A
+native element's `:disabled` or `:invalid`, paired with the `:global` modifier in
+the §3 rule, is what generates the state.
+
+## Disabled
+
+Author it when asked, or when the control stays visible but its action can be
+unavailable (unmet precondition, request in progress, sold out). Otherwise author
+no `disabled` binding and no `--disabled` rule.
+
+## Invalid
+
+Author it only for a native field with a constraint (`required`, `pattern`,
+`type="email"`, …) or a `setCustomValidity` message. An unconstrained field is
+never invalid.
+
+For validity from outside the field (a server check, a password confirmation),
+call `setCustomValidity` in the component file, on the field itself: through a
+ref bound with `ref={confirmRef}`, a callback ref, or `event.currentTarget` in an
+`on*` handler (inline, or a function of the component passed by name). The field may be in a component of the same file
+that renders it. Not from a custom hook, a function outside the component, or
+another file, and not through a ref given to a custom component. A field in a loop
+or rendered conditionally is detected when every field with that `ref` or handler
+prop calls it. If only some do, the ones that do may not be detected: give them a
+constraint prop instead, otherwise leave `invalid` off them.
+
+A `form` or `fieldset` is invalid when a field inside it is
+(`.form:global(.signup-form--invalid), .form:invalid`), with no constraint of its
+own; with no constrained field it is never invalid.

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

@@ -1,7 +1,7 @@
 # Manifest Build Errors
 
 Use this reference only when `npx wix build` or `npx wix generate manifest`
-exits with an error. Read the error name from the first token before the colon
+exits with an error or prints a warning. For an error, read the error name from the first token before the colon
 (`IoError:`, `ParseError:`, or `NotFoundError:`), then apply the matching fix.
 
 | Error | Fix |
@@ -20,6 +20,19 @@ exits with an error. Read the error name from the first token before the colon
 
 After each fix, re-run `npx wix build && npx wix generate manifest` to confirm.
 
+## Warnings
+
+The build can also print non-fatal warnings such as
+`[css] … styles selectors that matched no element in the extraction render`.
+Read every warning and fix it; this is mandatory, with one exception below.
+
+- **A part's own class** (`.errorMessage`, `.item`) means the part is not
+  mounted in the extraction render. Keep it mounted per `PARTS.md`, then
+  re-run build and manifest generation.
+- **A class applied only by state** (`.contentOpen` from `open && styles.contentOpen`)
+  is expected: the part is mounted and only the state look is absent. Leave the
+  markup and CSS unchanged; do not force the state on or remove the styling.
+
 ## Checklist
 
 - [ ] The fix matches the reported error name and message.

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

@@ -46,9 +46,38 @@ Apply this filter to every candidate:
   share the same semantic editor surface. Distinguish position with data or a
   module-only helper class, not separate part names.
 
-The manifest generator can silently omit a named part behind conditional JSX.
-Keep an editor-controlled part mounted in the render it inspects. Hide it with
-CSS driven by a data attribute, or disable it when it should remain visible.
+## Keep Every Part Mounted
+
+The manifest is generated from a single server-side render of the component
+with mock props. Effects do not run and `useState` keeps its initial value, so
+markup that is not mounted in that render, and the CSS that styles it, never
+reaches the manifest. The source is not changed afterwards: write it so every
+part is mounted regardless of state.
+
+- Mount every phase (loading, error, empty, question, result) and hide the
+  inactive ones with the `hidden` attribute. Never write
+  `phase === 'x' && <Part />`. Give a `hidden` element no author `display`
+  rule: it would override `hidden`.
+- While data is missing, render one static placeholder item inside a hidden
+  wrapper so the item parts exist. It is never visible.
+- Mutually exclusive messages (loading, error, empty) are one part whose text
+  switches by phase, not several parts with the same name.
+- A modifier toggled by state (`correct`, `incorrect`) is a design state; see
+  `DESIGN-STATES.md`.
+
+```tsx
+const item = current ?? placeholderItem; // placeholder shows only while hidden
+
+<div hidden={phase !== 'question'}>
+  <h3
+    {...elementProps?.quizQuestion}
+    className={classNames('quiz-question', styles.question, elementProps?.quizQuestion?.className)}
+  >
+    {item.question}
+  </h3>
+</div>
+```
+
 After generating the manifest, confirm that its `elements` include every
 intended named part and that each `elementProps.<key>` read in code equals the
 camelCase of that part's global class.

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

@@ -29,9 +29,11 @@ const items = buildItems(props.items);
 return <ul>{items.map(renderItem)}</ul>;
 ```
 
-This does not require every data branch to render simultaneously. Empty,
-loading, and error states may be conditional when their initial value is stable
-and the same on server and client.
+This does not require every data branch to render simultaneously: loading,
+empty, and error states may be conditional when their initial value is stable
+and the same on server and client. A branch that contains a named part must
+still be mounted in the first render, or the manifest omits that part (see
+`PARTS.md`).
 
 ## Deterministic Output
 
@@ -47,4 +49,5 @@ format, or a client-only enhancement that does not replace the initial markup.
 
 - [ ] No browser globals are accessed at module scope or during render.
 - [ ] Initial server/client markup is complete and identical.
+- [ ] Every named part is mounted in the first render.
 - [ ] Render output does not depend on random, clock, locale, or timezone state.

package/skills/wix-headless-kit/install/pins.json

@@ -3,6 +3,6 @@
   "@wix/create-new": "0.0.124",
   "typescript": "5.8.3",
   "templates": {
-    "ref": "v1.32.0"
+    "ref": "v1.33.0"
   }
 }