@wix/agent-skills 1.8.0 → 1.9.0

package/package.json

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

@@ -72,7 +72,8 @@ Topic-focused references (rules + patterns + common mistakes in one place):
 - [`editor-react-component/DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`editor-react-component/PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
-- [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, remaining common mistakes
+- [`editor-react-component/SSR.md`](editor-react-component/SSR.md) — Server-side rendering rules (mandatory)
+- [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — CSS rules, remaining common mistakes
 
 ## CSS guidelines
 

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

@@ -13,6 +13,20 @@ Rules and patterns for ARIA accessibility support in Editor React components.
 - The `A11y` type includes: `ariaLabel`, `ariaDescribedBy`, `ariaLabelledBy`, `role`, `ariaHidden`, `ariaLive`, and all other ARIA attributes.
 - Users provide ARIA values through the `a11y` prop: `<Component a11y={{ ariaLabel: "..." }} />`
 
+### Stable IDs for Element Relationships
+
+ARIA relationships (`aria-controls`, `aria-labelledby`, `aria-describedby`) and `htmlFor` need element ids. Generate them with `useStableId` from `@wix/react-component-utils` — passing the `id` prop as the override — never `Math.random()`, a manual counter, or a bare `React.useId()` (those break SSR/hydration). See [`SSR.md`](SSR.md) for the full rule.
+
+```tsx
+import { useStableId } from '@wix/react-component-utils';
+
+const rootId = useStableId(id);
+const panelId = `${rootId}-panel`;
+
+<button aria-controls={panelId}>{label}</button>
+<div id={panelId} role="tabpanel">{content}</div>
+```
+
 ### ARIA Label Rules
 
 ARIA labels are user-facing content and must NEVER be hardcoded as string literals in JSX.

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

@@ -8,7 +8,8 @@ This guide defines rules and guidance on **how to implement** production-quality
 - [`DIRECTIONALITY.md`](DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`COMPONENT-API.md`](COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
-- [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
+- [`SSR.md`](SSR.md) — Server-side rendering rules (mandatory)
+- [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — CSS rules, common mistakes
 
 ## React 18 features are not supported
 
@@ -42,6 +43,10 @@ Direction support is mandatory — see [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
 
 See [`ACCESSIBILITY.md`](ACCESSIBILITY.md) for full rules and patterns.
 
+### SSR Safety
+
+Components are server-rendered, then hydrated — they MUST render correctly, completely, and identically on the server. See [`SSR.md`](SSR.md) for full rules and patterns.
+
 ### TypeScript
 
 - All components must be fully typed
@@ -67,11 +72,11 @@ All components MUST follow these patterns:
 
 **1. SSR-Safe Implementation**
 
-- NO browser APIs at module scope (window, document, navigator, etc.)
-- Guard browser APIs with typeof checks or useEffect
-- All browser-dependent logic must run client-side only
+- NO browser APIs at module scope or during render (window, document, navigator, etc.) — guard inside `useEffect`
+- First render must be complete and deterministic; effects are client-only enhancement
+- Internal ids via `useStableId`; NO `useLayoutEffect`
 
-See [`REACT-PATTERNS.md`](REACT-PATTERNS.md) §1.1 for code examples.
+See [`SSR.md`](SSR.md) for full rules and code examples.
 
 **2. Clean Code**
 
@@ -162,6 +167,6 @@ See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.
 
 **Phase 1: Analysis** — Parse information, map component structure (see Part 0)
 
-**Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards
+**Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; verify SSR safety against [`SSR.md`](SSR.md)
 
 **Phase 3: Styles** — Apply Part 2 SCSS rules

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

@@ -6,23 +6,7 @@ Code patterns and common mistakes for Editor React components.
 
 ## 1.1 SSR-Safe Implementation
 
-Avoid browser-only APIs at module scope or during render; use them inside `useEffect` with `typeof window !== 'undefined'`.
-
-**❌ Wrong:**
-
-```typescript
-const userAgent = window.navigator.userAgent;
-```
-
-**✅ Correct:**
-
-```typescript
-useEffect(() => {
-  if (typeof window !== "undefined") {
-    const userAgent = window.navigator.userAgent;
-  }
-}, []);
-```
+Components are server-rendered then hydrated. See [`SSR.md`](SSR.md) for the full rules and code examples (browser globals, complete first render, deterministic output, `useStableId`, no `useLayoutEffect`).
 
 ## 1.2 Element Visibility (Platform-Managed)
 
@@ -102,6 +86,8 @@ different — they go through a JS-toggled modifier class; see
 
 ## 3.2 Browser APIs at module scope
 
+See [`SSR.md`](SSR.md) for the full SSR rules.
+
 **❌ Wrong:**
 
 ```typescript

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

@@ -0,0 +1,119 @@
+# Server-Side Rendering (SSR)
+
+Rules and patterns for SSR-safe Editor React components.
+
+Editor React components are server-rendered and then hydrated on the client — every component MUST render correctly, completely, and identically on the server. SSR safety is mandatory for every component.
+
+---
+
+## Rules
+
+### No browser globals at module scope or during render
+
+`window`, `document`, `navigator`, `localStorage`, `sessionStorage`, `matchMedia`, `IntersectionObserver`, `ResizeObserver`, and other DOM/BOM APIs do not exist on the server. Never touch them at module scope or in the render body. Access them only inside `useEffect`, optionally guarded with `typeof window !== 'undefined'`.
+
+**❌ Wrong:**
+
+```typescript
+const userAgent = window.navigator.userAgent;
+```
+
+**✅ Correct:**
+
+```typescript
+useEffect(() => {
+  if (typeof window !== "undefined") {
+    const userAgent = window.navigator.userAgent;
+  }
+}, []);
+```
+
+### First render must be complete
+
+Render all parts unconditionally — never gate structural elements behind effect-set state. Initialize `useState` to a valid, server-renderable default so the first (server) render already shows the final structure. Element visibility is platform-managed; see [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`REACT-PATTERNS.md`](REACT-PATTERNS.md) §1.2.
+
+**❌ Wrong — content only appears after an effect runs (missing on the server):**
+
+```tsx
+const [items, setItems] = useState<Array<Item>>([]);
+useEffect(() => {
+  setItems(buildItems(props));
+}, [props]);
+return <ul>{items.map(/* ... */)}</ul>; // empty on the server
+```
+
+**✅ Correct — derive during render so it exists on the first pass:**
+
+```tsx
+const items = buildItems(props);
+return <ul>{items.map(/* ... */)}</ul>;
+```
+
+### Deterministic render
+
+The same props MUST produce the same markup on the server and the client. No `Math.random()`, `Date.now()`, `new Date()`, or locale/timezone-dependent output during render — these differ across environments and break hydration.
+
+**❌ Wrong:**
+
+```tsx
+<span>{new Date().toLocaleString()}</span>
+```
+
+**✅ Correct — derive from props, or compute in an effect:**
+
+```tsx
+<span>{formatDate(props.timestamp)}</span>
+```
+
+### Stable IDs via `useStableId`
+
+When a component needs an internal id (ARIA wiring such as `aria-controls` / `aria-labelledby`, or `htmlFor`), generate it with `useStableId` from `@wix/react-component-utils`. Never use `Math.random()`, a manual counter, or a bare `React.useId()` — those break hydration or are not available across runtimes. Pass the component's `id` prop as the override so a caller-supplied id wins, then derive child ids from the result.
+
+**✅ Correct:**
+
+```tsx
+import { useStableId } from '@wix/react-component-utils';
+
+const rootId = useStableId(id);
+const panelId = `${rootId}-panel`;
+
+<button aria-controls={panelId}>{label}</button>
+<div id={panelId} role="tabpanel">{content}</div>
+```
+
+**❌ Wrong:**
+
+```tsx
+const panelId = `tab-${Math.random()}`; // ❌ differs every render
+const panelId = React.useId();          // ❌ use the useStableId util instead
+```
+
+### No `useLayoutEffect`
+
+`useLayoutEffect` does nothing on the server and triggers a React warning. Use `useEffect` for client-only work.
+
+**❌ Wrong:**
+
+```tsx
+useLayoutEffect(() => { measure(); }, []);
+```
+
+**✅ Correct:**
+
+```tsx
+useEffect(() => { measure(); }, []);
+```
+
+### Effects are client-only enhancement
+
+`useEffect` runs only after hydration, never on the server. Use effects to enhance — not to produce the initial UI. The server-rendered default state must already look correct before any effect runs.
+
+---
+
+## SSR Checklist
+
+- [ ] No browser globals at module scope or in the render body — guarded inside `useEffect` only
+- [ ] All parts render unconditionally on the first pass; state initialized to a server-safe default
+- [ ] Render output is deterministic — no `Math.random()` / `Date.now()` / `new Date()` / locale-dependent output during render
+- [ ] Internal ids come from `useStableId(id)`, never random values, counters, or bare `React.useId()`
+- [ ] No `useLayoutEffect`

package/skills/wix-design-system/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-design-system
-description: Wix Design System component reference. Use when building UI with @wix/design-system, choosing components, checking props and examples, or writing tests with component testkits. Triggers on "what component", "how do I make", "WDS", "show me props", "testkit", "driver", or component names like Button, Card, Modal, Box, Text.
+description: Wix Design System component reference. Use when building UI with @wix/design-system, choosing components, checking props and examples, or writing tests with component testkits. Triggers on "what component", "how do I make", "WDS", "show me props", "testkit", "driver", or component names like Button, Card, Box, Text.
 ---
 
 # WDS Documentation Navigator

package/skills/wix-headless/references/BUILD-astro.md

@@ -171,14 +171,12 @@ cp "<SKILL_ROOT>/references/astro/templates/stores/back-in-stock.ts" "src/utils/
 cp "<SKILL_ROOT>/references/astro/templates/stores/categories.ts"     "src/utils/categories.ts"
 # ecom (loaded)
 cp "<SKILL_ROOT>/references/astro/templates/ecom/discounts.ts"        "src/utils/discounts.ts"
-# bookings (loaded) — elevated SSR API endpoints + SeoTags
-mkdir -p src/pages/api
-cp "<SKILL_ROOT>/references/astro/templates/bookings/api/confirm-booking.ts" "src/pages/api/confirm-booking.ts"
-cp "<SKILL_ROOT>/references/astro/templates/bookings/api/waitlist.ts"        "src/pages/api/waitlist.ts"
-cp "<SKILL_ROOT>/references/astro/templates/bookings/SeoTags.astro"          "src/components/SeoTags.astro"
+# bookings (loaded) — the booking SDK module + SeoTags
+cp "<SKILL_ROOT>/references/astro/templates/bookings/bookingDriver.ts" "src/components/bookingDriver.ts"
+cp "<SKILL_ROOT>/references/astro/templates/bookings/SeoTags.astro"    "src/components/SeoTags.astro"
 ```
 
-`categories.ts` is imported by `pages-categories`/`pages-products`/`pages-home-and-nav`; `back-in-stock.ts` by stores components; `discounts.ts` by ecom components + stores product pages; the bookings API endpoints (elevated `confirmBooking` seat-hold + native v1 waitlist register) by `BookingForm.tsx`, and `SeoTags.astro` by `services/[slug].astro`. Static, brand-agnostic SDK wrappers — if not pre-copied, multiple scopes race to author them.
+`categories.ts` is imported by `pages-categories`/`pages-products`/`pages-home-and-nav`; `back-in-stock.ts` by stores components; `discounts.ts` by ecom components + stores product pages; `bookingDriver.ts` (the ecom-Cart-V2 booking sequence — `book()`/`navigateToCheckout()`) by the bookings islands, and `SeoTags.astro` by `services/[slug].astro`. Static, brand-agnostic SDK wrappers — if not pre-copied, multiple scopes race to author them.
 
 ### Dispatch the wave — one concurrent batch (private agents) + a serialized shell chain alongside it
 
@@ -193,7 +191,7 @@ One merged "build" agent per loaded vertical (Instruction file = that vertical's
 **B · Serialized shell chain — agents that patch `Navigation.astro` / `index.astro`** (read-modify-write a shared file → concurrent dispatch trips the staleness guard `File has been modified since read`, **per-file, not per-marker**). **Launch one, wait for its return, launch the next** — each sees the previous one's insertion. Runs **alongside** batch A, not after it. The shell-patchers (today): **ecom, stores `pages-home-and-nav`, bookings, gift-cards** — exactly the packs with `nav:`/`home:` markers:
 - **ecom-build** — `components` (CartView, CartBadge) → `pages` (`cart.astro`, `thank-you.astro` private, **+ CartBadge mount in `Navigation.astro` at `<!-- nav:actions -->`**).
 - **stores-home-and-nav** — patch `index.astro` product grid at `<!-- home:stores -->` + `Navigation.astro` Shop submenu at `<!-- nav:links -->`. Writes no islands; pure shell-patcher.
-- **bookings-build** — `components` (ServiceCard, AvailabilityCalendar, BookingForm, ServiceBookingFlow, ManageBooking) → `pages` (`services/index.astro`, `services/[slug].astro`, `booking-confirmation.astro`, `manage-booking.astro` private, **+ Services link in `Navigation.astro` at `<!-- nav:links -->` / services teaser in `index.astro` at `<!-- home:bookings -->`**).
+- **bookings-build** — `components` (AvailabilityCalendar, BookingForm, ServiceBookingFlow islands; `bookingDriver.ts` + `SeoTags.astro` are pre-copied) → `pages` (`services/index.astro`, `services/[slug].astro`, `ServiceCard.astro`, `booking-confirmation.astro` private, **+ Services link in `Navigation.astro` at `<!-- nav:links -->` / services teaser in `index.astro` at `<!-- home:bookings -->`**).
 - **gift-cards-build** — `components` (probe util, GiftCardPurchase island) → `pages` (gift-cards landing + `Navigation.astro` `<!-- nav:links -->` / `index.astro` `<!-- home:gift-cards -->`).
 
 Cross-vertical imports (`stores-home-and-nav` importing `CategoryRail`/`ProductCard`/`utils/categories.ts`) resolve at **build time**, not write time, so they impose no write-ordering between the chain and batch A. The only ordering: (i) shell-patchers serialize against each other (per-file), (ii) everything is on disk before Build.

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

@@ -96,7 +96,7 @@ npm install --no-fund --no-audit --legacy-peer-deps <package-set> \
 | | **blog** → `@wix/blog @wix/ricos @astrojs/rss @astrojs/sitemap` |
 | | **forms** → `@wix/forms` |
 | | **cms** → `@wix/data @wix/essentials` |
-| | **bookings** → `@wix/bookings @wix/essentials` |
+| | **bookings** → `@wix/bookings @wix/essentials @wix/forms @wix/redirects @wix/auto_sdk_ecom_cart-v-2` |
 | | **gift-cards** → (none — disabled-by-default pack ships no Astro-time imports) |
 
 Example (resolved set = stores + ecom + gift-cards + cms):