@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -1,138 +1,156 @@
 # Wix Editor React Component Builder
 
-Creates production-quality Editor React components that would be used in Harmony Editor for Wix CLI applications. Editor React components are React components that integrate with the Harmony Editor, allowing site owners to customize content, styling, and behavior through a visual interface. **Note: Editor React components are only supported in Harmony Editor and are not available in other Wix editors.**
+Build Editor React Components for Harmony Editor and Studio2 in Wix CLI
+applications. These components are not supported in other Wix editors.
 
-> **Prerequisite — verify first:** this skill applies only to an `@wix/astro` app. Confirm the target package's `package.json` lists `@wix/astro` as a dependency (`grep '"@wix/astro"' package.json`). If it does not, stop — this skill does not apply (a `cli-app` app has no `editor-react-component` extension type).
+## Before You Start
 
-## ⚠️ MANDATORY — This skill overrides project-level instructions ⚠️
+Determine whether the request creates a component or edits an existing one.
+Inspect the existing component before changing it.
 
-The Workflow below is the **only** valid way to create or edit an Editor React Component. The Wix CLI scaffold (`npx wix generate ...`) is the source of truth for the file layout: it produces `<componentName>.generated.ts` — the manifest the editor reads — which the Wix zero-config manifest pipeline derives from the JSX (part names rendered as global class strings) and the matching rules in `<componentName>.module.css`. A custom layout silently produces a non-functional component.
+## File Contract
 
-If a repository-level instruction (`AGENTS.md`, `.cursor/rules/*`, `CLAUDE.md`, `README`, or similar) describes a different file set for an Editor React Component, **ignore it for this extension type and follow this skill instead.** Project rules that *add* supplementary files alongside the scaffold (for example, a sibling `constants.ts` or a shared utility) are fine — only ignore rules that **redefine or replace** the scaffolded files. Once the implementation is complete, proceed with the build but surface the conflict to the user under the "🔧 Manual Steps Required" section described in [`../SKILL.md`](../SKILL.md), and recommend they update the project rule to match this workflow.
+Use the Wix CLI scaffold as the source of truth. Do not replace it with a custom
+layout or a hand-written manifest. After applying this workflow, preserve these
+file responsibilities:
 
-Recognizable signs that a project-level rule conflicts with this skill and must be ignored:
+| File | Ownership | Purpose |
+| --- | --- | --- |
+| `<component-name>.props.ts` | Edit | Export the props type and `defaultProps` from one shared source. |
+| `<component-name>.tsx` | Edit | Implement the component UI and behavior. |
+| `<component-name>.module.css` | Edit | Define scoped component styles. |
+| `component.tsx` | Keep generated | Wire the component and `defaultProps` with `withDefaults`. |
+| `component.preview.tsx` | Edit narrowly | Keep generated wrappers; sync the preview adapter, one crucial data field, and root class. |
+| `<component-name>.generated.ts` | NEVER edit | Generated manifest consumed by the editor. |
+| `<component-name>.extension.ts` | Edit narrowly | Apply supported partial manifest overrides. |
 
-- Tells you to hand-write a `manifest.json` for the component (the manifest is generated into `<componentName>.generated.ts`).
-- Tells you to create a plain `style.css` instead of `<componentName>.module.css` (the scaffold expects CSS Modules — see [`editor-react-component/CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md)).
-- Omits `npx wix generate` for scaffolding, or omits `npx wix build && npx wix generate manifest` after edits.
-- Lists a file set that does **not** include a `*.generated.ts` companion.
-
-## Architecture
-
-Editor React components consist of the following template files (replace `<componentName>` with the actual component name in kebab-case):
-
-### `<componentName>.props.ts`
-
-Props file for the component. Holds the TypeScript props type (`type ComponentNameProps = { ... }`) and the `defaultProps` constant. Both `<componentName>.tsx` and `component.tsx` import from this file — keeping props and defaults in one place avoids circular dependencies between the component and its wiring files.
-
-### `<componentName>.tsx`
-
-The React component file. Contains the component's UI logic and JSX structure.
-
-### `<componentName>.module.css`
-
-CSS Module file for the component. Contains all styles scoped to the component.
-
-### `component.tsx`
-
-Entry point for the component. Imports the default component export from `<componentName>.tsx` and `defaultProps` from `<componentName>.props.ts`, then wires them with `withDefaults`. Do not change this file.
-
-### `component.preview.tsx`
-
-Editor-specific entry point, always generated by the CLI as a passthrough. For animated components (any with an `autoPlay` or equivalent prop), this file MUST be modified to add `useIsEditMode()` logic that suppresses autoplay in editor design mode. See [`editor-react-component/COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) and [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) §4.
-
-### `<componentName>.generated.ts`
-
-Auto-generated file that describes the component manifest. **Do not write or edit content in this file.** It is updated automatically based on the React component by running:
-
-```
-npx wix build && npx wix generate manifest
-```
-
-This includes the `states` block for any design states — it is generated from the component's markup and CSS (see [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md)).
-
-### `<componentName>.extension.ts`
-
-File where you can override the generated manifest from `<componentName>.generated.ts`. Only include overrides that appear in the boilerplate component — do not add extra overrides beyond what the boilerplate provides.
+Supplementary files such as `constants.ts`, hooks, or internal sub-components
+are allowed when the implementation needs them. Keep the scaffolded files and
+their responsibilities intact.
 
 ## Workflow
 
-1. **MANDATORY** — always use the scaffold; never substitute with manual file creation.
-   If `src/extensions/site/components/component-name/` does not yet exist, run
-   `npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description of what the component does"}'` to scaffold it. The scaffold creates the files under `src/extensions/site/components/<folder>/` and registers the component in `src/extensions.ts`; edit them there (not under `src/site/components/`). Skip this
-   step when iterating on an existing component — re-running it would
-   return "an extension already exist" error.
-2. Run the following script to verify that all component creation and review dependencies are installed properly:
-`node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','typescript','@types/eslint-plugin-jsx-a11y'];const missing=ps.filter(p=>!(require.resolve.paths(p)||[]).some(d=>fs.existsSync(path.join(d,p,'package.json'))));if(missing.length){console.error('Missing dependencies: '+missing.join(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser typescript @types/eslint-plugin-jsx-a11y; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-dev @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser typescript @types/eslint-plugin-jsx-a11y; fi; }`
-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
-   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
-   parts for all components. Design-states emission requires
-   `@wix/cli` ≥ 1.1.215 (native and class-triggered states work from
-   ≥ 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. 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,
-animated GIF/SVG, canvas/WebGL loop, video-like surface), or has an `autoPlay`
-(or equivalent) prop, it MUST include an on-stage play/pause control **and** the
-generated `component.preview.tsx` MUST be modified to suppress autoplay in the
-editor — follow [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md).
-
-If the component needs **runtime site context** — something no prop can carry —
-read [`editor-react-component/SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md)
-before writing the code. Triggers, and the only cases that warrant it:
-
-- The component reflects **where the visitor is** in the site (breadcrumbs, "you
-  are here" indicators) — not navigation menus, whose items the site owner
-  authors and which take a `MenuItems` prop.
-- The component needs the page's **own URL** (share, copy-link, canonical).
-- The site's language direction drives **JavaScript** (keyboard navigation,
-  transform math, conditional rendering) — not just CSS.
-- Behavior must differ while rendering inside the editor.
-
-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).
-
-## React guidelines
-
-Core rules and workflow: [`editor-react-component/REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md).
-
-Topic-focused references (rules + patterns + common mistakes in one place):
-
-- [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) — ARIA/a11y rules and patterns
-- [`editor-react-component/A11Y-REVIEW.md`](editor-react-component/A11Y-REVIEW.md) — Automated a11y scan + triage workflow to run after editing
-- [`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, 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
-- [`editor-react-component/SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) — Hooks for runtime site context (site pages, current URL, language direction, editor mode) — read only when a trigger above applies
-- [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, remaining common mistakes
-
-## CSS guidelines
-
-Reference: [`editor-react-component/CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md).
-
-For branded or themed components, also apply: [`editor-react-component/BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md).
+1. **Scaffold only when creating.** If the component folder does not exist, run:
+
+   ```bash
+   npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description"}'
+   ```
+
+   The command creates `src/extensions/site/components/<component-name>/` and
+   registers the extension in `src/extensions.ts`. Do not rerun it for an
+   existing component.
+
+2. **Run the dependency preflight.** Verify that all component creation and
+   accessibility-review dependencies are installed:
+
+   ```bash
+   node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','typescript','@types/eslint-plugin-jsx-a11y'];const missing=ps.filter(p=>!(require.resolve.paths(p)||[]).some(d=>fs.existsSync(path.join(d,p,'package.json'))));if(missing.length){console.error('Missing dependencies: '+missing.join(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-dev @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y; fi; }
+   ```
+
+3. **Plan the contract and structure.** Identify content and behavior props,
+   elect the semantic root, identify named inner parts, and decide which design
+   states each part supports. Read the relevant references from the routing
+   table below before writing code.
+
+4. **Implement the editable sources.** Preserve the scaffold contract. Keep
+   props/defaults in the props file, component logic in the main TSX file, and
+   static styling in the CSS Module. Do not edit `*.generated.ts`.
+
+5. **Run the accessibility review.** Follow
+   [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md): run both bundled
+   scanners, triage their output, complete the manual semantic checklist, fix
+   confirmed issues, and rerun the scanners on changed JSX files.
+
+6. **Configure the editor extension when required.** For a new component or a
+   requested sizing, installation, or manifest change, apply
+   [`editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md)
+   to `<component-name>.extension.ts`. Otherwise leave the file unchanged.
+   Finally, synchronize `requiredDataFields` and `rootClassName` in
+   `component.preview.tsx`.
+
+7. **Generate and validate.** Run:
+
+   ```bash
+   npx wix build && npx wix generate manifest
+   npx tsc --noEmit
+   ```
+
+   Run relevant project tests and lint commands when available. Inspect the
+   regenerated manifest; never repair it by hand. Design-state generation needs
+   `@wix/cli` 1.1.210 or newer, and prop-triggered `ElementState` generation
+   needs 1.1.215 or newer. If expected states are absent on an older CLI, report
+   the version constraint and let the user decide whether to upgrade. If the
+   build or manifest command exits with an error, diagnose it with
+   [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md), apply the
+   matching fix, and rerun both commands.
+
+8. **Report the result.** Summarize edited files and checks. Call out any
+   unresolved instruction conflict, missing dependency, unsupported CLI
+   version, or check that could not run.
+
+## Reference Policy
+
+Read every reference required for the current scope. Read an optional reference
+only when its trigger applies; when it does, that reference becomes required.
+Apply every matching row; do not load the entire reference set by default.
+
+References refine the active workflow step; they do not restart the workflow or
+expand the user's requested scope. `SKILL.md` is the only reference router;
+reference files are self-contained leaves and do not route to other references.
+For an existing component, preserve out-of-scope public props, styling,
+extension configuration, and supporting files. Never re-scaffold an existing
+component or edit `*.generated.ts` as a reference-driven fix.
+
+### 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), and [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md) and [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
+| Changing the public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), and [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
+| Changing public data props or the elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| Creating or changing an 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), and [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
+| Changing the root direction contract, direction-sensitive behavior, or a `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
+| Changing sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+
+### Optional References
+
+| Trigger | Read |
+| --- | --- |
+| An interactive or selectable part is created or changed—for example a button, link, input, tab, accordion trigger, or carousel control—or a custom state is added | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Public event callbacks are added or changed | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
+| Browser APIs, effects, or time-dependent output are introduced | [`SSR.md`](editor-react-component/SSR.md) |
+| A CSS feature or DOM API that is not clearly long-established is introduced, or the 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) |
+| Primary content is playable, looped, or autoplaying | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) and [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| Runtime site pages, URLs, JavaScript direction, or reduced-motion context is needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) |
+| Non-animation behavior must differ in editor design mode | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) and [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| The prompt explicitly requests a branded, themed, or brand-aware component | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
+
+## Core Invariants
+
+- Use React 18-compatible APIs; do not assume React 19 runtime features.
+- Include typed `id`, `className`, `direction`, and `a11y` support.
+- Apply `dir={direction}` and the unconditional fallback-direction class to the
+  elected root. Use logical CSS properties for direction-sensitive layout.
+- Keep render output deterministic and avoid browser globals during render.
+- Use only Baseline Widely Available CSS features and DOM APIs, or ones that
+  fall back to them. When a design needs a feature that is not, build the
+  supported alternative.
+- Route ARIA through the typed `a11y` contract; do not add one-off ARIA props.
+- Give every named inner part a global class, a CSS Module class, and a matching
+  `elementProps` entry. The elected root uses top-level props instead.
+- Pair each eligible native editor design-state selector with its
+  editor-injected global modifier. Keep a non-input control's keyboard-only
+  `:focus-visible` indicator standalone unless editable focus styling is
+  explicitly requested. Toggle custom global state classes from data.
+- For an item array where only one body is visible, give every item a `name`,
+  use `ActiveItemIndex<'arrayPropName'>`, render every body, and hide inactive
+  bodies accessibly.
+- If primary content autoplays or loops, provide an accessible play/pause
+  control, honor reduced motion, and suppress autoplay in editor design mode.
+- In `component.preview.tsx`, keep `withDefaults` and `withFallbackPlaceholder`,
+  wrap the preview adapter when present, normally put
+  only the one data prop crucial to meaningful rendering in
+  `requiredDataFields`, and match `rootClassName` to the root global class.

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

@@ -324,14 +324,14 @@ Site plugins can import and use Wix SDK modules directly — you do NOT need `cr
 ```typescript
 // ✅ CORRECT — Import SDK modules directly
 import { items } from "@wix/data";
-import { currentCart } from "@wix/ecom";
+import { currentCartV2 } from "@wix/ecom";
 import { products } from "@wix/stores";
 
 class MyPlugin extends HTMLElement {
   async loadData() {
     // Call SDK methods directly — no createClient needed
     const result = await items.query("MyCollection").find();
-    const cart = await currentCart.getCurrentCart();
+    const { cart } = await currentCartV2.getCurrentCart();
     const productList = await products.queryProducts().limit(10).find();
   }
 }
@@ -344,6 +344,18 @@ const wixClient = createClient({ modules: { items, products } });
 await wixClient.items.query(...); // Wrong — API surface differs through client
 ```
 
+### Identity of SDK Calls in Site Plugins
+
+A plugin runs as the **site visitor or member**, never as the app — see [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) before routing any SDK call out to a backend endpoint.
+
+The three calls above are correct exactly as written, and each for a different reason:
+
+| Call | Why it works directly |
+| --- | --- |
+| `items.query(...)` | Wix Data enforces the collection's `dataPermissions` per caller — the scaffolded default reads as `ANYONE`. See [Permissions](DATA_COLLECTION.md#permissions) |
+| `currentCartV2.getCurrentCart()` | Resolves the cart from the caller's session. Elevating it would return the app's cart, not the visitor's |
+| `products.queryProducts()` | Catalog base fields are public. `MERCHANT_DATA` and non-visible products are withheld unless the app holds `SCOPE.STORES.PRODUCT_READ_ADMIN` — don't request them from a plugin |
+
 ### Performance Considerations
 
 - Keep bundle size small - plugins load on user-facing pages

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

@@ -2,18 +2,49 @@
 
 ## Prerequisites
 
-The docs are pre-built at `node_modules/@wix/patterns/dist/docs/` (160+ markdown files + `index.json`). This requires `@wix/patterns` version **1.367.0** or later. Verify they exist:
+Lookups here are direct file reads — no script. Resolve the installed package root once per session and reuse it:
 
 ```bash
-ls node_modules/@wix/patterns/dist/docs/   # expect ~165 .md files + index.json
+node -e "
+const fs = require('fs'), path = require('path');
+function tryEnablePnp() {
+  let dir = process.cwd();
+  for (;;) {
+    const pnp = path.join(dir, '.pnp.cjs');
+    if (fs.existsSync(pnp)) { try { require(pnp).setup(); } catch {} return; }
+    const parent = path.dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+tryEnablePnp();
+try {
+  console.log(path.dirname(require.resolve('@wix/patterns/package.json', { paths: [process.cwd()] })));
+} catch {
+  let dir = process.cwd();
+  for (;;) {
+    const candidate = path.join(dir, 'node_modules', '@wix', 'patterns');
+    if (fs.existsSync(path.join(candidate, 'package.json'))) { console.log(candidate); process.exit(0); }
+    const parent = path.dirname(dir);
+    if (parent === dir) { console.error('@wix/patterns not found'); process.exit(1); }
+    dir = parent;
+  }
+}
+"
 ```
 
-If the directory is missing, install the package at the minimum version:
+A bare `require.resolve` without the PnP-activation step throws in a Yarn Berry project even when the package is installed — run the whole snippet, not a shortened version.
+
+Then confirm the installed version actually ships the bundle index:
 
 ```bash
-npm install @wix/patterns@^1.367.0
+ls <pkgRoot>/dist/dts-bundle/index.json
 ```
 
+**If it's missing, stop — do not look elsewhere for types or docs.** The installed `@wix/patterns` predates the index; it ships from **1.458.0** onward, so upgrade to at least that and re-run the check. A missing *file* is not the same as a name not being covered (see below): the mechanism itself isn't available yet.
+
+**Never inspect `node_modules` by hand** — no `ls`, no `find`, no `cat` of an arbitrary path, and that includes the sanctioned directories: never browse `dist/dts-bundle/` or `dist/docs/` looking around. Every lookup below names the exact file to `Read` — go straight to it.
+
 ## Library Architecture
 
 ### Composition Hierarchy
@@ -29,55 +60,33 @@ Provider                     <- WixPatternsProvider or WixPatternsBMProvider
 
 Each collection type follows the same Component + State + Hook pattern:
 
-| Collection       | Component          | State Type              | Hook                            |
-|------------------|--------------------|-------------------------|---------------------------------|
-| Table            | `Table`            | `TableState`            | `useTableCollection()`          |
-| Grid             | `Grid`             | `GridState`             | `useGridCollection()`           |
-| TableGridSwitch  | `TableGridSwitch`  | `TableGridSwitchState`  | `useTableGridSwitchCollection()`|
-| TableFolders     | `TableFolders`     | `TableFoldersState`     | `useTableFolders()`             |
-| GridFolders      | `GridFolders`      | `GridFoldersState`      | `useGridFolders()`              |
-
-This table covers the common collection types — the full, authoritative list is in `node_modules/@wix/patterns/dist/docs/index.json`.
+| Component | State Type | Hook |
+| --- | --- | --- |
+| `Table` | `TableState` | `useTableCollection()` |
+| `Grid` | `GridState` | `useGridCollection()` |
+| `TableGridSwitch` | `TableGridSwitchState` | `useTableGridSwitchCollection()` |
+| `TableFolders` | `TableFoldersState` | `useTableFolders()` |
+| `GridFolders` | `GridFoldersState` | `useGridFolders()` |
 
-Create state with the hook -> pass it to the component's `state` prop -> wrap in a page component.
+Common types only; `dist/dts-bundle/index.json` has the authoritative set. Create state with the hook -> pass it to the component's `state` prop -> wrap in a page component.
 
 ### Choosing the Right Provider
 
-| Provider                        | When to Use                                                                          |
-|---------------------------------|--------------------------------------------------------------------------------------|
-| `WixPatternsProvider`           | **Default — start here.** Auto-detects the environment (BM, Essentials, Giza) and supplies the right context. |
-| `WixPatternsBMProvider`         | Optional alternative for Yoshi BM Flow over Business Manager.                        |
-| `WixPatternsGizaProvider`       | Optional alternative for Yoshi BM Flow over Giza.                                    |
-| `WixPatternsEssentialsProvider` | Yoshi Fullstack.                                                                     |
-| `WixPatternsBaseProvider`       | App does **not** run under a Giza/WixEssentials environment and you inject services (i18n, sentry) yourself. |
-
-Prefer `WixPatternsProvider` unless the project is on one of the specific Yoshi flows above — it is the documented recommendation for most apps, and it resolves the environment for you rather than making you pick.
+| Provider | When to Use |
+| --- | --- |
+| `WixPatternsProvider` | **Default — start here.** Auto-detects the environment (BM, Essentials, Giza). |
+| `WixPatternsBMProvider` | Optional alternative for Yoshi BM Flow over Business Manager. |
+| `WixPatternsGizaProvider` | Optional alternative for Yoshi BM Flow over Giza. |
+| `WixPatternsEssentialsProvider` | Yoshi Fullstack. |
+| `WixPatternsBaseProvider` | App does **not** run under Giza/WixEssentials and you inject services (i18n, sentry) yourself. |
 
-**Confirm the import path in the provider's own doc file** — these do not all come from the same subpath (`WixPatternsEssentialsProvider` and `WixPatternsBaseProvider` are under `@wix/patterns/essentials`, for instance). Check the project's `package.json` to identify the flow.
+**Confirm the import path in the provider's own bundle** — they don't all share a subpath (`WixPatternsEssentialsProvider` and `WixPatternsBaseProvider` are under `@wix/patterns/essentials`). The project's `package.json` identifies the flow.
 
 ### Keep Provider and Page Separate
 
-The provider **must** be in a separate parent component from the page content. Hooks like `useTableCollection` require the provider's context to already exist above them in the React tree.
+The provider **must** live in a parent component of the page content: hooks like `useTableCollection` need its context to already exist above them in the React tree.
 
-**Wrong — provider and page in the same component:**
-```tsx
-function BadApp() {
-  const state = useTableCollection({
-    queryName: 'my-items',
-    itemKey: (item) => item.id,
-    itemName: (item) => item.name,
-    fetchData: async () => ({ items: [], total: 0 }),
-    filters: {},
-  }); // fails at runtime — no provider context above this component
-  return (
-    <WixPatternsProvider>
-      <CollectionPage>
-        <Table state={state} columns={[{ title: 'Name', render: (item) => item.name }]} />
-      </CollectionPage>
-    </WixPatternsProvider>
-  );
-}
-```
+**Wrong:** calling `useTableCollection` in the same component that renders `WixPatternsProvider`. The hook runs before the provider exists above it, so it throws at runtime — and the JSX nesting looks right, which is what makes this hard to spot.
 
 **Correct — provider in root, page in a separate file:**
 ```tsx
@@ -97,13 +106,14 @@ import { Table, useTableCollection } from '@wix/patterns';
 import { CollectionPage } from '@wix/patterns/page';
 
 function MyCollectionPage() {
+  // works — the provider context exists above this component
   const state = useTableCollection({
     queryName: 'my-items',
     itemKey: (item) => item.id,
     itemName: (item) => item.name,
     fetchData: async () => ({ items: [], total: 0 }),
     filters: {},
-  }); // works — the provider context exists above this component
+  });
   return (
     <CollectionPage>
       <Table state={state} columns={[{ title: 'Name', render: (item) => item.name }]} />
@@ -112,33 +122,33 @@ function MyCollectionPage() {
 }
 ```
 
-Always keep the provider (and router if needed) in the app's root component, and each page in its own file.
+Keep the provider (and router, if any) in the app's root component and each page in its own file.
 
-When the user needs **multiple pages**, use the `@wix/patterns` routing solution (`PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate`) instead of a separate router. Look up the relevant doc files for setup details.
+For **multiple pages**, use the `@wix/patterns` routing solution (`PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate`) rather than a separate router; look the doc files up for setup.
 
 ## How to Look Things Up
 
 **Don't guess which components or props exist — read the doc files first.**
 
-### Finding the right file
+### Finding the right name
+
+`Read <pkgRoot>/dist/dts-bundle/index.json` — one entry per name, grouped implicitly by its `category` field. Lookup is **exact-match only**: no fuzzy matching, no typo suggestions. If the exact key isn't there, scan the index you already hold for something close before concluding the name isn't covered.
 
-- **By name:** Read `node_modules/@wix/patterns/dist/docs/index.json` — it maps every component name to its doc file and category.
-- **By browsing:** List the `dist/docs/` folder. Filenames match component names directly (e.g., `Table.md`, `useTableCollection.md`). Note some names contain spaces (`AI Assistant.md`) or dots (`CollectionPage.Header.md`) — quote paths when searching.
-- **By concept:** Search filenames for keywords (e.g., "filter"). Check `index.json` categories — related components share a category prefix.
+Not every real `@wix/patterns` export is in this index — only the names these guides actually reference. If a name you need genuinely isn't there, **stop and say so rather than falling back to `node_modules`.**
 
 ### Reading doc files
 
-Each doc contains the component's category, import path, description, code examples, and API props table. **Always check the import statement** — not everything comes from `@wix/patterns` (some use subpaths like `@wix/patterns/provider`).
+`Read <pkgRoot>/dist/docs/index.json` to resolve a name to its doc file — or a `symbols` alias, for the cases where the Storybook title doesn't match the export (`ExportTo.md` documents `ExportButton`) — then `Read <pkgRoot>/dist/docs/<file>.md` directly, the whole file, not piped through `head`. It covers more names than the bundle index above: it's produced for every documented component, not just the curated ones.
 
-### Following cross-references
+**Always check the import statement inside the doc** — not everything comes from `@wix/patterns` (some use subpaths like `@wix/patterns/provider`).
 
-Docs contain relative Storybook URLs like `[TableState](./?path=/story/...--tablestate)`. To resolve these, **use the link text as the filename**: `[TableState](...)` -> read `TableState.md`.
+### Reading the file the index names
 
-Links to `https://www.docs.wixdesignsystem.com/` are external (Wix Design System) — not part of `@wix/patterns` docs.
+The mechanics of the file an index names — types the docs don't cover, which one-line stubs are answers rather than truncation, subpath entry points, cross-references, split compound-component docs — are in [Reading bundles and docs](dashboard-page/PATTERNS_BUNDLE_READING.md). Read it before your first `dist/dts-bundle/*.d.ts` of the session.
 
 ## The Collection → Entity Flow
 
-A collection page and its item form are **two patterns pages**, not a page plus a modal. Getting the table right and then hand-building the "add item" form in a dashboard modal is the most common way this goes wrong.
+A collection page and its item form are **two patterns pages**, not a page plus a modal. Getting the table right and then hand-building the "add item" form as a dashboard modal is the most common way this goes wrong.
 
 | Step | What owns it |
 | --- | --- |
@@ -149,24 +159,20 @@ A collection page and its item form are **two patterns pages**, not a page plus
 | Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
 | The individual fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
 
-`navigateToEntityPage` is preferred over a plain route change because the entity header (title, subtitle, breadcrumbs) renders immediately, without waiting for the fetch.
+Prefer `navigateToEntityPage` over a plain route change: the entity header (title, subtitle, breadcrumbs) renders immediately, without waiting for the fetch.
 
-Read `EntityPage.md`, `useEntityPage.md`, and `usePatternsNavigate.md` before implementing — and note that `useCreateCollection` is **not** about creating items; it returns a function that initializes collection state.
+Read `EntityPage.md`, `useEntityPage.md`, and `usePatternsNavigate.md` before implementing — and note `useCreateCollection` is **not** about creating items; it returns a function that initializes collection state.
 
-Reserve dashboard modals for genuine dialogs — delete confirmations, short prompts — not entity editing.
+Three things about the `useEntityPage` call are worth getting right first time — both generics, what `onSave` receives, which params exist: [ENTITY_PAGE_TOOLKIT.md](dashboard-page/ENTITY_PAGE_TOOLKIT.md).
+
+Reserve dashboard modals for dialogs that neither write nor display a listed record — a delete or discard confirmation, an unsaved-changes prompt. **A create / "add new" form is not one of them**: it writes the record, so it is an `EntityPage` even though nothing is being edited yet. Size and field count are not exceptions — a one-field create form is still an `EntityPage`. A page that lists no records is outside this rule.
 
 ## When Patterns Has No Equivalent
 
-A concept is only "missing" from patterns after you've checked `index.json` **and** searched the docs folder by keyword. Then, and only then:
+A concept is only "missing" from patterns after you've checked `dist/dts-bundle/index.json` and `dist/docs/index.json` **and** searched by keyword within what you've read. Then, and only then:
 
 1. Look the component up in `@wix/design-system` via the `wix-design-system` skill.
 2. Render it *inside* the patterns page shell / collection, not as a replacement for it.
-3. If WDS lacks it too, compose from WDS primitives (`Box`, `Card`, `Text`) — never restyle patterns internals or add another UI library.
-
-Anything page- or collection-shaped (page shell, header, table, grid, filters, sorting, paging, row actions, bulk actions) is patterns' territory. If you're about to build one of those from WDS parts, you skipped a lookup.
-
-## Tips
+3. If WDS lacks it too, compose from WDS primitives (`Box`, `Card`, `Text`) — never restyle patterns internals, never add another UI library.
 
-- **Compound components** have separate docs per sub-part: `CollectionPage.md`, `CollectionPage.Header.md`, `CollectionPage.Content.md`.
-- **Hook docs** list configuration options as props in the API table.
-- **Type docs** (e.g., `TableState.md`) describe the shape of state objects.
+Anything page- or collection-shaped (page shell, header, table, grid, filters, sorting, paging, row and bulk actions) is patterns' territory. If you're about to build one from WDS parts, you skipped a lookup.

package/skills/wix-app/references/backend-event/COMMON-EVENTS.md

@@ -21,8 +21,8 @@ Order events use **`@wix/ecom`** (namespace `orders`). Order **refund** events a
 | Order canceled | `import { orders } from "@wix/ecom"` | `orders.onOrderCanceled(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderCanceled](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-canceled?apiView=SDK) |
 | Refund created | `import { refunds } from "@wix/payments"` | `refunds.onRefundCreated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundCreated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-created?apiView=SDK) |
 | Refund updated | `import { refunds } from "@wix/payments"` | `refunds.onRefundUpdated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundUpdated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-updated?apiView=SDK) |
-| Cart created | `import { cart } from "@wix/ecom"` | `cart.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-created?apiView=SDK) |
-| Cart updated | `import { cart } from "@wix/ecom"` | `cart.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-updated?apiView=SDK) |
+| Cart created | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-created?apiView=SDK) |
+| Cart updated | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-updated?apiView=SDK) |
 
 ## Bookings Events