@wix/agent-skills 1.7.0 → 1.8.0

package/skills/wix-headless/references/astro/stores/PRODUCT_PAGES.md

@@ -1,10 +1,10 @@
 # Phase 4 Product Pages — Stores
 
-Scope: `product-pages`. Launched in **Step 7** after designer page scopes have written placeholder `.astro` files. This scope rewrites the product listing, product detail, and ProductCard component with live `productsV3` queries.
+Scope: `product-pages` (the `pages-products` scope) — written by the stores **merged build agent** (the build wave) *after* its `components` and `pages-categories` scopes. This scope writes the product listing, product detail, and ProductCard component **once** — applying the designer's visual spec (`references/astro/designer/INSTRUCTIONS.md` → `store-pages`) together with live `productsV3` queries in a single pass. Read your seeded slice from `.wix/seeded.json` (`seeded.stores`).
 
 ## Scope
 
-Files this agent OWNS (rewrites from designer output):
+Files this agent OWNS (each written once, visual structure + live queries together):
 
 - `src/pages/products/index.astro` — product listing
 - `src/pages/products/[slug].astro` — product detail with `wixMetadata` + SEO tags
@@ -12,17 +12,17 @@ Files this agent OWNS (rewrites from designer output):
 
 Files this agent MUST NOT touch:
 - `src/components/ProductPurchase.tsx`, `src/components/AddToCartButton.tsx` — owned by `components`
-- `src/pages/cart.astro`, `src/pages/thank-you.astro` — owned by `pages-cart-checkout`
+- `src/pages/cart.astro`, `src/pages/thank-you.astro` — owned by `cart-checkout`
 - `src/pages/index.astro`, `src/components/Navigation.astro` — owned by `pages-home-and-nav`
-- `src/components/CategoryRail.astro` — owned by `pages-categories`. **Import** from `../../components/CategoryRail.astro`; never `Write` it. If it's not on disk yet when you go to mount it, that means the orchestrator dispatched scopes out of order — return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "src/components/CategoryRail.astro" }]` (never defensively `Write` it yourself — `pages-categories` is the only writer, and racing it trips the harness staleness guard).
-- `src/utils/categories.ts` — pre-copied by the orchestrator before Phase 4 (BUILD.md Step 7 pre-batch). **Import** `listStoreCategories`/etc. from `../../utils/categories`; never `Write` it.
+- `src/components/CategoryRail.astro` — owned by the `pages-categories` scope, which your merged agent writes **before** this one. **Import** from `../../components/CategoryRail.astro`; never `Write` it here. By the time you mount it, the `pages-categories` step has already put it on disk. If it's somehow absent, you wrote your scopes out of order — return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "src/components/CategoryRail.astro" }]` (write `pages-categories` before `pages-products`; never defensively `Write` it from this scope).
+- `src/utils/categories.ts` — pre-copied by the orchestrator in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"). **Import** `listStoreCategories`/etc. from `../../utils/categories`; never `Write` it.
 - `global.css`, any other `.astro` page, any other component — owned by designers
 
 ## Inputs (from parent prompt)
 
 - **Phase 1 return data** — `products: [{id, name, slug, variantId, price, inventory, sku}]` — use slugs when needed (rarely; `queryProducts` returns them already).
-- **Design tokens** — the full `designTokens` JSON is inlined in your prompt for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens (`class="py-4xl flex flex-col gap-md font-display"`) at the call site rather than inventing semantic classes for layout/spacing/typography. Retained global semantic classes are limited to compound patterns (`offer-callout`, `cart-summary`), interactive primitives (`btn-primary`, `product-card`), and JS targets — see `references/shared/STYLING.md`.
-- **Designer output summary** — paths of existing `products/index.astro`, `products/[slug].astro`, `ProductCard.astro` with placeholder data.
+- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk) for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens (`class="py-4xl flex flex-col gap-md font-display"`) at the call site rather than inventing semantic classes for layout/spacing/typography. Retained global semantic classes are limited to compound patterns (`offer-callout`, `cart-summary`), interactive primitives (`btn-primary`, `product-card`), and JS targets — see `references/shared/STYLING.md`.
+- **Designer visual spec** — the layout, contract classes, and decorative-slot conventions for `products/index.astro`, `products/[slug].astro`, `ProductCard.astro` (from `references/astro/designer/INSTRUCTIONS.md` → `store-pages`), applied in the same pass as the live queries.
 
 ## Critical rules (all must be honored)
 
@@ -68,9 +68,9 @@ Do NOT modify logic, imports, SDK calls, `wixMetadata` export, or prop-passing.
 
 Use template `templates/products/index.astro`.
 
-Preserves the designer's page structure (class names, layout) and replaces the placeholder products array with a guarded, **cursor-paginated** `productsV3.queryProducts({ fields: ["CURRENCY"] }).limit(24).skipTo(cursor).find()` (cursor read from `?cursor=` on the URL; Prev/Next anchors built from `result.cursors.next` / `.prev`). Mounts the shared `<CategoryRail/>` (written by `pages-categories`) above the grid, passing `activeSlug={null}` and the prev/next hrefs. Emits the `AddProductImpression` analytics event from a client-side script that reads a JSON payload serialized at SSR.
+Applies the designer's page structure (class names, layout) and binds a guarded, **cursor-paginated** `productsV3.queryProducts({ fields: ["CURRENCY"] }).limit(24).skipTo(cursor).find()` (cursor read from `?cursor=` on the URL; Prev/Next anchors built from `result.cursors.next` / `.prev`). Mounts the shared `<CategoryRail/>` (written by `pages-categories`) above the grid, passing `activeSlug={null}` and the prev/next hrefs. Emits the `AddProductImpression` analytics event from a client-side script that reads a JSON payload serialized at SSR.
 
-> **Imports written by `pages-categories`.** Both `<CategoryRail/>` and `listStoreCategories` come from files this scope must NOT write — they're owned by the `pages-categories` scope. Import paths: `../../components/CategoryRail.astro` and `../../utils/categories`. If either import fails to resolve, return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "<missing path>" }]` — that means the orchestrator dispatched scopes out of order.
+> **Imports you must NOT write.** `<CategoryRail/>` (`../../components/CategoryRail.astro`) is written by the `pages-categories` scope your merged agent runs *before* this one; `listStoreCategories` (`../../utils/categories`) is pre-copied by the orchestrator. Both are on disk by the time you mount them. If either fails to resolve, return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "<missing path>" }]` — that means your agent wrote `pages-products` before `pages-categories`, or the pre-copy was skipped.
 
 > **Page size 24** — multiple of the 2/3/4-column grid, well under Wix's per-request cap of 100. Do not change without updating `CATEGORY_PAGES.md` to match.
 

package/skills/wix-headless/references/astro/stores/SHARED_WIRING.md

@@ -1,8 +1,8 @@
 # Phase 3 Components — Stores (TSX/Astro)
 
-Launched in **Step 4.5** (after Phase 2 Design System completes, parallel to any running designer page scopes). Writes code that depends on the **design tokens** but NOT on Phase 4 page markup. Finishes before the Phase 4 Pages scopes run in Step 7.
+This is the **components** portion of the stores **merged build agent** (the build wave — `BUILD-astro.md` § "Step 4.5"). Your agent writes these islands **first**, then the stores pages (`pages-categories`, `pages-products`) that mount them — so the islands are on disk before the page code references them. The code here depends on the **design tokens** (read from `.wix/design-tokens.css` on disk) but NOT on page markup.
 
-> **CSS lives in a sibling scope.** `src/styles/components-stores.css` is owned by the `components-css` scope (see `./COMPONENTS_CSS.md`), which runs concurrently with this one in the same Step 4.5 batch. This scope does NOT write the CSS file. Reference contract class names from the design tokens here; the CSS sibling defines the rules.
+> **CSS is pre-copied, not authored.** `src/styles/components-stores.css` ships from the skill template, copied by the orchestrator in the build-wave pre-batch (see `./COMPONENTS_CSS.md`). This scope does NOT write the CSS file. Reference its contract class names from the design tokens here; the pre-copied stylesheet defines the rules.
 
 ## Scope
 
@@ -17,14 +17,15 @@ Files this agent MUST NOT touch:
 - `src/styles/components-stores.css` — owned by the **`components-css`** sibling scope (see `./COMPONENTS_CSS.md`). Reference its class names; do not write the file.
 - `src/utils/wix-image.ts` — **shared utility shipped by the build skill.** Import `resolveWixImageUrl` from `../utils/wix-image`; do NOT write your own copy (would shadow the shared util and drop other verticals' callers). The canonical source lives at `<SKILL_ROOT>/shared-utilities/wix-image.ts`; it's copied into projects by `seed-utilities.sh` during Setup.
 - `src/components/CartView.tsx`, `src/components/CartBadge.tsx`, `src/utils/analytics.ts`, `src/styles/components-ecom.css` — owned by ecom
-- Any `.astro` page — those are designed and later rewritten by other scopes
+- `src/utils/back-in-stock.ts` — **pre-copied by the orchestrator** in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"), same as `categories.ts`. Import `getBackInStockEnabled`/the app-id constants from `../utils/back-in-stock`; never `Write` it (see `./BACK_IN_STOCK.md`).
+- Any `.astro` page — written by your agent's `pages-*` scopes (after the islands) or by another vertical
 - `src/styles/global.css` — owned by designer foundation
 - `src/layouts/Layout.astro` — owned by designer foundation (including the `components-stores.css` import line)
 - Any designed component (`ProductCard.astro`, `Navigation.astro`, etc.) — owned by designers
 
 ## Coordination: design tokens
 
-Your parent prompt includes the design tokens inline. Use it directly — do **not** read `.wix/design-tokens.css` + `.wix/site.d.ts` from disk and do not poll for it. The parent skill serializes your launch behind designer foundation specifically so the contract is already available in your prompt when you start.
+Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave). The parent skill serializes your launch behind the designer foundation specifically so this file is already written when you start.
 
 Reference the ACTUAL class names from the contract in React components (e.g. `className="add-to-cart-btn"`, not `className="addToCartButton"` or an invented name). See `references/shared/IMPLEMENTER.md` § "Contract class-name adaptation" for the full rule.
 

package/skills/wix-headless/references/astro/templates/Footer.astro

@@ -1,6 +1,6 @@
 ---
 // ── Composer skeleton: src/components/Footer.astro ────────────────────────────
-// Substitutions (see COMPOSE.md § "5. Footer.astro"):
+// Substitutions (see compose.mjs):
 //   {{brand.name}} — brand name for the wordmark + copyright.
 //   {{shell.footerTagline}} — short brand-voice tagline from data.shell.
 //   {{nav.links}} — same inlined Navigation links array (mirror/subset);

package/skills/wix-headless/references/astro/templates/Layout.astro

@@ -2,7 +2,7 @@
 // ── Composer skeleton: src/layouts/Layout.astro ──────────────────────────────
 // Fully replaces the scaffold's bare stub. The <script> below and the View
 // Transitions wiring are LITERAL fixed bulk — do not re-author. Composer's only
-// substitutions (see COMPOSE.md § "3. Layout.astro"):
+// substitutions (see compose.mjs):
 //   {{components-css-imports}} — one `import '../styles/components-<pack>.css';`
 //        per pack in "Packs with components" (omit entirely when none).
 //   {{fonts.googleHref}} — the Google Fonts <link> href built from designTokens

package/skills/wix-headless/references/astro/templates/Navigation.astro

@@ -1,6 +1,6 @@
 ---
 // ── Composer skeleton: src/components/Navigation.astro ────────────────────────
-// Substitutions (see COMPOSE.md § "4. Navigation.astro"):
+// Substitutions (see compose.mjs):
 //   {{shell.navBrandMark}} — brand mark / wordmark text from data.shell.
 //   {{nav.links}} — one <a href={href}>{label}</a> per entry in the inlined
 //        Navigation links array, labels VERBATIM (no editorial rebrands). Render

package/skills/wix-headless/references/astro/templates/astro.config.mjs

@@ -3,7 +3,7 @@
 // scaffold's generated astro.config.mjs varies (integrations args, image.domains,
 // vite.server settings differ run to run). Composer must NOT overwrite it with
 // this file — it applies exactly two mutations to the scaffold's own config and
-// preserves everything else (see COMPOSE.md § "2. astro.config.mjs"):
+// preserves everything else (see compose.mjs):
 //
 //   (1) register the Tailwind v4 Vite plugin   → vite.plugins: [tailwindcss()]
 //   (2) fix the bare `process.env` reference    → globalThis guard (TS-safe)

package/skills/wix-headless/references/astro/templates/bookings/AvailabilityCalendar.tsx

@@ -0,0 +1,218 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { createClient, OAuthStrategy } from "@wix/sdk";
+import { availabilityTimeSlots, eventTimeSlots, bookings } from "@wix/bookings";
+// Browser client ID comes from astro:env/client (NOT import.meta.env, which is
+// undefined in the browser bundle → OAuthStrategy posts an empty client_id and
+// oauth2/token 400s).
+import { WIX_CLIENT_ID } from "astro:env/client";
+
+// AvailabilityCalendar.tsx — client:only="react" island. Date navigator + slot
+// grid. Branches on serviceType:
+//   APPOINTMENT → availabilityTimeSlots.listAvailabilityTimeSlots() (1-on-1;
+//                 slots carry scheduleId + startDate).
+//   CLASS       → eventTimeSlots.listEventTimeSlots() (group sessions; slots
+//                 carry eventInfo.eventId + capacity; NO scheduleId).
+// Adapt styling/copy; keep the SDK wiring + slot normalization.
+
+export interface SelectedSlot {
+  serviceType: "APPOINTMENT" | "CLASS";
+  localStartDate: string;
+  localEndDate: string;
+  serviceId: string;
+  timezone: string;
+  // APPOINTMENT only:
+  scheduleId?: string;
+  locationId?: string;
+  locationType?: string;
+  // CLASS only:
+  eventId?: string;
+  totalCapacity?: number;
+  remainingCapacity?: number;
+  bookableCapacity?: number;
+  isFull?: boolean; // CLASS full → waitlist
+  // resolved on select (CLASS):
+  instructorName?: string;
+}
+
+interface Props {
+  serviceId: string;
+  serviceName: string;
+  serviceType: "APPOINTMENT" | "CLASS";
+  onSlotSelected: (slot: SelectedSlot) => void;
+}
+
+const wixClient = createClient({
+  modules: { availabilityTimeSlots, eventTimeSlots, bookings },
+  auth: OAuthStrategy({ clientId: WIX_CLIENT_ID }),
+});
+
+const pad = (n: number) => String(n).padStart(2, "0");
+// Local date string YYYY-MM-DDThh:mm:ss (no Z) — API expects local business time.
+const localDateString = (d: Date) =>
+  `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+const tz = () => Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+
+const fetchSlots = async (
+  serviceId: string,
+  serviceType: "APPOINTMENT" | "CLASS",
+  date: Date,
+): Promise<{ slots: SelectedSlot[]; timezone: string }> => {
+  const start = new Date(date); start.setHours(0, 0, 0, 0);
+  const end = new Date(date); end.setHours(23, 59, 59, 0);
+  const timeZone = tz();
+
+  if (serviceType === "CLASS") {
+    const result = await wixClient.eventTimeSlots.listEventTimeSlots({
+      serviceIds: [serviceId], // plural for the CLASS API
+      fromLocalDate: localDateString(start),
+      toLocalDate: localDateString(end),
+      timeZone,
+      includeNonBookable: true, // include full sessions → waitlist CTA
+      cursorPaging: { limit: 50 },
+    });
+    const z = result.timeZone ?? timeZone;
+    const slots: SelectedSlot[] = (result.timeSlots ?? []).map((s: any) => ({
+      serviceType: "CLASS",
+      serviceId,
+      localStartDate: s.localStartDate,
+      localEndDate: s.localEndDate,
+      eventId: s.eventInfo?.eventId, // session id — NO scheduleId on event slots
+      totalCapacity: s.totalCapacity ?? undefined,
+      remainingCapacity: s.remainingCapacity ?? undefined,
+      bookableCapacity: s.bookableCapacity ?? undefined,
+      isFull: (s.bookableCapacity ?? s.remainingCapacity ?? 0) <= 0,
+      timezone: z,
+    }));
+    return { slots, timezone: z };
+  }
+
+  // APPOINTMENT
+  const result = await wixClient.availabilityTimeSlots.listAvailabilityTimeSlots({
+    serviceId, // a single GUID STRING — NOT an array (the array form is the CLASS `serviceIds` field)
+    fromLocalDate: localDateString(start),
+    toLocalDate: localDateString(end),
+    timeZone,
+    bookable: true,
+    cursorPaging: { limit: 50 },
+  });
+  const z = result.timeZone ?? timeZone;
+  const slots: SelectedSlot[] = (result.timeSlots ?? []).map((s: any) => ({
+    serviceType: "APPOINTMENT",
+    serviceId,
+    localStartDate: s.localStartDate,
+    localEndDate: s.localEndDate,
+    scheduleId: s.scheduleId,
+    locationId: s.location?.id,
+    locationType: s.location?.locationType,
+    isFull: false,
+    timezone: z,
+  }));
+  return { slots, timezone: z };
+};
+
+// CLASS instructor lives on the event's resources, which the LIST call omits —
+// only getEventTimeSlot returns them. Resolve for the picked slot.
+const fetchInstructor = async (eventId: string): Promise<string | undefined> => {
+  try {
+    const { timeSlot } = await wixClient.eventTimeSlots.getEventTimeSlot(eventId);
+    const names = (timeSlot?.availableResources ?? [])
+      .flatMap((g: any) => g.resources ?? [])
+      .map((r: any) => r.name)
+      .filter(Boolean);
+    return names[0];
+  } catch {
+    return undefined;
+  }
+};
+
+const dayLabel = (d: Date) =>
+  d.toLocaleDateString([], { weekday: "long", month: "long", day: "numeric" });
+const timeLabel = (iso: string) =>
+  new Date(iso).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+const startOfToday = () => { const d = new Date(); d.setHours(0, 0, 0, 0); return d; };
+
+const capacityLabel = (s: SelectedSlot): string | null => {
+  if (s.serviceType !== "CLASS") return null;
+  const left = s.bookableCapacity ?? s.remainingCapacity ?? 0;
+  if (left <= 0) return "Full · join waitlist";
+  if (left <= 3) return `${left} spot${left === 1 ? "" : "s"} left`;
+  return `${left} spots`;
+};
+
+export default function AvailabilityCalendar({ serviceId, serviceName, serviceType, onSlotSelected }: Props) {
+  const [date, setDate] = useState<Date>(() => startOfToday());
+  const [slots, setSlots] = useState<SelectedSlot[]>([]);
+  const [status, setStatus] = useState<"loading" | "ready" | "error">("loading");
+  const [selectedKey, setSelectedKey] = useState<string | null>(null);
+  const today = useMemo(() => startOfToday(), []);
+  const atToday = date.getTime() <= today.getTime();
+
+  const load = useCallback(async (target: Date) => {
+    setStatus("loading"); setSelectedKey(null);
+    try {
+      const { slots: fetched } = await fetchSlots(serviceId, serviceType, target);
+      setSlots(fetched); setStatus("ready");
+    } catch (err) {
+      console.error("[availability] list failed:", err);
+      setStatus("error");
+    }
+  }, [serviceId, serviceType]);
+
+  useEffect(() => { void load(date); }, [date, load]);
+
+  const shiftDay = (delta: number) =>
+    setDate((prev) => { const n = new Date(prev); n.setDate(n.getDate() + delta); n.setHours(0, 0, 0, 0); return n; });
+
+  const keyOf = (s: SelectedSlot) => `${s.localStartDate}|${s.eventId ?? s.scheduleId ?? ""}`;
+
+  const handleSelect = async (s: SelectedSlot) => {
+    // Guard on the type-appropriate id — CLASS slots have no scheduleId.
+    const id = s.serviceType === "CLASS" ? s.eventId : s.scheduleId;
+    if (!s.localStartDate || !id) return;
+    setSelectedKey(keyOf(s));
+    const instructorName = s.serviceType === "CLASS" && s.eventId ? await fetchInstructor(s.eventId) : undefined;
+    onSlotSelected({ ...s, instructorName });
+  };
+
+  return (
+    <div className="availability-calendar">
+      <div className="availability-date-nav">
+        <button type="button" className="availability-nav-btn" onClick={() => shiftDay(-1)} disabled={atToday} aria-label="Previous day">← Prev</button>
+        <span className="availability-date-label">{dayLabel(date)}</span>
+        <button type="button" className="availability-nav-btn" onClick={() => shiftDay(1)} aria-label="Next day">Next →</button>
+      </div>
+
+      {status === "loading" && <p className="availability-loading">Checking availability…</p>}
+      {status === "error" && (
+        <>
+          <p className="availability-error">Could not load availability — please try again.</p>
+          <button type="button" className="availability-nav-btn" onClick={() => void load(date)}>Retry</button>
+        </>
+      )}
+      {status === "ready" && slots.length === 0 && (
+        <p className="availability-empty">No availability on this date — try another day.</p>
+      )}
+      {status === "ready" && slots.length > 0 && (
+        <div className="availability-slots" role="group" aria-label={`Available times for ${serviceName}`}>
+          {slots.map((s) => {
+            const key = keyOf(s);
+            const isSelected = key === selectedKey;
+            const cap = capacityLabel(s);
+            return (
+              <button
+                key={key}
+                type="button"
+                className={["time-slot", isSelected ? "time-slot--selected" : "time-slot--available", s.isFull ? "time-slot--full" : ""].filter(Boolean).join(" ")}
+                aria-pressed={isSelected}
+                onClick={() => void handleSelect(s)}
+              >
+                <span className="time-slot-time">{timeLabel(s.localStartDate)}</span>
+                {cap && <span className="time-slot-capacity">{cap}</span>}
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless/references/astro/templates/bookings/BookingForm.tsx

@@ -0,0 +1,194 @@
+import { useState } from "react";
+import { createClient, OAuthStrategy } from "@wix/sdk";
+import { bookings } from "@wix/bookings";
+import type { SelectedSlot } from "./AvailabilityCalendar";
+import { WIX_CLIENT_ID } from "astro:env/client"; // browser client ID, NOT import.meta.env
+
+// BookingForm.tsx — client:only="react" island. Renders after a slot is picked.
+// Flow: createBooking → CREATED holds NO seat, so POST the booking to
+// the elevated /api/confirm-booking to occupy it (and validate availability).
+// A full CLASS session throws SESSION_CAPACITY_EXCEEDED whose message carries the
+// v1 session id → register on the native waitlist via /api/waitlist.
+
+interface Props {
+  serviceId: string;
+  serviceName: string;
+  serviceType: "APPOINTMENT" | "CLASS";
+  slot: SelectedSlot;
+  onSuccess: (bookingId: string, startDate: string) => void;
+  onCancel: () => void;
+}
+
+const wixClient = createClient({
+  modules: { bookings },
+  auth: OAuthStrategy({ clientId: WIX_CLIENT_ID }),
+});
+
+const slotDisplay = (slot: SelectedSlot) =>
+  slot.localStartDate
+    ? new Date(slot.localStartDate).toLocaleString([], {
+        weekday: "long", month: "long", day: "numeric", hour: "2-digit", minute: "2-digit",
+      })
+    : "";
+
+export default function BookingForm({ serviceName, serviceType, slot, onSuccess, onCancel }: Props) {
+  const [firstName, setFirstName] = useState("");
+  const [lastName, setLastName] = useState("");
+  const [email, setEmail] = useState("");
+  const [phone, setPhone] = useState("");
+  const [participants, setParticipants] = useState(1);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [waitlisted, setWaitlisted] = useState(false);
+
+  const isWaitlist = serviceType === "CLASS" && !!slot.isFull;
+  // Party size only applies to CLASS (APPOINTMENT is 1-on-1).
+  const maxParty = serviceType === "CLASS" ? Math.max(1, slot.bookableCapacity ?? slot.remainingCapacity ?? 1) : 1;
+  const partyOptions = Array.from({ length: Math.min(maxParty, 8) }, (_, i) => i + 1);
+
+  const contactDetails = () => ({
+    firstName: firstName.trim(),
+    lastName: lastName.trim() || undefined,
+    email: email.trim(),
+    phone: phone.trim() || undefined,
+  });
+
+  const buildSlot = () =>
+    serviceType === "CLASS"
+      // CLASS: serviceId + eventId only — Wix derives the rest from the event.
+      ? { serviceId: slot.serviceId, eventId: slot.eventId }
+      // APPOINTMENT: scheduleId + explicit start/end/timezone/location.
+      : {
+          serviceId: slot.serviceId,
+          scheduleId: slot.scheduleId,
+          startDate: slot.localStartDate,
+          endDate: slot.localEndDate,
+          timezone: slot.timezone,
+          ...(slot.locationId
+            ? { location: { _id: slot.locationId, locationType: slot.locationType as any } }
+            : { location: { locationType: "OWNER_BUSINESS" as const } }),
+        };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError(null);
+    if (!firstName.trim() || !email.trim()) {
+      setError("Please enter your first name and email.");
+      return;
+    }
+    setSubmitting(true);
+    try {
+      const result = await wixClient.bookings.createBooking({
+        totalParticipants: participants, // party size
+        contactDetails: contactDetails(),
+        selectedPaymentOption: "OFFLINE" as const,
+        bookedEntity: { slot: buildSlot() },
+      } as any);
+
+      const status = result.booking?.status;
+      const bookingId = result.booking?._id ?? "";
+      const revision = result.booking?.revision ?? "";
+
+      // Defensive: if createBooking ever returns a WAITING_LIST booking directly,
+      // treat it as joined. In practice a full session THROWS
+      // SESSION_CAPACITY_EXCEEDED (handled in catch → /api/waitlist) rather than
+      // returning this status — both paths land the user on the waitlist.
+      if (status === "WAITING_LIST") { setWaitlisted(true); setSubmitting(false); return; }
+
+      // CREATED → confirm server-side to hold the seat.
+      const confirmRes = await fetch("/api/confirm-booking", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ bookingId, revision }),
+      });
+      const confirmJson = await confirmRes.json().catch(() => ({}));
+      if (!confirmRes.ok || confirmJson.ok === false) {
+        setError("This session just filled up — please pick another time.");
+        setSubmitting(false); onCancel(); return;
+      }
+      onSuccess(bookingId, slot.localStartDate);
+    } catch (err: any) {
+      console.error("[booking] createBooking/confirm failed:", err);
+      // Full CLASS session → native waitlist. The error carries the v1 session id.
+      const full = `${err?.message ?? ""} ${JSON.stringify(err?.details ?? {})} ${String(err)}`;
+      if (/SESSION_CAPACITY_EXCEEDED/i.test(full) || /no available spots/i.test(full)) {
+        const sessionId = full.match(/on session ([^\s"}]+)/)?.[1];
+        if (sessionId) {
+          try {
+            const res = await fetch("/api/waitlist", {
+              method: "POST", headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ sessionId, totalParticipants: participants, contactDetails: contactDetails() }),
+            });
+            const j = await res.json().catch(() => ({}));
+            if (res.ok && j.ok !== false) { setWaitlisted(true); setSubmitting(false); return; }
+          } catch (e) { console.error("[waitlist] failed:", e); }
+        }
+        setError("This class is full and we couldn't add you to the waitlist — please try again later.");
+        setSubmitting(false); return;
+      }
+      setError("This time slot was just taken. Please select another.");
+      setSubmitting(false); onCancel();
+    }
+  };
+
+  if (waitlisted) {
+    return (
+      <div className="booking-form">
+        <div className="booking-form-header">
+          <h3 className="booking-form-title">You're on the waitlist</h3>
+          <p className="booking-form-subtitle">{serviceName} · {slotDisplay(slot)}</p>
+        </div>
+        <p>We'll email <strong>{email.trim()}</strong> if a spot opens up.</p>
+        <button type="button" className="booking-cancel" onClick={onCancel}>← Back to available times</button>
+      </div>
+    );
+  }
+
+  return (
+    <form className="booking-form" onSubmit={handleSubmit}>
+      <div className="booking-form-header">
+        <h3 className="booking-form-title">{isWaitlist ? "Join the waitlist" : "Reserve your spot"}</h3>
+        <p className="booking-form-subtitle">
+          {serviceName} · {slotDisplay(slot)}{slot.instructorName ? ` · with ${slot.instructorName}` : ""}
+        </p>
+        {isWaitlist && <p className="booking-form-note">This session is full — join the waitlist and we'll notify you if a spot opens.</p>}
+      </div>
+
+      {error && <p className="booking-error">{error}</p>}
+
+      <div className="booking-field-row">
+        <div className="booking-field">
+          <label className="booking-label booking-label--required" htmlFor="bf-first">First name</label>
+          <input id="bf-first" className="booking-input" type="text" value={firstName} onChange={(e) => setFirstName(e.target.value)} required autoComplete="given-name" />
+        </div>
+        <div className="booking-field">
+          <label className="booking-label" htmlFor="bf-last">Last name</label>
+          <input id="bf-last" className="booking-input" type="text" value={lastName} onChange={(e) => setLastName(e.target.value)} autoComplete="family-name" />
+        </div>
+      </div>
+
+      <div className="booking-field">
+        <label className="booking-label booking-label--required" htmlFor="bf-email">Email</label>
+        <input id="bf-email" className="booking-input" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required autoComplete="email" />
+      </div>
+
+      <div className="booking-field">
+        <label className="booking-label" htmlFor="bf-phone">Phone</label>
+        <input id="bf-phone" className="booking-input" type="tel" value={phone} onChange={(e) => setPhone(e.target.value)} autoComplete="tel" />
+      </div>
+
+      {!isWaitlist && maxParty > 1 && (
+        <div className="booking-field">
+          <label className="booking-label" htmlFor="bf-party">Number of spots</label>
+          <select id="bf-party" className="booking-input" value={participants} onChange={(e) => setParticipants(Number(e.target.value))}>
+            {partyOptions.map((n) => <option key={n} value={n}>{n}</option>)}
+          </select>
+        </div>
+      )}
+
+      <button type="submit" className="booking-submit" disabled={submitting}>
+        {submitting ? (isWaitlist ? "Joining…" : "Confirming…") : isWaitlist ? "Join Waitlist" : "Confirm Booking"}
+      </button>
+      <button type="button" className="booking-cancel" onClick={onCancel} disabled={submitting}>← Back to available times</button>
+    </form>
+  );
+}

package/skills/wix-headless/references/astro/templates/bookings/ManageBooking.tsx

@@ -0,0 +1,84 @@
+import { useState } from "react";
+import { createClient, OAuthStrategy } from "@wix/sdk";
+import { bookings } from "@wix/bookings";
+import { WIX_CLIENT_ID } from "astro:env/client";
+
+// ManageBooking.tsx — client:only="react" island for /manage-booking.
+// The server (manage-booking.astro) already minted an anonymous action token
+// (app-elevated) and passed it in. The cancel call is a NO-AUTH anonymous method,
+// so the visitor client runs it directly with the token. Reschedule-in-place
+// needs a verified class V2Slot shape, so we offer cancel-and-rebook instead.
+
+interface Props {
+  token: string | null;
+  revision: string;
+  serviceName: string;
+  startDate: string | null;
+  status: string | null;
+  canCancel: boolean;
+  showSummary?: boolean; // false when embedded under a page that already shows the service/date
+}
+
+const wixClient = createClient({
+  modules: { bookings },
+  auth: OAuthStrategy({ clientId: WIX_CLIENT_ID }),
+});
+
+const fmt = (iso: string | null) => {
+  if (!iso) return null;
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime())
+    ? null
+    : d.toLocaleString([], { weekday: "long", month: "long", day: "numeric", hour: "2-digit", minute: "2-digit" });
+};
+
+export default function ManageBooking({ token, revision, serviceName, startDate, status, canCancel, showSummary }: Props) {
+  const [state, setState] = useState<"idle" | "canceling" | "canceled" | "error">(
+    status === "CANCELED" ? "canceled" : "idle",
+  );
+  const when = fmt(startDate);
+
+  const handleCancel = async () => {
+    if (!token) return;
+    setState("canceling");
+    try {
+      await wixClient.bookings.bookingsCancelBookingAnonymously(token, revision);
+      setState("canceled");
+    } catch (err) {
+      console.error("[manage-booking] cancel failed:", err);
+      setState("error");
+    }
+  };
+
+  if (state === "canceled") {
+    return (
+      <div className="manage-booking">
+        <p className="manage-booking-status">
+          Your booking for <strong>{serviceName}</strong>{when ? <> on <strong>{when}</strong></> : null} is canceled.
+        </p>
+        <a href="/services" className="booking-submit" style={{ display: "inline-block" }}>Book another service</a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="manage-booking">
+      {showSummary !== false && (
+        <p className="manage-booking-summary">
+          <strong>{serviceName}</strong>{when ? <> · {when}</> : null}
+        </p>
+      )}
+      {state === "error" && <p className="booking-error">Something went wrong canceling your booking. Please try again.</p>}
+      {canCancel ? (
+        <button type="button" className="booking-submit" onClick={handleCancel} disabled={state === "canceling"}>
+          {state === "canceling" ? "Canceling…" : "Cancel this booking"}
+        </button>
+      ) : (
+        <p className="manage-booking-note">This booking can no longer be canceled online.</p>
+      )}
+      <p className="manage-booking-note">
+        Need a different time? Cancel above, then <a href="/services" className="manage-booking-link">book another time</a>.
+      </p>
+    </div>
+  );
+}