@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/events/app/hooks/events/useEventRegistration.ts

@@ -0,0 +1,40 @@
+// React binding of the registration store (wix/events/registration-store.ts) — the whole
+// registration state machine for one event lives there, framework-free, branched on
+// event.registrationType: TICKETING loads the tier picker (per-tier or per-option quantities, a
+// named price on donation tiers, Wix's running totals) and checkout() reserves → redirects to
+// Wix's hosted checkout; RSVP renders the organizer's form and submits it in place. All
+// correctness (the visitor-public tier read, the reservation payload, the redirect callbacks,
+// rsvpV2, the form body) lives in the data layer; you own how it looks. One store per event — a
+// new event id gets a fresh one.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createRegistrationStore,
+  type RegistrationState,
+  type RegistrationStore,
+} from "../../wix/events/registration-store";
+import type { EventDetail } from "../../wix/events/types";
+
+export type UseEventRegistration = RegistrationState &
+  Pick<RegistrationStore, "setQuantity" | "setGuestPrice" | "setRsvpValue" | "setGuestCount" | "setGuestName" | "checkout" | "rsvp">;
+
+export function useEventRegistration(event: EventDetail): UseEventRegistration {
+  const key = `${event.id}:${event.registrationType}`;
+  const ref = useRef<{ key: string; store: RegistrationStore } | null>(null);
+  if (!ref.current || ref.current.key !== key) ref.current = { key, store: createRegistrationStore(event) };
+  const store = ref.current.store;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return {
+    ...state,
+    setQuantity: store.setQuantity,
+    setGuestPrice: store.setGuestPrice,
+    setRsvpValue: store.setRsvpValue,
+    setGuestCount: store.setGuestCount,
+    setGuestName: store.setGuestName,
+    checkout: store.checkout,
+    rsvp: store.rsvp,
+  };
+}

package/skills/wix-headless-templates/events/app/hooks/events/useEvents.ts

@@ -0,0 +1,24 @@
+// React binding of the events store (wix/events/events-store.ts) — the listing state machine
+// lives there, framework-free; this hook subscribes to one instance per mounted listing and
+// exposes its state and actions under one name. SSR-friendly: pass server-fetched data as
+// `initialEvents` (+ `initialTotal` from fetchEventsPage, so "load more" knows there is more) and
+// no client fetch happens; a SPA passes nothing. Astro islands and React SPAs use this; a static
+// page, Vue, or Svelte uses the store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createEventsStore, type EventsState, type EventsStore, type EventsStoreOptions } from "../../wix/events/events-store";
+
+export type UseEventsOptions = EventsStoreOptions;
+
+export type UseEvents = EventsState & Pick<EventsStore, "setActiveCategoryId" | "loadMore">;
+
+export function useEvents(options: UseEventsOptions = {}): UseEvents {
+  const ref = useRef<EventsStore | null>(null);
+  if (!ref.current) ref.current = createEventsStore(options);
+  const store = ref.current;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { ...state, setActiveCategoryId: store.setActiveCategoryId, loadMore: store.loadMore };
+}

package/skills/wix-headless-templates/events/app/wix/events/events-core.ts

@@ -0,0 +1,379 @@
+// Event rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./events.ts (the
+// SDK, managed Astro and React) and the REST twin in templates/events/rest/events.ts (fetch, a
+// static site or a port to another language). Every rule about statuses, fieldsets, prices,
+// dates, images, categories, and the organizer's RSVP form lives HERE, once. A raw event may come
+// from the SDK (`_id`, mainImage as a wix:image string, Date objects) or from REST (`id`, mainImage
+// as { id, url }, ISO strings); the mappers accept both. Imports are type-only so a strip to JS
+// emits no imports.
+import type {
+  EventCategory,
+  EventDetail,
+  EventStatus,
+  EventSummary,
+  RegistrationStatus,
+  RegistrationType,
+  RsvpForm,
+  RsvpFormControl,
+  RsvpFormInput,
+  TaxSettings,
+} from "./types";
+
+/** A raw Events V3 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** The Wix Events app id (reference only — frontend calls need no app-id constant). */
+export const EVENTS_APP_ID = "140603ad-af8d-84a5-2c80-a0f60cb47351";
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+// Fieldsets are opt-in: without REGISTRATION there's no registration type to branch on;
+// without CATEGORIES the category names never arrive; DETAILS carries the formatted date
+// and mainImage; TEXTS carries the long description; URLS the Wix event page url; FORM the
+// organizer's RSVP form (createRsvp validates submissions against it).
+export const LIST_FIELDS = ["DETAILS", "REGISTRATION", "CATEGORIES"] as const;
+export const DETAIL_FIELDS = ["DETAILS", "TEXTS", "REGISTRATION", "URLS", "CATEGORIES", "FORM"] as const;
+
+/** Default listing: only these are registerable. `past` is ENDED; `all` is the three (never CANCELED/DRAFT). */
+export const LIVE_STATUSES = ["UPCOMING", "STARTED"] as const;
+export const PAST_STATUSES = ["ENDED"] as const;
+export type StatusFilter = "upcoming" | "past" | "all";
+export function statusesFor(status: StatusFilter = "upcoming"): EventStatus[] {
+  if (status === "past") return [...PAST_STATUSES];
+  if (status === "all") return [...LIVE_STATUSES, ...PAST_STATUSES];
+  return [...LIVE_STATUSES];
+}
+
+export const START_DATE_FIELD = "dateAndTimeSettings.startDate";
+/** The stable secondary sort. The SDK spells it `_createdDate` and renames on the wire; REST is `createdDate`. */
+export const CREATED_DATE_FIELD_SDK = "_createdDate";
+export const CREATED_DATE_FIELD_REST = "createdDate";
+/** Server-side category filter field. SDK `categories._id` → REST `categories.id` (the same rename). */
+export const CATEGORY_ID_FIELD_SDK = "categories._id";
+export const CATEGORY_ID_FIELD_REST = "categories.id";
+/** Wix's page size; a listing loads more pages on demand. */
+export const DEFAULT_PAGE_SIZE = 20;
+
+export interface ListOptions {
+  /** Page size, 1..1000 (default 20). */
+  limit?: number;
+  /** Items to skip (default 0). */
+  offset?: number;
+  /** Server-side filter to one category (a manual category or a recurring series' id). */
+  categoryId?: string;
+  status?: StatusFilter;
+}
+
+/**
+ * The Query Events body for the listing in REST spelling: statuses, soonest first then newest
+ * first, a positive limit, an offset. `paging.limit` defaults to 0 — a bare query answers
+ * `total: N, events: []` with no error — so the limit is always sent. The SDK builder spells
+ * the same parts with `_createdDate` / `categories._id`.
+ */
+export function listQuery({ limit = DEFAULT_PAGE_SIZE, offset = 0, categoryId, status }: ListOptions = {}): Raw {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) throw new Error("limit must be between 1 and 1000.");
+  if (!Number.isInteger(offset) || offset < 0) throw new Error("offset must be a non-negative integer.");
+  const filter: Raw = { status: { $in: statusesFor(status) } };
+  if (categoryId) filter[CATEGORY_ID_FIELD_REST] = { $in: [categoryId] };
+  return {
+    filter,
+    sort: [
+      { fieldName: START_DATE_FIELD, order: "ASC" },
+      { fieldName: CREATED_DATE_FIELD_REST, order: "DESC" },
+    ],
+    paging: { limit, offset },
+  };
+}
+
+/** Query Categories body: only MANUAL categories (AUTO / RECURRING_EVENT / HIDDEN never become pills). */
+export const CATEGORY_STATES = ["MANUAL"] as const;
+export function categoriesQuery(): Raw {
+  return { filter: { states: { $hasSome: [...CATEGORY_STATES] } }, paging: { limit: 100 } };
+}
+
+/** How many more pages: a page is the last when offset + page length reaches the total. */
+export function hasMorePages(loaded: number, total: number | undefined | null): boolean {
+  return typeof total === "number" && loaded < total;
+}
+
+/**
+ * Format a decimal amount in a currency with the visitor's locale — the one money formatter for
+ * this vertical. No currency → the bare amount (never a made-up "$"). "" when there is no value.
+ */
+export function formatAmount(value: string | number | null | undefined, currency: string | null | undefined): string {
+  if (value == null || value === "") return "";
+  const n = Number(value);
+  if (!Number.isFinite(n)) return String(value);
+  if (!currency) return n.toFixed(2);
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(n);
+  } catch {
+    return `${n.toFixed(2)} ${currency}`;
+  }
+}
+
+/** A Wix Money `{ value, amount (deprecated), currency }` → formatted string (value read before the deprecated amount). */
+export function formatMoney(money: Raw | null | undefined): string {
+  if (!money) return "";
+  return formatAmount(money.value ?? money.amount, money.currency);
+}
+
+/** Any date the API hands back (Date on the SDK, ISO string on REST) → ISO string, "" when absent/invalid. */
+export function isoOf(value: unknown): string {
+  if (!value) return "";
+  const d = new Date(value as string);
+  return Number.isNaN(d.getTime()) ? "" : d.toISOString();
+}
+
+/**
+ * A moment formatted in the EVENT's time zone (medium date + short time) — sale periods,
+ * registration openings. The browser's zone is wrong for a venue event; a missing/invalid zone
+ * falls back to the visitor's.
+ */
+export function formatInZone(value: unknown, timeZoneId: string | null | undefined): string {
+  const iso = isoOf(value);
+  if (!iso) return "";
+  const d = new Date(iso);
+  const opts: Intl.DateTimeFormatOptions = { dateStyle: "medium", timeStyle: "short" };
+  try {
+    return new Intl.DateTimeFormat(undefined, timeZoneId ? { ...opts, timeZone: timeZoneId } : opts).format(d);
+  } catch {
+    return new Intl.DateTimeFormat(undefined, opts).format(d);
+  }
+}
+
+/** "From €45" (ticketed), "Free" (RSVP / free tickets), "" when nothing applies. */
+export function lowestPriceLabel(reg: Raw): string {
+  const type = reg.type ?? reg.initialType;
+  if (type === "RSVP") return "Free";
+  if (type !== "TICKETING") return "";
+  const lowest: Raw | undefined = reg.tickets?.lowestPrice;
+  if (!lowest) return "";
+  if (Number(lowest.value ?? lowest.amount ?? 0) === 0) return "Free";
+  const formatted = lowest.formattedValue || formatMoney(lowest);
+  return formatted ? `From ${formatted}` : "";
+}
+
+// event.description is Ricos rich content ({ nodes: [...] }), NOT a string — calling string
+// methods on it crashes the page. Extract plain paragraphs; detailedDescription (legacy plain
+// text) is the fallback. A description of one empty PARAGRAPH node (what the dashboard saves
+// for "no description") yields [] here, matching Wix's hasDescription() rule.
+export function toParagraphs(rich: Raw | undefined | null, legacy: string | undefined): string[] {
+  const collect = (nodes: Raw[] | undefined): string =>
+    (nodes ?? [])
+      .map((n: Raw) => (typeof n.textData?.text === "string" ? n.textData.text : collect(n.nodes)))
+      .join("");
+  const out: string[] = [];
+  for (const node of rich?.nodes ?? []) {
+    const text = collect([node]).trim();
+    if (text) out.push(text);
+  }
+  if (!out.length && legacy) out.push(legacy);
+  return out;
+}
+
+/**
+ * The main image in the form imgSrc scales: the SDK carries it as a `wix:image://` string; REST
+ * as `{ id, url, altText }` — rebuilt into the id form so both transports resolve one URL shape.
+ */
+export function mainImageOf(raw: Raw): unknown {
+  const m = raw.mainImage;
+  if (m && typeof m === "object" && typeof m.id === "string" && m.id) {
+    return `wix:image://v1/${m.id}/${encodeURIComponent(String(m.altText || "image"))}`;
+  }
+  return m;
+}
+
+/** A category entity (Categories API or the event's CATEGORIES fieldset) → pill DTO. */
+export function toCategory(raw: Raw): EventCategory {
+  return { id: rawId(raw), name: raw.name ?? "" };
+}
+
+/**
+ * The event's assigned categories that are real, visitor-facing groupings: the CATEGORIES
+ * fieldset also lists the RECURRING_EVENT category every series gets and hidden ones — neither
+ * is a filter pill. (`type` and `hidden` per the SDK's EventCategory.)
+ */
+export function manualCategories(raw: Raw): EventCategory[] {
+  return ((raw.categories?.categories ?? []) as Raw[])
+    .filter((c) => c.type !== "RECURRING_EVENT" && c.hidden !== true)
+    .map(toCategory)
+    .filter((c) => c.id);
+}
+
+/** Categories from Query Categories, MANUAL only (the query already filters; this is the safety net). */
+export function toCategories(list: Raw[] | undefined): EventCategory[] {
+  return (list ?? [])
+    .filter((c) => !Array.isArray(c.states) || c.states.includes("MANUAL"))
+    .map(toCategory)
+    .filter((c) => c.id);
+}
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc): EventSummary {
+  const reg: Raw = raw.registration ?? {};
+  const dts: Raw = raw.dateAndTimeSettings ?? {};
+  const dateTbd = dts.dateAndTimeTbd === true;
+  const registrationType = (reg.type ?? reg.initialType ?? "NONE") as RegistrationType;
+  return {
+    id: rawId(raw), // _id on the SDK, id on REST — never a bare .id on the SDK (undefined there)
+    slug: raw.slug ?? "",
+    title: raw.title ?? "",
+    shortDescription: raw.shortDescription ?? "",
+    status: (raw.status ?? "UPCOMING") as EventStatus,
+    // Wix's server-formatted schedule (site locale, event zone); the organizer's TBD message when there is no date.
+    dateLabel: dateTbd ? dts.dateAndTimeTbdMessage || dts.formatted?.dateAndTime || "" : (dts.formatted?.dateAndTime ?? ""),
+    startDateIso: dateTbd ? "" : isoOf(dts.startDate),
+    endDateIso: dateTbd ? "" : isoOf(dts.endDate),
+    timeZoneId: dts.timeZoneId ?? "",
+    dateTbd,
+    dateTbdMessage: dts.dateAndTimeTbdMessage ?? "",
+    hideEndDate: dts.hideEndDate === true,
+    showTimeZone: dts.showTimeZone !== false,
+    locationName: raw.location?.name ?? "",
+    locationType: raw.location?.locationTbd
+      ? "TBD"
+      : ((raw.location?.type as "VENUE" | "ONLINE") ?? "TBD"),
+    imageUrl: imgSrc(mainImageOf(raw), 1200, 800),
+    // `type` is the current flavor (can become EXTERNAL later); initialType is the immutable
+    // seeded one — read type first.
+    registrationType,
+    priceLabel: lowestPriceLabel(reg),
+    // The API reports tickets.soldOut true on an RSVP event too (it has no tickets at all) — sold
+    // out is a ticketing signal only.
+    soldOut: registrationType === "TICKETING" && reg.tickets?.soldOut === true,
+    // `categories` is absent on the typed Event (an SDK type gap) — the Raw boundary reads
+    // the runtime field the CATEGORIES fieldset populates.
+    categories: manualCategories(raw),
+    recurrenceStatus: dts.recurrenceStatus ?? "ONE_TIME",
+    recurringCategoryId: dts.recurringEvents?.categoryId ?? "",
+  };
+}
+
+const INPUT_TYPES = new Set(["TEXT", "NUMBER", "TEXT_ARRAY", "DATE_TIME", "ADDRESS"]);
+
+function toFormInput(raw: Raw): RsvpFormInput {
+  const type = INPUT_TYPES.has(raw.type) ? raw.type : raw.array === true ? "TEXT_ARRAY" : "TEXT";
+  return {
+    name: raw.name ?? "",
+    label: raw.label ?? raw.name ?? "",
+    mandatory: raw.mandatory === true,
+    type,
+    options: Array.isArray(raw.options) ? raw.options.map(String) : [],
+    maxLength: Number(raw.maxLength) > 0 ? Number(raw.maxLength) : 0,
+  };
+}
+
+/**
+ * The organizer's RSVP form from the FORM fieldset. createRsvp validates `form.inputValues`
+ * against `form.controls[].inputs`: an unknown input name, a missing mandatory value (for a YES),
+ * or a value outside the predefined options is INVALID_FORM_RESPONSE — so the form is rendered
+ * from this, never hardcoded. Deleted controls are skipped; controls keep `orderIndex` order.
+ * GUEST_CONTROL is lifted out: its answer travels as `additionalGuestDetails`, not as an input
+ * value (the Create RSVP contract). Its max is read from the count input's numeric options, else
+ * the names input's `maxSize`.
+ */
+export function toRsvpForm(form: Raw | undefined | null): RsvpForm | null {
+  if (!form || !Array.isArray(form.controls)) return null;
+  const live = (form.controls as Raw[])
+    .filter((c) => c.deleted !== true)
+    .slice()
+    .sort((a, b) => (a.orderIndex ?? 0) - (b.orderIndex ?? 0));
+  const controls: RsvpFormControl[] = [];
+  let guestControl: RsvpForm["guestControl"] = null;
+  for (const c of live) {
+    const inputs = ((c.inputs ?? []) as Raw[]).map(toFormInput).filter((i) => i.name);
+    if (c.type === "GUEST_CONTROL") {
+      const count = inputs.find((i) => i.type === "NUMBER") ?? inputs[0];
+      const names = inputs.find((i) => i.type === "TEXT_ARRAY");
+      const numeric = (count?.options ?? []).map(Number).filter((n) => Number.isFinite(n));
+      const fromOptions = numeric.length ? Math.max(...numeric) : 0;
+      const rawNames = ((c.inputs ?? []) as Raw[]).find((i) => i.type === "TEXT_ARRAY" || i.array === true);
+      const maxGuests = fromOptions || Number(rawNames?.maxSize ?? 0) || 0;
+      guestControl = { label: count?.label ?? "Guests", maxGuests, namesLabel: names?.label ?? "Guest names" };
+      continue;
+    }
+    controls.push({ id: rawId(c) || c.name || `${controls.length}`, type: c.type ?? "INPUT", system: c.system === true, inputs });
+  }
+  return { controls, guestControl };
+}
+
+/** `registration.tickets.taxSettings` → DTO (null when the organizer configured no tax). */
+export function toTaxSettings(ts: Raw | undefined | null): TaxSettings | null {
+  if (!ts || !ts.type) return null;
+  const rate = Number(ts.rate);
+  return {
+    name: ts.name ?? "Tax",
+    ratePercent: Number.isFinite(rate) ? rate : 0,
+    includedInPrice: ts.type === "INCLUDED_IN_PRICE",
+    appliedToDonations: ts.appliedToDonations === true,
+  };
+}
+
+/** The venue's one-line address: Wix's `formatted` (a runtime field), else the parts joined. */
+export function formattedAddress(address: Raw | undefined | null): string {
+  if (!address) return "";
+  if (typeof address.formatted === "string" && address.formatted) return address.formatted;
+  if (typeof address.formattedAddress === "string" && address.formattedAddress) return address.formattedAddress;
+  return [address.addressLine1 ?? address.addressLine, address.addressLine2, address.city, address.subdivision, address.postalCode, address.country]
+    .filter((p) => typeof p === "string" && p.trim())
+    .join(", ");
+}
+
+/** Coordinates when Wix geocoded the venue (`address.location` on events; `geocode` on ticket definitions). */
+export function coordinatesOf(address: Raw | undefined | null): { lat: number; lng: number } | null {
+  const geo: Raw | undefined = address?.location ?? address?.geocode;
+  const lat = Number(geo?.latitude);
+  const lng = Number(geo?.longitude);
+  return Number.isFinite(lat) && Number.isFinite(lng) && (lat !== 0 || lng !== 0) ? { lat, lng } : null;
+}
+
+/** A Wix PageUrl: the SDK hands a string; REST hands `{ base, path }` (joined the way the SDK does). */
+export function pageUrlOf(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  const v = value as Raw;
+  if (typeof v.base !== "string") return "";
+  const base = /^https?:\/\//.test(v.base) ? v.base : `https://${v.base}`;
+  return `${base}${v.path ?? ""}`;
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): EventDetail {
+  const summary = toSummary(raw, imgSrc);
+  const reg: Raw = raw.registration ?? {};
+  const status = (typeof reg.status === "string" ? reg.status : "UNKNOWN_REGISTRATION_STATUS") as RegistrationStatus;
+  const paused = reg.registrationPaused === true || reg.registrationDisabled === true;
+  const opensAt = status === "SCHEDULED_RSVP" ? isoOf(reg.rsvp?.startDate) : "";
+  const formatted: Raw = raw.dateAndTimeSettings?.formatted ?? {};
+  const limit = Number(reg.tickets?.ticketLimitPerOrder);
+  return {
+    ...summary,
+    aboutParagraphs: toParagraphs(raw.description, raw.detailedDescription),
+    formatted: {
+      startDate: formatted.startDate ?? "",
+      startTime: formatted.startTime ?? "",
+      endDate: formatted.endDate ?? "",
+      endTime: formatted.endTime ?? "",
+    },
+    address: summary.locationType === "VENUE" ? formattedAddress(raw.location?.address) : "",
+    coordinates: summary.locationType === "VENUE" ? coordinatesOf(raw.location?.address) : null,
+    registrationStatus: status,
+    // Wix: closed is exactly the two CLOSED_* statuses. Open = an OPEN_* status the organizer hasn't paused;
+    // SCHEDULED_RSVP is neither (it opens at rsvp.startDate).
+    registrationOpen: status.startsWith("OPEN_") && !paused && summary.registrationType !== "NONE",
+    registrationClosed: status === "CLOSED_MANUALLY" || status === "CLOSED_AUTOMATICALLY",
+    registrationOpensAtIso: opensAt,
+    registrationOpensAtLabel: formatInZone(opensAt, summary.timeZoneId),
+    registrationPaused: paused && status.startsWith("OPEN_"),
+    waitlistOnly: status === "OPEN_RSVP_WAITLIST_ONLY",
+    membersOnly: reg.allowedGuestTypes === "MEMBER",
+    rsvpResponseType: reg.rsvp?.responseType === "YES_AND_NO" ? "YES_AND_NO" : "YES_ONLY",
+    rsvpForm: summary.registrationType === "RSVP" ? toRsvpForm(raw.form) : null,
+    externalUrl: reg.external?.url ?? "",
+    eventPageUrl: pageUrlOf(raw.eventPageUrl),
+    addToCalendar: { google: raw.calendarUrls?.google ?? "", ics: raw.calendarUrls?.ics ?? "" },
+    taxSettings: toTaxSettings(reg.tickets?.taxSettings),
+    // Wix default 20, max 50 — the reservation rejects a larger order with an opaque error.
+    ticketLimitPerOrder: Number.isInteger(limit) && limit > 0 ? Math.min(limit, 50) : 20,
+  };
+}

package/skills/wix-headless-templates/events/app/wix/events/events-store.ts

@@ -0,0 +1,175 @@
+// The events listing as a framework-free store — the logic behind useEvents, usable from React
+// (useEvents wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. State, actions, subscribe/getState, emit after
+// every change.
+//
+// SSR-friendly: seed with `initialEvents` (+ `initialTotal` from fetchEventsPage) and they render
+// at once with no client fetch; a SPA passes nothing and `start()` fetches the first page. Pages
+// are Wix's 20; `loadMore()` appends the next. The category pills are the site's MANUAL categories
+// (Query Categories on the visitor token, as Wix's listing does); when that read is refused for
+// this site's visitor scope the pills fall back to the manual categories on the loaded events.
+// Filtering by category is client-side while the whole list is loaded, server-side (a refetch)
+// once there are more pages than loaded — so a filter never hides events on unloaded pages.
+//
+// One store per mounted listing (a page can hold the index and a "next up" rail):
+// createEventsStore(), not a singleton.
+import { fetchCategories, fetchEventsPage } from "./events";
+import { DEFAULT_PAGE_SIZE, type StatusFilter } from "./events-core";
+import type { EventCategory, EventSummary } from "./types";
+
+export interface EventsStoreOptions {
+  /** Server-fetched first page (Astro frontmatter) — renders at once, no client fetch. */
+  initialEvents?: EventSummary[];
+  /** Matching events overall (from fetchEventsPage) — enables "load more"; absent → the list is complete. */
+  initialTotal?: number;
+  /** Page size (default 20). */
+  pageSize?: number;
+  /** "upcoming" (default) lists UPCOMING/STARTED; "past" ENDED; "all" both. A past event is never registerable. */
+  status?: StatusFilter;
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface EventsState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  events: EventSummary[] | null;
+  /** Manual categories — render a filter bar only when > 1. */
+  categories: EventCategory[];
+  activeCategoryId: string | null;
+  /** More pages exist for the current filter — render a "load more" control on this. */
+  hasMore: boolean;
+  /** A page (or a refetch for a category) is loading; the current `events` stay rendered. */
+  loadingMore: boolean;
+  error: string | null;
+}
+
+export interface EventsStore {
+  getState(): EventsState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the first page when no `initialEvents` were given, and the categories. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop a late response. */
+  stop(): void;
+  /** Filter to one category (null = all). Client-side while everything is loaded, else a server-side refetch. */
+  setActiveCategoryId(id: string | null): void;
+  /** Append the next page for the current filter. No-op while loading or when `hasMore` is false. */
+  loadMore(): Promise<void>;
+}
+
+export function createEventsStore({ initialEvents, initialTotal, pageSize = DEFAULT_PAGE_SIZE, status }: EventsStoreOptions = {}): EventsStore {
+  // `all` is the unfiltered list; `filtered` is the server-filtered list for the active category (null = not in use).
+  let all: EventSummary[] | null = initialEvents ?? null;
+  let allTotal: number = initialTotal ?? initialEvents?.length ?? 0;
+  let filtered: EventSummary[] | null = null;
+  let filteredTotal = 0;
+  let fetchedCategories: EventCategory[] | null = null;
+  let activeCategoryId: string | null = null;
+  let loadingMore = false;
+  let error: string | null = null;
+  let started = false;
+  let generation = 0; // bumps on every filter change so a late page for an old filter is dropped
+  const listeners = new Set<() => void>();
+  let snapshot: EventsState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+  const message = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+  const allLoaded = () => all !== null && all.length >= allTotal;
+  const serverFiltering = () => activeCategoryId !== null && !allLoaded();
+
+  function derivedCategories(): EventCategory[] {
+    const seen = new Map<string, string>();
+    for (const e of all ?? []) for (const c of e.categories) if (!seen.has(c.id)) seen.set(c.id, c.name);
+    return [...seen.entries()].map(([id, name]) => ({ id, name }));
+  }
+
+  function getState(): EventsState {
+    if (snapshot) return snapshot;
+    const events = serverFiltering()
+      ? filtered
+      : all === null
+        ? null
+        : activeCategoryId
+          ? all.filter((e) => e.categories.some((c) => c.id === activeCategoryId))
+          : all;
+    // Never before the first page is in: a "load more" under skeletons would be a lie.
+    const hasMore = serverFiltering() ? filtered !== null && filtered.length < filteredTotal : activeCategoryId === null && all !== null && !allLoaded();
+    snapshot = {
+      events,
+      categories: fetchedCategories ?? derivedCategories(),
+      activeCategoryId,
+      hasMore,
+      loadingMore,
+      error,
+    };
+    return snapshot;
+  }
+
+  async function loadPage(categoryId: string | null, offset: number): Promise<void> {
+    const gen = generation;
+    loadingMore = true;
+    error = null;
+    emit();
+    try {
+      const page = await fetchEventsPage({ limit: pageSize, offset, categoryId: categoryId ?? undefined, status });
+      if (!started || gen !== generation) return;
+      if (categoryId === null) {
+        all = offset === 0 ? page.events : [...(all ?? []), ...page.events];
+        allTotal = page.total;
+      } else {
+        filtered = offset === 0 ? page.events : [...(filtered ?? []), ...page.events];
+        filteredTotal = page.total;
+      }
+    } catch (e) {
+      if (!started || gen !== generation) return;
+      if (categoryId === null && all === null) all = [];
+      if (categoryId !== null && filtered === null) filtered = [];
+      error = message(e);
+    } finally {
+      if (started && gen === generation) {
+        loadingMore = false;
+        emit();
+      }
+    }
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      // The visitor-scope category read — a refusal is not an error state, the pills derive from the events instead.
+      fetchCategories()
+        .then((list) => {
+          if (!started) return;
+          fetchedCategories = list;
+          emit();
+        })
+        .catch(() => {});
+      if (!initialEvents) void loadPage(null, 0);
+    },
+    stop() {
+      started = false;
+    },
+    setActiveCategoryId(id) {
+      if (id === activeCategoryId) return;
+      activeCategoryId = id;
+      generation++;
+      filtered = null;
+      filteredTotal = 0;
+      loadingMore = false;
+      emit();
+      if (serverFiltering()) void loadPage(id, 0);
+    },
+    async loadMore() {
+      if (loadingMore || !getState().hasMore) return;
+      if (serverFiltering()) await loadPage(activeCategoryId, (filtered ?? []).length);
+      else await loadPage(null, (all ?? []).length);
+    },
+  };
+}