@wix/agent-skills 1.15.1 → 1.16.0

package/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md

@@ -1,157 +1,268 @@
+# Wix Bookings — ready-made client
 
-# Wix Bookings Skill
+The bookings client is **shipped as real files**, not snippets to regenerate. It's a complete
+service catalog + detail page + slot picker + booking flow (create booking → hosted checkout),
+styled with your app's design tokens (base44's `src/index.css` — the shadcn palette the design phase
+already set). Copy it into the app and wire the routes —
+you generate almost none of the booking code (the `{ services }` / `{ slots }` destructuring, the
+local wall-clock date args, the null-slot re-validate guard, the participant cap, the eCom
+redirect-session all ship and are correct).
 
-> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and both bookings helpers from `references/bookings/`. All helpers import from `"./wix-client.js"`, so copy them into the same folder (e.g. `src/rest/`). Copy **both** for the full booking flow:
->
-> | File | What it covers |
-> |---|---|
-> | `wix-bookings-services.js` | Service listing, slot availability, media URL helper |
-> | `wix-bookings-checkout.js` | Create booking, hosted checkout, bookAndCheckout convenience |
+Talks to Wix directly over the public `WIX_CLIENT_ID` (anonymous visitor tokens). Never mock
+services or slots; never hand-build a `/checkout` URL — the shipped flow creates the booking through
+the API and completes it via the eCom redirect-session.
 
-Builds a real, client-only Wix Bookings front end. The browser talks to Wix directly over a
-public `WIX_CLIENT_ID`. Never mock services or slots; never hand-build a `/checkout` URL —
-always create the booking through the API and complete it via the eCom checkout + redirect-session.
+## Prerequisites
+- The site's **Wix Bookings** setup is the read/book target. It's installed and seeded separately
+  (see **Seeding** below), in parallel with this build — so it may have no services at build time;
+  the client renders the shipped empty state until services (and staff/working hours, so slots are
+  bookable) land. This client is read-only over services — it does not provision them.
+- The public headless **`WIX_CLIENT_ID`** from your prompt (buyer-facing, safe to hardcode/commit).
+- For **paid** services, the site must accept payments and the deployed app domain must be
+  allow-listed on the OAuth client for the hosted checkout to return. Those are separate Wix setup
+  flows the user completes later — out of scope here; if checkout return fails before that, it's
+  expected, flag it and continue.
 
-This skill ships the single-service booking flow for **APPOINTMENT and CLASS** services: browse
-services → pick a service → pick an available slot → enter details → book → hosted checkout.
-Appointments and classes differ only in the availability call (`listAvailableSlots` vs
-`listEventTimeSlots`); `listSlotsForService` routes by `service.type`, and `createBooking` handles
-either slot. **COURSE (whole-course enrollment) is not covered** — see "Beyond the snippets".
+## STEP 1 — The client is already in `src/`
+The install step (base44.md STEP 1) deployed the whole bookings UI client + REST scaffolds into
+`src/` (imports use the `@/` alias → `src/`). Here's every file and what it is — **this is your map,
+so you don't need to open them:**
 
-## When to use
-- User wants a Wix Bookings appointment site or asks to "connect Wix Bookings".
-- Replacing placeholder/mock services or fake calendars with live Wix data.
-- Adding service listings, a slot picker, booking creation, or checkout over an existing
-  Wix Bookings setup.
+| file | what it is |
+|---|---|
+| `hooks/useServices.js` | services-list data — one page + `loadMore` paging, plus the category menu (`categories` / `activeCategory` / `setActiveCategory`); `total === 0` → empty state |
+| `hooks/useServiceDetail.js` | detail + booking flow — load service, list slots, hold slot/contact/participants, re-validate + book + checkout |
+| `lib/serviceFacts.js` | price / duration / capacity / where / reschedule labels, derived from a service — rateType-aware, so VARIED and NO_FEE services still show a price |
+| `components/ServiceCard.jsx`, `ServiceGrid.jsx` | service listing UI (grid + card, with empty state); the card shows price, tagline and a `60 min · 1-to-1` meta row |
+| `components/SlotPicker.jsx` | bookable-slot chips + paging (pure UI, driven by `useServiceDetail`) |
+| `components/BookingForm.jsx` | contact + participant form (pure UI, driven by `useServiceDetail`) |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `pages/Services.jsx`, `pages/ServiceDetail.jsx` | the two shipped routes (`/services`, `/service/:serviceId`); the detail page is two-column — service + a duration/price/where strip on the left, the sticky booking panel on the right |
+| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-client.js` | REST transport — mints/persists the anonymous visitor token |
+| `rest/wix-bookings-services.js` | services + availability: `queryServices`, `queryServicesByCategory`, `categoriesOf`, `getService`, `countServices`, `listSlotsForService`, `listAvailableSlots`, `listEventTimeSlots`, `getAvailableSlot`, `mediaUrl` |
+| `rest/wix-bookings-checkout.js` | booking + checkout: `createBooking`, `checkoutBooking`, `bookAndCheckout` |
 
-## Prerequisites
-1. A Wix site with **Wix Bookings installed and at least one appointment service created**
-   (this skill does NOT provision — it's read-only over services). Staff/resources and a
-   booking policy should be configured so slots are bookable.
-2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the Wix
-   Business Manager surfaces a copyable prompt with the id filled in — see the router `SKILL.md`). Paste
-   it into `src/rest/wix-client.js` in place of the placeholder. It is a buyer-facing credential
-   (it only mints anonymous visitor tokens), **not** a secret, so hardcoding/committing it is fine.
-3. The site must **accept payments** for paid services, and the deployed app domain must be
-   allow-listed on the OAuth client for Wix-hosted checkout to return. These are **separate Wix
-   setup flows the user completes later** — out of this skill's scope. If checkout return fails
-   before that setup is done, that's expected; flag it and continue.
-
-## The API (copy as-is; do not re-derive it)
-This skill ships only the REST layer — no UI components. Build the booking UI however the
-project wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
-adjust import paths:
-- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to the
-  id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor refresh token IS
-  the booking visitor identity; it is persisted to localStorage. Do not re-mint anonymously per
-  load.
-- `src/rest/wix-bookings-services.js` — **Services & availability:**
-  `queryServices`, `getService`, `countServices`, `listAvailableSlots`, `getAvailableSlot`,
-  `mediaUrl` (resolve a service image to an absolute URL)
-- `src/rest/wix-bookings-checkout.js` — **Booking & checkout:**
-  `createBooking`, `checkoutBooking`, `bookAndCheckout`
-
-The `Service`, `TimeSlot`, and `Booking` shapes are documented as JSDoc comments at the top of
-each helper file. Read them before building the UI — they describe the key fields and link to
-the full API reference for anything not shown.
-
-## How to wire it (UI is the project's choice)
-- **Service list** — `queryServices()` for the listing (visitor-visible services only). Render
-  `name`, `tagLine`, the image via `mediaUrl(service.media?.items?.[0]?.image)`, and the price
-  from `payment.fixed.price`. `value` + `currency` are always present; `formattedValue` is
-  **optional** (it may be missing), so don't depend on it — build the price from `value`+`currency`
-  and use `formattedValue` only when present. e.g. `new Intl.NumberFormat(undefined, { style:
-  'currency', currency }).format(Number(value))`. (Rendering `formattedValue` alone leaves the price
-  blank — or your "Varies" fallback — whenever it's absent.) Pass the returned
-  `nextOffset` back as `offset` to load the next page. Books **APPOINTMENT and CLASS** services
-  (see the slot picker below); COURSE is whole-course enrollment and out of scope.
-- **Service detail** — `getService(serviceId)` keyed off the URL/route; returns null on miss —
-  show a not-found state, never invent a service. Render `description`, price, and `locations`.
-- **Slot picker** — use **`listSlotsForService(service, { fromLocalDate, toLocalDate, timeZone? })`**:
-  it routes by `service.type` — APPOINTMENT → `listAvailableSlots` (staff working hours), CLASS/COURSE
-  → `listEventTimeSlots` (scheduled sessions). Both return the same slot shape. (Call the specific
-  function directly if you already know the type.) Dates are **local** wall-clock strings
-  `"YYYY-MM-DDThh:mm:ss"` (no zone), interpreted in `timeZone` (defaults to the visitor's IANA zone).
-  Only `bookable: true` slots come back. Render each `slot.localStartDate`/`localEndDate`; group by
-  day for a calendar. Pass `nextCursor` back
-  as `cursor` to page.
-- **Booking form** — collect the buyer's `firstName`, `lastName`, `email`, `phone`. Keep it
-  minimal; richer per-service form fields live in the service's `form.id` (see "Beyond the snippets").
-- **Participant count** — cap it by the service policy, not just slot capacity. The most a single
-  booking may reserve is `service.bookingPolicy.participantsPolicy.maxParticipantsPerBooking`. Only
-  render a participant selector when that value is `> 1`, and bound its max at
-  `min(maxParticipantsPerBooking, slot.remainingCapacity)` for a class; when it is `1` (the common
-  case) show no selector and book exactly one. Never offer a fixed range like 1–4 — the slot's
-  `remainingCapacity` tells you the class's open spots, not how many one buyer may take, so relying
-  on it alone lets the buyer pick a count that `createBooking` then rejects. Pass the chosen count
-  as `createBooking`'s `totalParticipants`.
-- **Re-validate + book** — right before submitting, call
-  `getAvailableSlot(serviceId, { localStartDate, localEndDate, timeZone? })` to confirm the slot
-  is still open (and to pick up the staff resource). Then create + check out in one step:
-  `window.location.href = (await bookAndCheckout(slot, { email, firstName, lastName, phone })).checkoutUrl;`
-  Or split it: `const booking = await createBooking(slot, contact); const url = await checkoutBooking(booking.id);`
-- **Confirmation / return** — after the buyer returns from hosted checkout, the order is placed
-  and Wix Bookings confirms the booking automatically (status becomes `CONFIRMED`, or `PENDING`
-  if the service needs manual approval). Show a confirmation screen on return.
-- **Empty state** — if `countServices()` is 0, show an empty state telling the user to add a
-  service in their Wix dashboard. Never invent services.
-
-## Hard rules (do not violate)
-- ✅ Book ONLY via `createBooking()` → `checkoutBooking()` (or `bookAndCheckout()`), then redirect
-  to the returned `fullUrl`.
-- ❌ Never hand-build a `/checkout`, booking, or calendar URL.
-- ❌ Never mock services, time slots, or availability — render live Wix data or the empty state.
-- ❌ Never invent reviews, ratings, staff, or testimonials. Empty review UI only.
-- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
-- ✅ Send availability/booking dates as **local** `"YYYY-MM-DDThh:mm:ss"` strings plus a
-  `timeZone` — do not send UTC `Z` timestamps to the slot APIs.
-- ✅ Re-validate the slot with `getAvailableSlot()` before `createBooking()` — slots get taken.
-- ✅ Cap participant count at `service.bookingPolicy.participantsPolicy.maxParticipantsPerBooking`
-  (render no selector when it is 1); never offer a fixed range and never use slot capacity as the
-  per-buyer limit — a count above the policy makes `createBooking` fail.
-- The client fails loudly on purpose: `createBooking`/`checkoutBooking` throw on an unbookable
-  slot, a missing booking id, or a missing redirect URL. A green path means it's really bookable —
-  don't swallow these.
-
-## Beyond the snippets
-The snippets cover **APPOINTMENT and CLASS** bookings (the slot picker routes by `service.type`).
-For anything beyond that, extend the client: add a new helper on `wixApiRequest`, looking up the
-exact endpoint, method, and body in the **official Wix API reference** first (never guess):
-- Official Wix API reference: https://dev.wix.com/docs/api-reference.md
-- Single-service booking flow (the full picture): https://dev.wix.com/docs/api-reference/business-solutions/bookings/flow-single-service-booking.md
-- **Courses are NOT covered — a course is enrolled as a *whole*, not booked per session.**
-  `listEventTimeSlots` returns **no** per-session slots for a COURSE (verified — empty even for admin),
-  so the slot-picker flow doesn't apply. Enrolling in a course uses a course-specific flow (whole-course
-  capacity computed from bookings) that these snippets don't implement —
-  https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-reader-v2/query-extended-bookings.md
-- **Service variants / participants** (duration- or person-based pricing):
-  https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/service-options-and-variants/get-service-options-and-variants-by-service-id.md
-- **Add-ons:** https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/list-add-on-groups-by-service-id.md
-- **Custom booking form fields** (render `service.form.id`): Get Form Summary —
-  https://dev.wix.com/docs/rest/crm/forms/form-schemas/get-form-summary.md
-- **Member login + a "my bookings" account view** → the **members** vertical
-  (`references/members/INSTRUCTIONS.md`): booking itself works anonymously, but signing a member in
-  (custom login on your own UI) lets them see their own appointments/history.
-
-Keep the snippets as the default for everything they already do; reach for the API reference
-only for the gap.
+They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
+`read_file` the shipped page/component/hook source to inspect it** — the table above says what each
+is, and every field shape you need is in the snippets below. Read a shipped file's source **only**
+on a real fallback — a runtime error, or a field the snippets don't cover (see "Fallback only" at
+the end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
+`references/bookings/app/` → `src/`.)
+
+## STEP 2 — Credentials
+Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
+one place both ids live.
+
+## STEP 3 — Theme (nothing to style on the shipped components)
+The shipped components carry **no palette of their own** — they render from base44's design tokens
+in `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`,
+`--muted`, `--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`,
+`text-foreground`, `bg-primary`, `text-muted-foreground`, `border-border`, `rounded-lg`,
+`font-display`). Those tokens are **already set to the brand by the design phase**, so the shipped
+pages are themed with zero work here. To adjust the palette, edit `index.css` (`:root` **and**
+`.dark`) — the base44 way; **never add a parallel theme file (e.g. a `theme.css`) or restyle the
+shipped JSX.** Build the Home/Header you add (STEP 4) from the **same** base44 tokens/classes so it
+matches automatically. A dark brand is just base44's dark palette in `index.css` — no per-component work.
+
+## STEP 4 — Wire routes (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+**No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
+`App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
+replace it. Bookings needs **no cross-page provider** (there's no cart — each booking completes on
+its own detail page), so there's nothing to wrap the tree in.
+- Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
+  route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every** page
+  — including the shipped `Services` / `ServiceDetail` — so you **never edit the shipped pages to add
+  a header/footer** (they render inside `<Outlet/>` as-is).
+- **Pin the top chrome as one fixed block.** Put `<WixManageBanner/>` (shipped, preview-only) **above**
+  your `<Header/>` inside a single `position:fixed` top region — the header itself is plain in-flow
+  markup, the region owns the fixing — so banner + header ride together (no scroll drift/gap). Pad
+  the content by the region's **ResizeObserver-measured** height so it clears the chrome and
+  self-corrects when the banner is dismissed.
+- Routes under the Layout: `/services` → `Services`, `/service/:serviceId` → `ServiceDetail` (both
+  shipped, as-is). **You add `/` → your own Home** page.
+
+```jsx
+import { useRef, useState, useEffect } from "react";
+import { Routes, Route, Outlet } from "react-router-dom";
+import WixManageBanner from "@/components/WixManageBanner";   // shipped, preview-only · default export, no props
+import Services from "@/pages/Services";               // shipped · default export, no props
+import ServiceDetail from "@/pages/ServiceDetail";     // shipped · default export, no props
+import Home from "@/pages/Home";           // YOU build
+import Header from "@/components/Header";   // YOU build — plain in-flow markup, NOT position:fixed
+import Footer from "@/components/Footer";   // YOU build
+
+function Layout() {
+  const topRef = useRef(null);
+  const [offset, setOffset] = useState(0);
+  useEffect(() => {                                  // measure the fixed region → pad content below it
+    const ro = new ResizeObserver(() => setOffset(topRef.current?.offsetHeight ?? 0));
+    if (topRef.current) ro.observe(topRef.current);
+    return () => ro.disconnect();
+  }, []);
+  return (<>
+    <div ref={topRef} style={{ position: "fixed", top: 0, left: 0, right: 0, zIndex: 50 }}>
+      <WixManageBanner />                    {/* null on the published site / when dismissed */}
+      <Header />                             {/* your brand header, in-flow inside this fixed block */}
+    </div>
+    <div style={{ paddingTop: offset }}>     {/* clears the chrome; shrinks when the banner is dismissed */}
+      <Outlet />                             {/* shipped Services/ServiceDetail render here, untouched */}
+      <Footer />
+    </div>
+  </>);
+}
+
+<Routes>
+  <Route element={<Layout />}>                                       {/* chrome wraps all */}
+    <Route path="/" element={<Home />} />                            {/* yours */}
+    <Route path="/services" element={<Services />} />                {/* shipped, as-is */}
+    <Route path="/service/:serviceId" element={<ServiceDetail />} /> {/* shipped, as-is */}
+  </Route>
+</Routes>
+```
+
+## What you build (not shipped)
+The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the
+`Layout` (STEP 4) so they wrap every route — plus the overall brand story, styled with the same
+base44 tokens/classes. **Compose the shipped pieces** — a "featured services" strip is just
+`queryServices` + the shipped `ServiceGrid`; the nav is a link to `/services`:
+
+```jsx
+import { useState, useEffect } from "react";
+import { Link } from "react-router-dom";
+import { queryServices } from "@/rest/wix-bookings-services";
+import ServiceGrid from "@/components/ServiceGrid";
+
+// Responsive header: choose ONE branch with a state flag (copy this pattern). Do NOT render a
+// desktop nav AND a mobile nav toggled by Tailwind `hidden md:flex` / `md:hidden`: these navs are
+// inline-styled, and an inline `display` beats a Tailwind class, so `hidden` never applies — BOTH
+// branches render. One branch = one nav.
+export function Header() {
+  const [mobile, setMobile] = useState(() => window.innerWidth < 768);
+  useEffect(() => {
+    const onResize = () => setMobile(window.innerWidth < 768);
+    window.addEventListener("resize", onResize);            // keep it reactive to viewport changes
+    return () => window.removeEventListener("resize", onResize);
+  }, []);
+  return (
+    <nav style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+      {/* brand/logo */}
+      {mobile ? <YourMenu /> : <Link to="/services">Services</Link>}
+    </nav>
+  );
+}
+export function Featured() {                                // on your home page
+  const [services, setServices] = useState([]);
+  // NB: queryServices returns { services, total, nextOffset } — destructure the array.
+  useEffect(() => { queryServices({ limit: 6 }).then(({ services }) => setServices(services)); }, []);
+  return <ServiceGrid services={services} empty="Services coming soon." />;
+}
+```
+Everything reads base44's design tokens (`index.css`), so your home/nav match the shipped pages automatically.
+
+**Editing a component and the change doesn't show? It's the preview, not your code.** The dev
+preview can serve a stale module after a write. Before diagnosing a visual bug you just "fixed", do a
+fresh full navigate/reload of the preview and re-check — don't keep rewriting correct code against a
+stale render.
+
+## Using the client from your own UI
+The two shipped hooks are the whole flow. If you build a custom surface, drive it the same way:
+
+```jsx
+// LIST — every list helper returns an OBJECT, not a bare array. Destructure it:
+const { services, total, nextOffset } = await queryServices({ limit: 24 });   // total 0 → empty state
+if ((await countServices()) === 0) { /* show the empty state — never invent services */ }
+
+// DETAIL — getService(id) is keyed off the route param; returns null on a miss (not-found, never invent):
+const service = await getService(serviceId);
+
+// FACTS (price / duration / capacity / where / reschedule note) — lib/serviceFacts.js branches on
+// payment.rateType and on APPOINTMENT-vs-CLASS for you. Reading payment.fixed.price yourself renders
+// NOTHING for a VARIED or NO_FEE service, and duration is empty on a class:
+const price = servicePriceLabel(service);      // "€95.00" · "From €85.00" · "Free" · "" for CUSTOM
+const minutes = serviceDuration(service);      // 60 for an appointment; null for a class/course
+const where = serviceLocationLabel(service);   // from payment.options — service.locations has no name
+
+// IMAGE — the primary image is media.mainMedia; resolve through mediaUrl (Wix media can be a bare
+// handle, not a full URL). Fall back to the gallery/cover:
+const img = mediaUrl(service.media?.mainMedia?.image ?? service.media?.items?.[0]?.image ?? service.media?.coverMedia?.image);
+
+// SLOTS — listSlotsForService routes by service.type and returns { slots, nextCursor }; iterate .slots.
+// Dates are LOCAL wall-clock "YYYY-MM-DDThh:mm:ss" (NO zone / Z). The LIST call takes
+// fromLocalDate/toLocalDate — the single-slot re-validate (getAvailableSlot) takes
+// localStartDate/localEndDate. They are NOT interchangeable.
+// It also returns `timeZone` — the zone those localStartDate strings are in. Label the picker with
+// that value rather than a locally guessed zone, so the times and the label can't disagree.
+const { slots, nextCursor, timeZone } = await listSlotsForService(service, { fromLocalDate, toLocalDate });
+
+// BOOK — re-validate the picked slot (getAvailableSlot returns the slot or NULL — guard it), then
+// book + check out and redirect. Participants: cap at
+// service.bookingPolicy.participantsPolicy.maxParticipantsPerBooking (commonly 1 → no selector);
+// never use slot.remainingCapacity as the per-buyer limit.
+const fresh = await getAvailableSlot(service.id, { localStartDate, localEndDate });
+if (!fresh) { /* "that time was just taken — pick another" */ }
+const { checkoutUrl } = await bookAndCheckout(fresh, { email, firstName, lastName, phone }, { totalParticipants });
+window.location.href = checkoutUrl;   // hosted checkout; on return the booking is CONFIRMED/PENDING
+```
+
+## Extending the client
+The shipped flow covers **APPOINTMENT and CLASS** services (`listSlotsForService` routes by
+`service.type`). For anything beyond that, add a helper on `wixApiRequest`, looking the endpoint up
+in the **`wix-docs`** skill first (never guess):
+- **COURSE** enrollment — a course is enrolled as a *whole*, not per session; `listEventTimeSlots`
+  returns no slots for it, so the slot-picker flow doesn't apply (course-specific flow).
+- **Service variants / participants** (duration- or person-based pricing), **add-ons**, and
+  **custom booking form fields** (render `service.form.id`).
+- **Member login + a "my bookings" view** → the **members** vertical
+  (`references/members/INSTRUCTIONS.md`): booking works anonymously, but signing a member in lets
+  them see their own appointments.
+
+Fallback only — when you hit an error or need something not shown here: read the relevant shipped
+file under `src/`, or look it up via the **`wix-docs`** skill. Each helper in
+`wix-bookings-services.js` / `wix-bookings-checkout.js` links its own reference page inline; these are
+the areas they sit in:
+- Bookings (services, categories, bookings): https://dev.wix.com/docs/api-reference/business-solutions/bookings.md
+- Availability time slots: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots.md
+- eCommerce checkout (paid bookings): https://dev.wix.com/docs/api-reference/business-solutions/e-commerce.md
+- Headless redirect session (hosted checkout): https://dev.wix.com/docs/api-reference/business-management/headless/redirects.md
+
+## Hard rules
+- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
+- Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped
+  `Services`/`ServiceDetail` to add chrome.
+- The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your
+  `Header` is plain in-flow markup (not `position:fixed`).
+- Send availability/booking dates as **local** `"YYYY-MM-DDThh:mm:ss"` strings + a `timeZone` — never
+  UTC `Z` timestamps to the slot APIs.
+- Re-validate the slot with `getAvailableSlot()` before booking; guard the `null` — slots get taken.
+- Cap participants at `maxParticipantsPerBooking` (no selector when 1); never offer a fixed range and
+  never use slot capacity as the per-buyer limit.
+- Book only through the shipped flow (`bookAndCheckout` / `createBooking`→`checkoutBooking`) and
+  redirect to the returned URL — never a hand-built `/checkout` or calendar URL.
+- Render live Wix data or the shipped empty state — never mock services, slots, or availability, and
+  never invent reviews, ratings, staff, or testimonials.
 
 ## Point the user to their dashboard
-In some cases, users need to access the Wix dashboard in order to edit the bookings content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For bookings data those pages are:
-- **Booking Services** — `https://manage.wix.com/dashboard/{metaSiteId}/bookings/services` (`Dashboard → Bookings → Booking Services`; add services and service categories)
-- **Staff** — `https://manage.wix.com/dashboard/{metaSiteId}/bookings/staff` (`Dashboard → Bookings → Staff`; add staff and set working hours, so slots are actually bookable)
-
-Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
-
-## Verification checklist (before declaring done)
-- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
-- [ ] Visitor token persists across reload (same visitor identity across reloads)
-- [ ] `queryServices()` renders live services; `countServices()` 0 → empty state (no mock services)
-- [ ] `listAvailableSlots()` returns real bookable slots for a chosen service and date range
-- [ ] Slot is re-validated with `getAvailableSlot()` immediately before booking
-- [ ] Participant selector capped by `maxParticipantsPerBooking` (hidden when 1) — a count above the policy is not offerable
-- [ ] `createBooking()` returns a booking with `status: "CREATED"` and a real id
-- [ ] Checkout redirects via redirect-session `fullUrl` (no hand-built URL)
-- [ ] On return from checkout the booking is confirmed (status `CONFIRMED`/`PENDING`)
-- [ ] No mock services, slots, or availability anywhere
-- [ ] Told the user at least once that they can continue setting up their bookings in the dashboard and provided deep links.
+Provide deep links so the owner can manage bookings content (substitute the site's `metaSiteId`):
+- **Booking Services** — `https://manage.wix.com/dashboard/{metaSiteId}/bookings/services` (add
+  services and service categories)
+- **Staff** — `https://manage.wix.com/dashboard/{metaSiteId}/bookings/staff` (add staff and set
+  working hours, so slots are actually bookable)
+
+## Seeding
+Seed the services per `seed/SEED.md` (the build-time setup module) — separate from this client
+build; run in parallel.
+
+## Verify (before declaring done)
+- [ ] Client files copied into `src/`; `WIX_CLIENT_ID` set (not the placeholder).
+- [ ] Brand palette lives in `index.css` (`:root`/`.dark`); no parallel theme file; shipped components/pages not restyled or rewritten.
+- [ ] **Opened `/services` and a service detail page** (not just the home page) and confirmed the shipped cards render themed (surface, text, brand color) with images.
+- [ ] `Layout` (fixed `<WixManageBanner/>` + `<Header/>` region, then `<Outlet/>` + Footer) wraps all
+      routes; shipped `Services`/`ServiceDetail` untouched; content clears the fixed chrome.
+- [ ] Visitor token persists across reload (same visitor identity across reloads).
+- [ ] `queryServices()` renders live services; empty catalog shows the shipped empty state (no mock services).
+- [ ] Slot picker shows real bookable slots; the slot is re-validated with `getAvailableSlot()` right before booking.
+- [ ] Participant selector capped by `maxParticipantsPerBooking` (hidden when 1).
+- [ ] Booking redirects to the hosted checkout URL the client returns; on return the booking is CONFIRMED/PENDING.
+- [ ] No mock services, slots, or availability anywhere.

package/skills/wix-vibe-headless/references/bookings/app/components/BookingForm.jsx

@@ -0,0 +1,65 @@
+// Contact + participants form — pure UI. All state/handlers (field setters, participant cap,
+// submit, submitting, error) come from useServiceDetail; this only renders them. The participant
+// selector shows ONLY when maxParticipants > 1 (commonly 1 → no selector, book exactly one).
+// Styled with base44 design tokens (shadcn Tailwind classes).
+const fieldCls =
+  "w-full px-3 py-2.5 box-border font-body border border-input rounded-sm bg-background text-foreground";
+const labelCls = "block mb-1.5 text-[11px] uppercase tracking-wide text-muted-foreground";
+
+export default function BookingForm({
+  contact, setContactField, maxParticipants, participants, setParticipants,
+  onSubmit, submitting, canSubmit, error, needsApproval, timeLabel, priceLabel,
+}) {
+  // Naming the time and price on the button is the last confirmation before payment, so what the
+  // buyer clicks states exactly what they're committing to.
+  const what = [timeLabel, priceLabel].filter(Boolean).join(" · ");
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); onSubmit(); }} className="flex flex-col gap-4">
+      <div className="flex gap-3">
+        <div className="flex-1">
+          <label className={labelCls} htmlFor="bk-first">First name</label>
+          <input id="bk-first" className={fieldCls} value={contact.firstName} onChange={setContactField("firstName")} />
+        </div>
+        <div className="flex-1">
+          <label className={labelCls} htmlFor="bk-last">Last name</label>
+          <input id="bk-last" className={fieldCls} value={contact.lastName} onChange={setContactField("lastName")} />
+        </div>
+      </div>
+
+      <div>
+        <label className={labelCls} htmlFor="bk-email">Email</label>
+        <input id="bk-email" required type="email" autoComplete="email" placeholder="you@example.com"
+          className={fieldCls} value={contact.email} onChange={setContactField("email")} />
+      </div>
+
+      <div>
+        <label className={labelCls} htmlFor="bk-phone">
+          Phone <span className="normal-case tracking-normal">optional</span>
+        </label>
+        <input id="bk-phone" type="tel" autoComplete="tel" className={fieldCls}
+          value={contact.phone} onChange={setContactField("phone")} />
+      </div>
+
+      {maxParticipants > 1 && (
+        <div>
+          <label className={labelCls} htmlFor="bk-participants">Participants</label>
+          <input id="bk-participants" type="number" min={1} max={maxParticipants} value={participants}
+            onChange={(e) => setParticipants(Math.max(1, Math.min(maxParticipants, Number(e.target.value) || 1)))}
+            className={`${fieldCls} w-[100px]`} />
+        </div>
+      )}
+
+      {error && <p role="alert" className="m-0 text-destructive text-sm">{error}</p>}
+
+      {/* The business confirms a manual-approval service after the fact, so this asks rather than books. */}
+      <button type="submit" disabled={!canSubmit}
+        className="px-6 py-3 cursor-pointer bg-primary text-primary-foreground border-none rounded-sm text-[15px] font-semibold disabled:opacity-50 disabled:cursor-not-allowed">
+        {submitting
+          ? (needsApproval ? "Requesting…" : "Booking…")
+          : needsApproval
+            ? (what ? `Request ${what}` : "Request appointment")
+            : (what ? `Book ${what}` : "Book appointment")}
+      </button>
+    </form>
+  );
+}

package/skills/wix-vibe-headless/references/bookings/app/components/ServiceCard.jsx

@@ -0,0 +1,47 @@
+// Grid tile for one bookable service. Styled with base44 design tokens (shadcn Tailwind classes:
+// bg-card / text-foreground / border-border / text-primary) — re-skin via the app's design tokens
+// (src/index.css :root/.dark), not this JSX. Load-bearing: the image goes through mediaUrl() (Wix
+// media can be a bare handle), the link uses `service.id`, and every price/duration/capacity label
+// comes from lib/serviceFacts.js so the card and the detail page can't disagree.
+import { Link } from "react-router-dom";
+import { mediaUrl } from "@/rest/wix-bookings-services";
+import { serviceCapacityLabel, serviceDuration, servicePriceLabel } from "@/lib/serviceFacts";
+
+export default function ServiceCard({ service }) {
+  const image = mediaUrl(service.media?.mainMedia?.image ?? service.media?.items?.[0]?.image ?? service.media?.coverMedia?.image);
+  const price = servicePriceLabel(service);
+  const minutes = serviceDuration(service);
+  // A class has no duration on the service, so its meta row carries capacity alone rather than a gap.
+  const facts = [minutes && `${minutes} min`, serviceCapacityLabel(service)].filter(Boolean);
+
+  return (
+    <Link to={`/service/${service.id}`}
+      className="group flex flex-col no-underline text-foreground bg-card border border-border rounded-lg overflow-hidden shadow-sm">
+      <div className="relative aspect-[4/3] bg-background overflow-hidden">
+        {image
+          ? <img src={image} alt={service.name} loading="lazy"
+              className="w-full h-full object-cover transition-transform duration-300 md:group-hover:scale-[1.03]" />
+          : <div className="w-full h-full bg-muted flex items-center justify-center" aria-hidden="true"><svg viewBox="0 0 24 24" className="w-8 h-8 text-muted-foreground/40" fill="none" stroke="currentColor" strokeWidth="1.5"><rect x="3" y="3" width="18" height="18" rx="2" /><circle cx="8.5" cy="8.5" r="1.5" /><path d="m21 15-5-5L5 21" /></svg></div>}
+      </div>
+
+      <div className="p-3 flex flex-col gap-1">
+        {/* Name and price share a row on a wide tile and stack on a phone's narrow one, where a long
+            name against a top-right price wraps into a ragged block. */}
+        <div className="flex flex-col gap-1 md:flex-row md:items-baseline md:justify-between md:gap-3">
+          <h3 className="m-0 font-display text-[15px] font-semibold line-clamp-2">{service.name}</h3>
+          {price && <span className="font-semibold whitespace-nowrap">{price}</span>}
+        </div>
+
+        {service.tagLine && (
+          <p className="m-0 text-muted-foreground text-[13px] line-clamp-1">{service.tagLine}</p>
+        )}
+
+        {facts.length > 0 && (
+          <p className="m-0 mt-0.5 text-[11px] uppercase tracking-wide text-muted-foreground">
+            {facts.join(" · ")}
+          </p>
+        )}
+      </div>
+    </Link>
+  );
+}

package/skills/wix-vibe-headless/references/bookings/app/components/ServiceGrid.jsx

@@ -0,0 +1,13 @@
+// Responsive service grid + empty state. Styled with base44 design tokens (shadcn Tailwind classes).
+import ServiceCard from "./ServiceCard";
+
+export default function ServiceGrid({ services, empty = "No services yet." }) {
+  if (!services?.length) {
+    return <p className="text-muted-foreground p-4 text-center">{empty}</p>;
+  }
+  return (
+    <div className="grid gap-4 grid-cols-2 md:[grid-template-columns:repeat(auto-fill,minmax(240px,1fr))]">
+      {services.map((s) => <ServiceCard key={s.id} service={s} />)}
+    </div>
+  );
+}