@wix/agent-skills 1.20.0 → 1.20.1

package/skills/wix-headless-fast/references/bookings/rest/booking.ts

@@ -0,0 +1,113 @@
+// Availability, the booking form, and the createBooking → Cart V2 → checkout-or-place sequence over
+// REST — the twin of app/wix/bookings/booking.ts. Same exports, same DTOs; every body comes from
+// booking-core (the SAME file the SDK transport uses, deployed flat next to this one), so this file
+// is only the transport: literal paths, one fetch per step. Failures are loud: a taken slot, a
+// refused cart, a checkout that won't start all throw — surface the message to the visitor.
+// All calls run with the visitor token: the booking and its cart are the token's (see ./client).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-event-time-slots.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form-summary.md
+import { wixRequest } from "./client.js";
+import {
+  FALLBACK_FIELDS,
+  appointmentSlotsRequest,
+  bookingCartRequest,
+  bookingIdOf,
+  bookingRequest,
+  cartIdOf,
+  cartTotal,
+  checkoutRedirectRequest,
+  checkoutRequired,
+  classSlotsRequest,
+  confirmedResult,
+  defaultTimeZone,
+  toFormFields,
+  toLocalDateString,
+  toSlot,
+  type Raw,
+  type SlotsWindow,
+} from "./booking-core.js";
+import type { BookingFormField, BookingResult, ServiceDetail, Slot } from "./types.js";
+
+export { toLocalDateString };
+
+/**
+ * Bookable slots for a service in [from, from + days) — APPOINTMENT and CLASS use different APIs;
+ * this branches for you. Dates are local wall-clock; timeZone defaults to the visitor's.
+ * APPOINTMENT: POST /service-availability/v2/time-slots  { serviceId, fromLocalDate, toLocalDate, timeZone, bookable, cursorPaging, includeResourceTypeIds, resourceTypes? }
+ * CLASS:       POST /service-availability/v2/time-slots/event  { serviceIds, fromLocalDate, toLocalDate, timeZone, includeNonBookable, eventFilter? }
+ */
+export async function fetchSlots(service: Pick<ServiceDetail, "id" | "type">, window: SlotsWindow = {}): Promise<Slot[]> {
+  const res =
+    service.type === "CLASS"
+      ? await wixRequest<Raw>("/service-availability/v2/time-slots/event", { body: classSlotsRequest(service.id, window) })
+      : await wixRequest<Raw>("/service-availability/v2/time-slots", { body: appointmentSlotsRequest(service.id, window) });
+  return ((res?.timeSlots ?? []) as Raw[]).map(toSlot);
+}
+
+/**
+ * The service's booking-form fields, flat and render-ready (values keyed by `target`). ALWAYS a
+ * non-empty list — contact basics when the schema is missing/unusable — so the form renders
+ * unconditionally.  GET /form-schema-service/v4/forms/{formId}/summary (labels, types) and
+ * GET /form-schema-service/v4/forms/{formId} (which fields are required — the summary doesn't say).
+ */
+export async function fetchBookingForm(formId: string | null): Promise<BookingFormField[]> {
+  if (!formId) return FALLBACK_FIELDS;
+  try {
+    const id = encodeURIComponent(formId);
+    const [res, form] = await Promise.all([
+      wixRequest<Raw>(`/form-schema-service/v4/forms/${id}/summary`, { method: "GET" }),
+      wixRequest<Raw>(`/form-schema-service/v4/forms/${id}`, { method: "GET" }).catch(() => null),
+    ]);
+    return toFormFields(res?.formSummary, form?.form);
+  } catch {
+    return FALLBACK_FIELDS;
+  }
+}
+
+/**
+ * Book a slot: createBooking → createCart (holds the seat) → calculateCart → hosted checkout (paid)
+ * or placeOrder (free / pay-in-person). Call from the browser. `formValues` is the object your
+ * inputs wrote, keyed by field `target` — passed as the formSubmission DIRECTLY. Throws with the
+ * refusal (slot taken, invalid form) — surface it, don't swallow it. `origin` is the site's real
+ * https origin as registered on the OAuth app's allowed domains (browser: window.location.origin).
+ *   POST /bookings/v2/bookings            { booking, formSubmission }
+ *   POST /ecom/v2/carts                   { catalogItems: [{ quantity: 1, catalogReference: { catalogItemId: <bookingId>, appId } }], cart: { source: { channelType: "WEB" } } }
+ *   POST /ecom/v2/carts/{cartId}/calculate {}
+ *   POST /headless/v1/redirect-session    { ecomCheckout: { checkoutId: <cartId> }, callbacks: { postFlowUrl } }
+ *   POST /ecom/v2/carts/{cartId}/place-order {}
+ */
+export async function bookService(
+  service: ServiceDetail,
+  slot: Slot,
+  formValues: Record<string, unknown>,
+  {
+    staffId,
+    timeZone = defaultTimeZone(),
+    origin = typeof window !== "undefined" ? window.location.origin : "",
+  }: { staffId?: string; timeZone?: string; origin?: string } = {},
+): Promise<BookingResult> {
+  const created = await wixRequest<Raw>("/bookings/v2/bookings", {
+    body: { booking: bookingRequest(service, slot, { staffId, timeZone, idKey: "id" }), formSubmission: formValues },
+  });
+  const bookingId = bookingIdOf(created);
+  if (!bookingId) throw new Error("The booking couldn't be created — the slot may have just been taken.");
+
+  const newCart = await wixRequest<Raw>("/ecom/v2/carts", { body: bookingCartRequest(bookingId) });
+  const cartId = cartIdOf(newCart);
+  if (!cartId) throw new Error("The booking couldn't be reserved — please try again.");
+
+  const calc = await wixRequest<Raw>(`/ecom/v2/carts/${cartId}/calculate`, { body: {} });
+  if (checkoutRequired(service, cartTotal(calc))) {
+    const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: checkoutRedirectRequest(cartId, origin) });
+    const url = session?.redirectSession?.fullUrl;
+    if (!url) throw new Error("Checkout couldn't start — please try again.");
+    return { kind: "redirect", url };
+  }
+
+  const order = await wixRequest<Raw>(`/ecom/v2/carts/${cartId}/place-order`, { body: {} });
+  return confirmedResult(bookingId, order);
+}

package/skills/wix-headless-fast/references/bookings/rest/services.ts

@@ -0,0 +1,55 @@
+// Service reads over REST — the twin of app/wix/bookings/services.ts. Same exports, same DTOs; the
+// rules and mappers come from services-core (the SAME file the SDK transport uses, deployed flat
+// next to this one by deploy.mjs --stack static), so this file is only the transport: one fetch with
+// a literal body per function. Every call here is safe from a browser with a visitor token.
+// Porting: keep the paths, keep the bodies, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import {
+  BOOKINGS_APP_ID,
+  SERVICES_CONDITIONAL_FIELDS,
+  STAFF_RESOURCE_TYPE_ID,
+  isVisible,
+  servicesFilter,
+  toCategory,
+  toDetail,
+  toSummary,
+  type Raw,
+} from "./services-core.js";
+import type { BookingCategory, ServiceDetail, ServiceSummary } from "./types.js";
+
+export { BOOKINGS_APP_ID, STAFF_RESOURCE_TYPE_ID };
+
+// POST /bookings/v2/services/query  { query: { filter, paging: { limit } }, conditionalFields }
+async function queryServices(slug: string | undefined, limit: number): Promise<Raw[]> {
+  const res = await wixRequest<Raw>("/bookings/v2/services/query", {
+    body: { query: { filter: servicesFilter(slug), paging: { limit } }, conditionalFields: SERVICES_CONDITIONAL_FIELDS },
+  });
+  return (res?.services ?? []) as Raw[];
+}
+
+/** List bookable services (hidden ones filtered), mapped to grid-ready DTOs. */
+export async function fetchServices({ limit = 100 } = {}): Promise<ServiceSummary[]> {
+  return (await queryServices(undefined, limit)).filter(isVisible).map((s) => toSummary(s, imgSrc));
+}
+
+/** One service by its URL slug (mainSlug.name) — a query with the slug in the filter. Null when not found. */
+export async function fetchServiceBySlug(slug: string): Promise<ServiceDetail | null> {
+  const raw = (await queryServices(slug, 1))[0];
+  return raw ? toDetail(raw, imgSrc) : null;
+}
+
+/**
+ * Service categories for a filter bar — non-fatal (empty array on failure).
+ * POST /bookings/v2/categories/query  { query: {} }
+ */
+export async function fetchBookingCategories(): Promise<BookingCategory[]> {
+  try {
+    const res = await wixRequest<Raw>("/bookings/v2/categories/query", { body: { query: {} } });
+    return ((res?.categories ?? []) as Raw[]).map(toCategory).filter((c) => c.id);
+  } catch {
+    return [];
+  }
+}

package/skills/wix-headless-fast/references/bookings/seed/SEED.md

@@ -51,6 +51,16 @@ image leaves that service text-only.
 **Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
 seems needed.
 
+## Supplied content
+
+The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For bookings, each service the
+user lists is one entry. Its name becomes `name` and its length in minutes becomes `duration`. Its
+price becomes `price`; a service marked free, or with no price, gets `"free": true`. A group activity
+with a capacity or fixed times becomes a `CLASS` with `capacity` and one `sessions` entry per listed
+time; everything else is an `APPOINTMENT`. A category or group becomes `category`. Their photo
+becomes `imageUrl`. A service with no duration is a question for the user. Staff members and
+opening hours are not seeded — say so; the owner sets them in the dashboard.
+
 ## Escape hatch — individual functions
 `setupBookings` composes exported steps — `installBookingsApp`, `queryStaffWithRetry`,
 `createCategories`, `createServices`, `scheduleClassSessions`, `importImage`,

package/skills/wix-headless-fast/references/cms/INSTRUCTIONS.md

@@ -1,27 +1,36 @@
 # CMS — playbook
 
-The data machinery ships as files — typed reads/writes over ANY collection, hooks, and the
-normalization layer (dates → ISO strings, `wix:image://` → https URLs), correct end-to-end.
-CMS is schema-generic, so unlike other verticals there are **no fixed pages**: the seed plan
-(`plan.json`) is the site's content model, and **you design the pages from it** — a listing
-surface and an item page per content collection, plus the home page and the brand. You never
-write data-access logic; you never skip designing.
+The data machinery ships as files — typed reads/writes over ANY collection, the list and item
+state machines, their React bindings, and the normalization layer (dates → ISO strings,
+`wix:image://` → https URLs), correct end-to-end. CMS is schema-generic, so unlike other
+verticals there are **no fixed pages**: the seed plan (`plan.json`) is the site's content model,
+and **you design the pages from it** — a listing surface and an item page per content collection,
+plus the home page and the brand. You never write data-access logic; you never skip designing.
 
 ## The file map (deployed into `src/`)
 
-**Don't read the shipped files** — this table and the contracts below are everything you
-need. Open a shipped file's source only on a real fallback (runtime error / uncovered field).
+**On Astro and React the shipped files are tested and work as they are** — this table and the
+contracts below are everything you need to use them, so don't spend the run reading their source;
+wire them and build your surfaces. Reading them is the right move when something is off (a runtime
+error, a field this playbook doesn't cover) or when the brief wants a behaviour they don't offer —
+then read the file that owns it and change or extend it. On `lib`, `static`, and a port the hooks
+don't deploy at all; the stores behind them do, and each wiring section below says how to bind
+them. Files you edit: `SiteLayout.astro` and `styles/global.css`. Files you **create** (skeletons
+below): the listing and item pages with their islands, plus your home page.
 
 | file | what it is |
 |---|---|
-| `wix/config.ts` · `wix/sdk.ts` · `wix/media.ts` · `wix/money.ts` | shared auth seam + helpers (deploy configures; nothing to set) |
+| `wix/config.ts` · `wix/sdk.ts` | shared auth seam (deploy configures it — nothing to set by hand) |
+| `wix/media.ts` · `wix/money.ts` | `imgAttrs(url, sizes)` — every `<img>` attribute for a DTO image (`src`, `srcSet`, `sizes`, lazy): `<img {...imgAttrs(item.photo, "33vw")} alt={item.title} />`; `{}` for an absent image — render your placeholder then |
 | `wix/cms/types.ts` | the DTOs (`CmsItem`, `CmsFilter`, `CmsSort`, `CmsQuery`, `CmsPage`) — contracts below |
-| `wix/cms/items.ts` | `queryItems`, `getItemById`, `getItemBy`, `countItems`, `insertItem`, `updateItem`, `patchItemFields`, `removeItem` |
-| `hooks/cms/useCollection.ts` | list state + skip paging — contract below |
-| `hooks/cms/useItem.ts` | one item by `_id` or slug field — contract below |
+| `wix/cms/items.ts` | `queryItems`, `getItemById`, `getItemBy`, `countItems`, `insertItem`, `updateItem`, `patchItemFields`, `removeItem` — the transport; the rules and DTO mappers are in `items-core.ts` beside it (shared with the REST layer) |
+| `wix/cms/items-core.ts` | the normalization rules, the filter guard, the wire spelling of a query, and `formatDate(iso)` — a DATE field as copy ("" for absent/invalid, never "Invalid Date") |
+| `wix/cms/collection-store.ts` · `item-store.ts` | the list and item state machines, framework-free (`createCollectionStore()`, `createItemStore()` — `getState`/`subscribe` + actions, one instance per surface); the hooks below bind them to React, every other stack uses them directly |
+| `hooks/cms/useCollection.ts` | React binding of `collection-store.ts`: list state + skip paging — contract below |
+| `hooks/cms/useItem.ts` | React binding of `item-store.ts`: one item by `_id` or slug field — contract below |
 | `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
 
-There are **no shipped components** — the data layer and hooks are the machinery; every
+There are **no shipped components** — the data layer, stores, and hooks are the machinery; every
 component is yours.
 
 Astro stack additionally gets:
@@ -48,14 +57,33 @@ pages bind to (collection ids and field keys verbatim).
 Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
 Style everything with Tailwind utilities on the tokens.
 
+### What a complete content site shows (recommended defaults)
+
+Defaults for a brief that says nothing about them; the prompt wins where it differs. Look at the
+seeded content before designing (how many collections, which fields, whether items carry images
+and dates) and design for this content, not for a stereotype of the business.
+
+- **Home:** what the site is about and one path into the content in the first screen; real items
+  under truthful headings; not a repeat of a listing page.
+- **Listing:** a real card — image, title, a secondary field — in the first screen; each item a
+  link to its item page (`/<collection>/<slug>`); loading, empty, and error states that look
+  different; "load more" when `hasNext`.
+- **Item page:** title, image, the date formatted, the body as HTML, related items only when a
+  reference field carries them; a slug that resolves to nothing shows only the not-found state.
+- **Copy:** nothing the owner didn't supply — no invented fields, counts, or authors; no Wix IDs or
+  technical words in visible text.
+
 ### The contracts your components consume
 
+Everything you need — tested and working as they are; read a file when something is off or the
+brief wants more.
+
 ```ts
 // CmsItem — display-ready, fields FLAT on the item (never item.data.*):
 // { _id, _createdDate?, _updatedDate?, _owner?, ...fields }
 //   TEXT/URL/EMAIL → string · NUMBER → number · BOOLEAN → boolean
-//   DATE/DATETIME → ISO string (render: new Date(iso).toLocaleDateString())
-//   IMAGE → resolved https URL (straight into <img src>; guard the absent case)
+//   DATE/DATETIME → ISO string (render: formatDate(item.publishDate) from wix/cms/items-core)
+//   IMAGE → resolved https URL (<img {...imgAttrs(item.photo, "33vw")} />; {} when absent → your placeholder)
 //   RICH_TEXT → the stored HTML string (render via set:html on a wrapper you control)
 //   REFERENCE/MULTI_REFERENCE → id(s); full CmsItem(s) when queried with include
 
@@ -81,40 +109,185 @@ Style everything with Tailwind utilities on the tokens.
 // removeItem(collectionId, id)
 ```
 
+### The pages and islands you create — skeletons
+
+The class names in these skeletons are the Astro/React spelling of layout rules that hold on
+every stack, and each rule is also named in words beside its classes. On a stack where the hooks
+don't deploy (`lib`, `static`, a port), keep the rule and write it in your own CSS.
+
+Each page is a thin SSR shell (fetch → DTO props → island, or no island when the page has no
+interactivity); each island is a thin view over a hook. Hooks first, branches after. The islands
+render on the server too (`client:load` SSRs), and by then the 200 and headers are already sent — a
+render throw truncates the body mid-stream. Render every state totally; nothing in a render path may
+throw.
+
+```astro
+---
+// src/pages/recipes.astro — YOU create it (one per content collection). Items are fetched
+// SERVER-SIDE (view-source shows titles) and handed to the island as serialized DTO props.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import CollectionView from "../components/cms/CollectionView";
+import { queryItems } from "../wix/cms/items";
+import type { CmsPage } from "../wix/cms/types";
+const SORT = [{ field: "publishDate", direction: "desc" as const }];
+let page: CmsPage = { items: [], hasNext: false, total: null };
+try {
+  page = await queryItems("recipes", { sort: SORT, limit: 12 });
+} catch {
+  // Guarded: an unguarded SSR throw truncates the response mid-stream; the island renders your empty state.
+}
+---
+<SiteLayout title="Recipes">
+  <!-- your page heading / intro, then: -->
+  <CollectionView client:load collectionId="recipes" sort={SORT} limit={12} initialItems={page.items} initialHasNext={page.hasNext} />
+</SiteLayout>
+```
+
+```astro
+---
+// src/pages/recipes/[slug].astro — YOU create it. SEO is plain <title>/<meta name="description">
+// from the DTO via the layout props — CMS collections have NO owner-editable SEO item type, so
+// don't copy another vertical's wixMetadata/<SEO.Tags> wiring.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import { getItemBy } from "../../wix/cms/items";
+import { formatDate } from "../../wix/cms/items-core";
+import { imgAttrs } from "../../wix/media";
+let item = null;
+try {
+  item = await getItemBy("recipes", "slug", Astro.params.slug!, { include: ["categories"] });
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+// A missing slug is a real 404 — never a fallback to another item.
+if (!item) return new Response(null, { status: 404 });
+---
+<SiteLayout title={String(item.title)} description={String(item.summary ?? "")}>
+  <!-- your detail layout: title; the image through imgAttrs (a placeholder when it returns {});
+       formatDate(item.publishDate); the RICH_TEXT body with set:html on a wrapper you control;
+       included reference items by name — never an id as content -->
+</SiteLayout>
+```
+
+```tsx
+// src/components/cms/CollectionView.tsx — YOU build it; a listing page mounts it.
+import { useCollection } from "../../hooks/cms/useCollection";
+import { formatDate } from "../../wix/cms/items-core";
+import { imgAttrs } from "../../wix/media";
+import type { CmsFilter, CmsItem, CmsSort } from "../../wix/cms/types";
+
+export default function CollectionView(props: {
+  collectionId: string;
+  filters?: CmsFilter[];
+  sort?: CmsSort[];
+  limit?: number;
+  initialItems?: CmsItem[];     // SSR props from your page — pass straight to useCollection;
+  initialHasNext?: boolean;     // omitted in a SPA (client fetch)
+}) {
+  const { collectionId, ...options } = props;
+  const list = useCollection(collectionId, options);
+  // …you implement the render:
+  //   • error → a short inline message
+  //   • items === null → skeleton cards; [] → your honest empty state (no mock items)
+  //   • else YOUR grid of YOUR cards: image via <img {...imgAttrs(item.photo, "(min-width: 768px) 33vw, 100vw")} alt={String(item.title)} />
+  //     — src, srcSet, sizes and lazy loading in one spread; {} when the field is absent → your
+  //     placeholder; title WRAPS (`min-w-0`, `break-words`), no `truncate`; the date as
+  //     formatDate(item.publishDate); the card links to `/${collectionId}/${item.slug}`
+  //   • hasNext → your "load more" control calling loadMore() (disabled while loadingMore)
+}
+```
+
+### The reference files for stacks where the components don't deploy
+
+On `lib`, `static`, and a port, nothing under `hooks/` arrives, and CMS ships no components. The
+state machines behind the hooks do arrive — `wix/cms/collection-store.ts`, `item-store.ts` — so you
+never rewrite them: create a store per surface, `subscribe`, render from `getState()`, call its
+actions. Their `CollectionState` / `ItemState` interfaces are the render contract; read those. What
+you write is the rendering — cards, the item view, the states — to the skeletons above. The two
+hooks under `references/cms/app/hooks/cms/` are the binding pattern, ten lines each, if your
+framework's external-store primitive is unfamiliar.
+
 ### Wiring — Astro (default)
 
-1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass) and add one nav
-   link per content surface.
-2. Author your pages under `src/pages/` — SSR fetch in the frontmatter, DTO props to your
-   islands (`client:load`; a page with no interactivity needs no island at all). Listing:
-
-   ```astro
-   ---
-   import SiteLayout from "../layouts/SiteLayout.astro";
-   import { queryItems } from "../wix/cms/items";
-   import type { CmsPage } from "../wix/cms/types";
-   let page: CmsPage = { items: [], hasNext: false, total: null };
-   try {
-     page = await queryItems("recipes", { sort: [{ field: "publishDate", direction: "desc" }] });
-   } catch {
-     // an unguarded SSR throw truncates the response mid-stream
-   }
-   ---
-   ```
-
-   Item page (`src/pages/recipes/[slug].astro`): `getItemBy("recipes", "slug", Astro.params.slug!)`
-   in the frontmatter; `return new Response(null, { status: 404 })` on null. SEO is plain
-   `<title>`/`<meta name="description">` from the DTO via the layout props — CMS collections
-   have **no owner-editable SEO item type**, so don't copy another vertical's
-   `wixMetadata`/`<SEO.Tags>` wiring.
-3. **Author your surfaces in as few messages as possible** — batch multiple Writes per
-   message (components and pages are independent files).
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass) and add one nav link
+   per content surface.
+2. Author your pages under `src/pages/` per the skeletons above — SSR fetch in the frontmatter,
+   DTO props to your islands (`client:load`; a page with no interactivity needs no island at all).
+3. Write `pages/index.astro` (home) on `SiteLayout`.
+4. **Author your surfaces in as few messages as possible** — batch multiple Writes per message
+   (components and pages are independent files).
+
+### Wiring — another JS framework (`--stack lib`: Vue, Svelte, Solid, plain Vite)
+
+`deploy.mjs cms --stack lib` put the data layer in `src/wix/` and nothing else: `sdk.ts` (the
+visitor client, configured with the public client id), `media.ts`, `money.ts`, and `wix/cms/` —
+`items.ts`, `types.ts`, `items-core.ts`, and the two stores `collection-store.ts`, `item-store.ts`.
+None of it is React. The hooks don't ship on this stack; the stores replace them, and you write the
+components in your framework to the contracts on this page:
+
+- bind the stores with your framework's external-store primitive (Vue: `shallowRef` updated in
+  `subscribe`; Svelte: `readable(store.getState(), (set) => store.subscribe(() => set(store.getState())))`;
+  Solid: a signal set in `subscribe`). `createCollectionStore({ collectionId, filters?, sort?, limit?, include?, initialItems? })`
+  per listing (`start()` when mounted, `stop()` when unmounted, `setQuery()` when filters change,
+  `loadMore()`), `createItemStore({ collectionId, ref: { id } | { by }, initialItem? })` per item
+  surface. State in, actions out — exactly the hooks' contracts above.
+
+Routes `/<collection>`, `/<collection>/:slug` (via `getItemBy`, null → your 404); dev server on
+4321; a static build goes through `npx @wix/cli@latest release` with `site.outputDirectory`
+pointing at the build folder, an SSR build is hosted by you. Page tags from the item's own fields.
+
+### Wiring — static site (`--stack static`, no bundler)
+
+`deploy.mjs cms --stack static --out site` put the REST layer in `site/js/wix/` (browser ESM, the
+`.ts` beside each `.js` for reading). Everything the visitor loads lives under `site/` — pages,
+styles, `js/` — and `wix.config.json`'s `site.outputDirectory` is `"./site"`; the project root
+(config, plan, seed output) is never the upload. Same function names and DTOs as the table above,
+so the contracts on this page hold unchanged: `queryItems`, `getItemBy`, `getItemById`,
+`countItems` (and the writes) from `./js/wix/items.js`; `formatDate` from `./js/wix/items-core.js`;
+`imgAttrs` from `./js/wix/media.js`. The state machines ship too: `createCollectionStore` from
+`./js/wix/collection-store.js` (the listing — `start()` once the page is up, `loadMore()`,
+`setQuery()`), `createItemStore` from `./js/wix/item-store.js` (the item page — `notFound` is your
+404 state). No components ship — you write the rendering in plain JS: one render function per
+surface that reads `getState()`, called from `subscribe`, with the surface's controls calling the
+store's actions. Pages are `<collection>.html` and `item.html?collection=…&slug=…` (Wix static
+hosting serves files, not directories — name the file and link to it). Set `document.title` and
+the meta description from the item's fields once it loads. The visitor token persists in
+`localStorage` on its own; never mint per page. Reads work on any collection whose `read` is
+`ANYONE`; a write from the page succeeds only where the seed opened that verb (403 → a permissions
+step). `npx @wix/cli@latest release` uploads `site/`.
+
+### Wiring — server-rendered, another language (Flask, Laravel, Rails, …)
+
+Run `deploy.mjs cms --stack static` in the project folder anyway: `js/wix/` is both the
+browser-side code and the readable spec. Then split by where the call runs. **Reads on the
+server:** port `js/wix/items.ts` and `items-core.ts` to your language — `queryItems`, `getItemBy`,
+`getItemById`, `countItems` returning the same DTO shapes as dicts (the core's `toValue` rules:
+`{ "$date": iso }` → ISO string, `wix:image://` → the https URL form in `media.ts`), one anonymous
+visitor token per process for these public reads (mint and refresh per `client.ts`) — and render
+the listing and item pages in your templates to the contracts above, so titles are in the HTML;
+page tags from the item's fields. **Visitor writes in the browser** (a collection the seed opened
+to visitors or members): `insertItem` from `./js/wix/items.js` on the page, exactly as the static
+wiring above — the browser owns the visitor token, so the server handles no per-visitor tokens.
+Routes stay `/<collection>`, `/<collection>/<slug>`.
+
+**Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted.** Same port for the
+reads, run at build time with one anonymous token; the generator must emit every item page (walk
+`queryItems` by `skip` until `hasNext` is false — never only the first page). Run
+`deploy.mjs cms --stack static --out <build dir>` so `js/wix/` is inside the output the pages
+import from, point `site.outputDirectory` at that folder, `wix release`. Pages sit at different
+depths (`/`, `/<collection>/…`): give the templates one base path to `js/wix/` (a template
+variable, or root-relative `/js/wix/…`), never a relative `./js/wix/` — it breaks one level down.
+The frozen listing is the first paint; a filter or "load more" still runs client-side on it
+through `createCollectionStore()` from `./js/wix/collection-store.js`, exactly as on a static
+site. Close with the live URL, the rebuild + release command, and one line for the owner:
+dashboard edits to the content reach the site when that command runs.
 
 ### Wiring — React SPA (Vite etc.)
 
 Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite
 plugins — deploy added the dep). Routes are yours: a list route per collection on
-`useCollection`, a detail route on `useItem` with `by: { field: "slug", value }`.
+`useCollection`, a detail route on `useItem` with `by: { field: "slug", value }` (components
+fetch client-side when no `initialItems` / `initialItem` is passed). Deploy wrote the public
+client id into `wix/config.ts`; nothing else to configure.
 
 ## Hard rules
 
@@ -132,7 +305,8 @@ plugins — deploy added the dep). Routes are yours: a list route per collection
   or use `patchItemFields`. Date fields on any write are Date objects — a round-tripped ISO
   string is silently stored as text and breaks date queries.
 - **Writes 403 unless the collection was seeded with that verb open** — surface a 403 as a
-  permissions setup step (which permission, where in the dashboard), not a code bug.
+  permissions setup step (which permission, where in the dashboard), not a code bug. Anything
+  that needs elevated access runs server-side per `references/shared/CUSTOM_OPERATIONS.md`.
 - **User-created content is a CMS contribution flow.** For a member or visitor submission that
   the app must later list, use the seeded CMS collection and its intended permission preset.
   If the operation needs elevated access — especially a browser-created file that must enter
@@ -145,17 +319,31 @@ plugins — deploy added the dep). Routes are yours: a list route per collection
   returned Wix Media reference. Do not author another upload endpoint for that flow.
 - **RICH_TEXT is HTML, not plain text** — render it with `set:html` (Astro) /
   `dangerouslySetInnerHTML` (React) on a wrapper; never interpolate it as text.
+- **Dates through `formatDate`**, images through `imgAttrs` — the DTO's ISO string and https URL
+  are data, not copy.
 - Reference fields hold ids unless the query passed `include` — don't render an id as
   content.
-- Guard absent IMAGE fields — render a fallback, never an empty/broken `<img>`.
-- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+- Guard absent IMAGE fields — `imgAttrs` returns `{}`; render a fallback, never an empty/broken `<img>`.
+- **Page at the source, not on a loaded list.** `hasNext`/`loadMore()` fetch the next page from
+  Wix; never raise the page limit instead of paging, never filter or sort client-side a page you
+  already hold — pass `filters`/`sort` and let Wix apply them across the collection.
+- **Call every hook before any conditional return.** An island that returns early for
+  `notFound`/loading above its hooks changes hook order between renders and React throws.
+- Where the shipped code deploys with Tailwind (Astro, React): theme via the `@theme` tokens, your
+  markup on the same tokens; no parallel theme files, no hardcoded palettes. Where it doesn't
+  (`lib`, `static`, a port): style with whatever your stack does well, on one token set of your
+  own; the rule that survives is the token set, not Tailwind.
 - Live data or an honest empty state — never mock items or invent fields not in the plan.
 
 ## Point the user to their dashboard
 
-Give the owner the dashboard link — the deploy step's JSON printed `dashboardUrl`; append
-`/wix-cms` for the collections area (items, fields, and More Actions → Permissions &
-Privacy live there).
+Hand the owner these links — `{siteId}` is `siteId` in `wix.config.json` (the deploy JSON prints it as
+`dashboardUrl`); a collection id is its `_id` (the seed result lists them).
+
+| page | `https://manage.wix.com/dashboard/{siteId}/` + |
+|---|---|
+| Collections | `wix-cms` |
+| A collection's items (fields, and More Actions → Permissions & Privacy) | `wix-cms/data/{collectionId}` |
 
 ## Seeding
 
@@ -163,17 +351,3 @@ Per `seed/SEED.md` — plain-data `plan.json` into `seed-cms.mjs` from the proje
 plan is the content model your pages bind to: design collections that exercise the UI
 (a `slug` field per detail page, an IMAGE field with a verified `imageUrl` per item, a DATE
 field when the content is chronological).
-
-## Verify (before declaring done)
-
-- [ ] Each listing page renders live items SSR (view-source shows titles) through YOUR
-      components; an empty collection shows your honest empty state (no mock items).
-- [ ] Item pages resolve by slug with a real 404 on a bad slug.
-- [ ] Images render (resolved https URLs, no raw `wix:image://`); absent images fall back
-      gracefully.
-- [ ] Dates render formatted (no "Invalid Date", no raw ISO strings in copy).
-- [ ] RICH_TEXT renders formatted (no visible HTML tags, no `[object Object]`).
-- [ ] Any 403 surfaced as a permissions step with the dashboard link.
-- [ ] Listing/item/home surfaces are YOUR designs on the tokens; data-layer/hook files
-      unedited.
-- [ ] Dashboard link handed to the owner.

package/skills/wix-headless-fast/references/cms/app/hooks/cms/useCollection.ts

@@ -1,9 +1,11 @@
-// One collection as list state. SSR-friendly: pass server-fetched items as `initialItems`
-// (Astro frontmatter / server component) and no client fetch happens for the first page; a
-// SPA passes nothing. Changing filters/sort (by value) refetches; loadMore() appends the
-// next page (skip paging).
-import { useCallback, useEffect, useRef, useState } from "react";
-import { queryItems } from "../../wix/cms/items";
+// React binding of the collection store (wix/cms/collection-store.ts) — the list state machine
+// lives there, framework-free; this hook subscribes to one instance per mounted listing. SSR-friendly:
+// pass server-fetched items as `initialItems` (Astro frontmatter / server component) and no client
+// fetch happens for the first page; a SPA passes nothing. Changing filters/sort (by value) refetches;
+// loadMore() appends the next page (skip paging). Astro islands and React SPAs use this; a static
+// page, Vue, or Svelte uses the store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createCollectionStore, type CollectionStore } from "../../wix/cms/collection-store";
 import type { CmsFilter, CmsItem, CmsSort } from "../../wix/cms/types";
 
 export interface UseCollectionOptions {
@@ -30,54 +32,19 @@ export interface UseCollection {
 
 export function useCollection(collectionId: string, options: UseCollectionOptions = {}): UseCollection {
   const { filters, sort, limit = 20, include, initialItems, initialHasNext } = options;
+  const ref = useRef<CollectionStore | null>(null);
+  if (!ref.current) ref.current = createCollectionStore({ collectionId, filters, sort, limit, include, initialItems, initialHasNext });
+  const store = ref.current;
   // Query identity by value — Dates in filters serialize to ISO, so this is stable.
   const key = JSON.stringify([collectionId, filters ?? null, sort ?? null, limit, include ?? null]);
-  const initialKey = useRef<string | null>(initialItems ? key : null);
-  const [items, setItems] = useState<CmsItem[] | null>(initialItems ?? null);
-  const [hasNext, setHasNext] = useState<boolean>(
-    initialHasNext ?? (initialItems ? initialItems.length >= limit : false),
-  );
-  const [loadingMore, setLoadingMore] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const itemsRef = useRef<CmsItem[] | null>(items);
-  itemsRef.current = items;
-
   useEffect(() => {
-    if (initialKey.current === key) return; // the SSR pass already answered this exact query
-    initialKey.current = null;
-    let alive = true;
-    setItems(null);
-    setError(null);
-    queryItems(collectionId, { filters, sort, limit, include })
-      .then((page) => {
-        if (!alive) return;
-        setItems(page.items);
-        setHasNext(page.hasNext);
-      })
-      .catch((e) => {
-        if (!alive) return;
-        setItems([]);
-        setError(e instanceof Error ? e.message : String(e));
-      });
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [key]);
-
-  const loadMore = useCallback(() => {
-    const current = itemsRef.current;
-    if (!current || loadingMore) return;
-    setLoadingMore(true);
-    queryItems(collectionId, { filters, sort, limit, include, skip: current.length })
-      .then((page) => {
-        setItems([...(itemsRef.current ?? []), ...page.items]);
-        setHasNext(page.hasNext);
-      })
-      .catch((e) => setError(e instanceof Error ? e.message : String(e)))
-      .finally(() => setLoadingMore(false));
+    store.setQuery({ collectionId, filters, sort, limit, include });
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [key, loadingMore]);
-
-  return { items, hasNext, loadMore, loadingMore, error };
+  }, [store, key]);
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { items: state.items, hasNext: state.hasNext, loadMore: store.loadMore, loadingMore: state.loadingMore, error: state.error };
 }