@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/restaurants/project/src/components/restaurants/ReservationView.tsx

@@ -0,0 +1,212 @@
+// REFERENCE reservations surface: party/date/time query → AVAILABLE slot pills → hold (or, under
+// manual approval, a plain pick) → the details form built from the location's form configuration →
+// confirmed / pending, on the @theme tokens. Correct and complete; per the skill's model you design
+// and build your own on useReservation (which owns ALL booking logic).
+import { useReservation } from "../../hooks/restaurants/useReservation";
+import { zonedDateTimeLabel } from "../../wix/restaurants/time-core";
+
+const input =
+  "w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary";
+
+function Policy({ label, policy }: { label: string; policy: { url: string; text: string } }) {
+  return policy.url ? (
+    <a href={policy.url} target="_blank" rel="noreferrer" className="underline">{label}</a>
+  ) : (
+    <details className="inline-block">
+      <summary className="cursor-pointer underline">{label}</summary>
+      <p className="mt-1 whitespace-pre-wrap text-xs text-muted-foreground">{policy.text}</p>
+    </details>
+  );
+}
+
+export default function ReservationView() {
+  const r = useReservation();
+
+  if (r.locations === null) {
+    return <div className="h-64 animate-pulse rounded-lg bg-secondary" aria-busy="true" />;
+  }
+  if (r.locations.length === 0 || !r.location) {
+    return (
+      <p className="py-16 text-center text-muted-foreground">
+        Table reservations aren't set up yet — call us to book.
+      </p>
+    );
+  }
+  if (!r.location.onlineReservationsEnabled) {
+    // Premium-gated toggle is off — slots/booking would fail; be honest, don't fake a form.
+    return (
+      <p className="py-16 text-center text-muted-foreground">
+        Online reservations aren't open yet — call us to book a table.
+      </p>
+    );
+  }
+
+  if (r.confirmed) {
+    const { outcome } = r.confirmed;
+    return (
+      <div className="mx-auto max-w-md rounded-lg border border-border p-8 text-center">
+        <p className="text-lg font-semibold">
+          {outcome === "confirmed" ? "Table reserved" : outcome === "pending" ? "Request sent" : "Reservation not completed"}
+        </p>
+        <p className="mt-2 text-sm text-muted-foreground">
+          {outcome === "confirmed"
+            ? r.location.form.submitMessage || "See you soon — a confirmation is on its way."
+            : outcome === "pending"
+              ? "The restaurant will confirm your reservation shortly."
+              : `Status: ${r.confirmed.status.toLowerCase().replace(/_/g, " ")} — please call us.`}
+        </p>
+        <button
+          type="button"
+          onClick={r.reset}
+          className="mt-6 rounded-control border border-border px-5 py-2 text-sm font-medium hover:bg-secondary"
+        >
+          Make another reservation
+        </button>
+      </div>
+    );
+  }
+
+  const form = r.location.form;
+  const picked = r.selectedSlot;
+  const holdMinutes = r.holdSecondsLeft !== null ? `${Math.floor(r.holdSecondsLeft / 60)}:${String(r.holdSecondsLeft % 60).padStart(2, "0")}` : "";
+
+  return (
+    <div className="mx-auto max-w-xl">
+      {r.locations.length > 1 && (
+        <label className="mb-4 block text-sm">
+          <span className="text-muted-foreground">Location</span>
+          <select value={r.location.id} onChange={(e) => r.setLocationId(e.target.value)} className={`mt-1 ${input}`}>
+            {r.locations.map((l) => (
+              <option key={l.id} value={l.id}>{l.name || l.address || "Restaurant"}</option>
+            ))}
+          </select>
+        </label>
+      )}
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+        <label className="block text-sm">
+          <span className="text-muted-foreground">Guests</span>
+          <input
+            type="number"
+            min={r.location.partySizeMin}
+            max={r.location.partySizeMax}
+            value={r.partySize}
+            onChange={(e) => r.setPartySize(Number(e.target.value))}
+            className={`mt-1 ${input}`}
+          />
+        </label>
+        <label className="block text-sm">
+          <span className="text-muted-foreground">Date</span>
+          <input type="date" value={r.date} onChange={(e) => r.setDate(e.target.value)} className={`mt-1 ${input}`} />
+        </label>
+        <label className="block text-sm">
+          <span className="text-muted-foreground">Around</span>
+          <input type="time" value={r.time} onChange={(e) => r.setTime(e.target.value)} className={`mt-1 ${input}`} />
+        </label>
+      </div>
+      {r.approval === "MANUAL" && (
+        <p className="mt-2 text-xs text-muted-foreground">Reservations for this party size are confirmed by the restaurant.</p>
+      )}
+      <button
+        type="button"
+        disabled={r.loading}
+        onClick={() => void r.findSlots()}
+        className="mt-4 w-full rounded-control bg-primary py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+      >
+        {r.loading && r.slots === null ? "Finding times…" : "Find a table"}
+      </button>
+
+      {r.error && <p className="mt-4 text-sm text-destructive">{r.error}</p>}
+
+      {r.slots !== null && r.slots.length === 0 && !r.error && (
+        <p className="mt-6 text-center text-sm text-muted-foreground">
+          No tables around that time — try another time or party size.
+        </p>
+      )}
+
+      {r.slots !== null && r.slots.length > 0 && !picked && (
+        <div className="mt-6 flex flex-wrap gap-2" role="group" aria-label="Available times">
+          {r.slots.map((slot) => (
+            <button
+              key={slot.startIso}
+              type="button"
+              disabled={r.loading}
+              onClick={() => void r.holdSlot(slot)}
+              className="rounded-control border border-border px-4 py-1.5 text-sm font-medium transition-colors hover:bg-secondary disabled:opacity-40"
+            >
+              {slot.label}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {picked && (
+        <div className="mt-6 rounded-lg border border-border p-5">
+          <p className="text-sm font-medium">
+            {r.held ? "Holding" : "Requesting"} {zonedDateTimeLabel(new Date(picked.startIso), r.location.timeZone)} for {r.partySize}
+            {r.location.name ? ` at ${r.location.name}` : ""}
+            {r.held && holdMinutes ? ` — complete within ${holdMinutes}.` : r.held ? " — complete within 10 minutes." : "."}
+          </p>
+          <div className="mt-4 grid grid-cols-1 gap-3 sm:grid-cols-2">
+            <input
+              placeholder="First name *"
+              value={r.reservee.firstName}
+              onChange={(e) => r.setReserveeField("firstName", e.target.value)}
+              className={input}
+            />
+            <input
+              placeholder={form.lastNameRequired ? "Last name *" : "Last name"}
+              value={r.reservee.lastName ?? ""}
+              onChange={(e) => r.setReserveeField("lastName", e.target.value)}
+              className={input}
+            />
+            <input
+              placeholder="Phone (+15551234567) *"
+              type="tel"
+              value={r.reservee.phone}
+              onChange={(e) => r.setReserveeField("phone", e.target.value)}
+              className={input}
+            />
+            <input
+              placeholder={form.emailRequired ? "Email *" : "Email"}
+              type="email"
+              value={r.reservee.email ?? ""}
+              onChange={(e) => r.setReserveeField("email", e.target.value)}
+              className={input}
+            />
+            {form.customFields.map((f) => (
+              <input
+                key={f.id}
+                placeholder={f.required ? `${f.name} *` : f.name}
+                value={r.reservee.customFields?.[f.id] ?? ""}
+                onChange={(e) => r.setCustomField(f.id, e.target.value)}
+                className={`${input} sm:col-span-2`}
+              />
+            ))}
+          </div>
+          {form.marketingCheckbox && (
+            <label className="mt-3 flex items-center gap-2 text-sm">
+              <input type="checkbox" checked={r.reservee.marketingConsent === true} onChange={(e) => r.setMarketingConsent(e.target.checked)} />
+              Send me news and offers by email
+            </label>
+          )}
+          {(form.terms || form.privacy) && (
+            <p className="mt-3 text-xs text-muted-foreground">
+              By reserving you agree to our{" "}
+              {form.terms && <Policy label="terms and conditions" policy={form.terms} />}
+              {form.terms && form.privacy && " and "}
+              {form.privacy && <Policy label="privacy policy" policy={form.privacy} />}.
+            </p>
+          )}
+          <button
+            type="button"
+            disabled={!r.canConfirm}
+            onClick={() => void r.confirm()}
+            className="mt-4 w-full rounded-control bg-primary py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+          >
+            {r.loading ? "Sending…" : r.held ? "Complete reservation" : "Request reservation"}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-templates/restaurants/project/src/hooks/restaurants/useMenus.ts

@@ -0,0 +1,34 @@
+// React binding of the menu store (wix/restaurants/menu-store.ts) — menu browsing and switching
+// live there, framework-free; this hook subscribes to one instance per mounted surface. SSR-friendly:
+// pass server-fetched menus as `initialMenus` (Astro frontmatter) 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.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createMenuStore, type MenuStore } from "../../wix/restaurants/menu-store";
+import type { MenuData } from "../../wix/restaurants/types";
+
+export interface UseMenusOptions {
+  initialMenus?: MenuData[];
+}
+
+export interface UseMenus {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  menus: MenuData[] | null;
+  /** Defaults to the first menu once loaded. */
+  activeMenuId: string | null;
+  setActiveMenuId: (id: string) => void;
+  /** The menu to render (its sections/items are display-ordered). */
+  activeMenu: MenuData | null;
+  error: string | null;
+}
+
+export function useMenus({ initialMenus }: UseMenusOptions = {}): UseMenus {
+  const ref = useRef<MenuStore | null>(null);
+  if (!ref.current) ref.current = createMenuStore({ initialMenus });
+  const store = ref.current;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { ...state, setActiveMenuId: store.setActiveMenuId };
+}

package/skills/wix-headless-templates/restaurants/project/src/hooks/restaurants/useOrderCart.ts

@@ -0,0 +1,52 @@
+// React binding for the order-cart store. Works in any React root — Astro islands (several
+// on one page share the same store) and SPAs alike.
+import { useSyncExternalStore } from "react";
+import {
+  addOrderLine,
+  getOrderCartState,
+  goToOrderCheckout,
+  isMenuOrderable,
+  refreshOrderCart,
+  removeLineFromOrder,
+  setOrderCartOpen,
+  subscribeOrderCart,
+  updateOrderLineQuantity,
+  type OrderCartState,
+} from "../../wix/restaurants/order-store";
+import type { MenuItem, OrderSelection } from "../../wix/restaurants/types";
+
+const SERVER_STATE = getOrderCartState();
+
+export interface UseOrderCart extends OrderCartState {
+  itemCount: number;
+  /**
+   * Add a dish: the MenuItem DTO as rendered, the menu/section ids it is rendered under (the
+   * fetchMenus tree — never looked up again), the quantity, and the visitor's selection (from
+   * initialSelection(item) + toggleModifier; omit for a dish with nothing to choose).
+   */
+  addToOrder: (item: MenuItem, context: { menuId: string; sectionId: string }, quantity?: number, selection?: OrderSelection) => Promise<void>;
+  /** false → this menu takes no online orders right now (no add control); null while unknown. */
+  menuOrderable: (menuId: string) => boolean | null;
+  updateQuantity: (lineItemId: string, quantity: number) => Promise<void>;
+  removeLine: (lineItemId: string) => Promise<void>;
+  checkout: () => Promise<void>;
+  openCart: () => void;
+  closeCart: () => void;
+  refresh: () => Promise<void>;
+}
+
+export function useOrderCart(): UseOrderCart {
+  const state = useSyncExternalStore(subscribeOrderCart, getOrderCartState, () => SERVER_STATE);
+  return {
+    ...state,
+    itemCount: state.cart?.itemCount ?? 0,
+    addToOrder: addOrderLine,
+    menuOrderable: isMenuOrderable,
+    updateQuantity: updateOrderLineQuantity,
+    removeLine: removeLineFromOrder,
+    checkout: goToOrderCheckout,
+    openCart: () => setOrderCartOpen(true),
+    closeCart: () => setOrderCartOpen(false),
+    refresh: refreshOrderCart,
+  };
+}

package/skills/wix-headless-templates/restaurants/project/src/hooks/restaurants/useReservation.ts

@@ -0,0 +1,49 @@
+// React binding of the reservation store (wix/restaurants/reservation-store.ts) — the whole
+// table-reservation state machine lives there, framework-free: location, date + party size in the
+// location's timezone, AVAILABLE slots, the 10-minute hold with its countdown (automatic approval)
+// or the approval request (manual approval), the details form driven by the location's form
+// configuration, and confirm. All correctness lives in the data layer; you own how it looks.
+// Client-only: availability is time-specific, so render the surface with client:only="react" in Astro.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createReservationStore, type ReservationState, type ReservationStore } from "../../wix/restaurants/reservation-store";
+
+export type UseReservation = ReservationState &
+  Pick<
+    ReservationStore,
+    | "setLocationId"
+    | "setDate"
+    | "setTime"
+    | "setPartySize"
+    | "findSlots"
+    | "holdSlot"
+    | "setReserveeField"
+    | "setMarketingConsent"
+    | "setCustomField"
+    | "confirm"
+    | "reset"
+  >;
+
+export function useReservation(): UseReservation {
+  const ref = useRef<ReservationStore | null>(null);
+  if (!ref.current) ref.current = createReservationStore();
+  const store = ref.current;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return {
+    ...state,
+    setLocationId: store.setLocationId,
+    setDate: store.setDate,
+    setTime: store.setTime,
+    setPartySize: store.setPartySize,
+    findSlots: store.findSlots,
+    holdSlot: store.holdSlot,
+    setReserveeField: store.setReserveeField,
+    setMarketingConsent: store.setMarketingConsent,
+    setCustomField: store.setCustomField,
+    confirm: store.confirm,
+    reset: store.reset,
+  };
+}

package/skills/wix-headless-templates/restaurants/project/src/layouts/Layout.astro

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Wix Astro Basics</title>
+	</head>
+	<body>
+		<slot />
+	</body>
+</html>
+
+<style>
+	html,
+	body {
+		margin: 0;
+		width: 100%;
+		height: 100%;
+	}
+</style>

package/skills/wix-headless-templates/restaurants/project/src/layouts/SiteLayout.astro

@@ -0,0 +1,47 @@
+---
+// The site chrome for every restaurant page — THIS file (header/footer/nav) plus the @theme
+// token block in src/styles/global.css are what you brand. Keep the <slot name="seo-tags" />
+// in <head>, the global.css import, and one OrderCartButton in the header + one
+// OrderCartDrawer per page (both client:only — they read browser cart state and must not
+// server-render). (If another vertical is also deployed, its SiteLayout may have won; merge
+// the Menu/Reservations nav links and the order-cart mounts there instead.)
+import OrderCartButton from "../components/restaurants/OrderCartButton";
+import OrderCartDrawer from "../components/restaurants/OrderCartDrawer";
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <a href="/menu" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Menu</a>
+          <a href="/reservations" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Reservations</a>
+          <OrderCartButton client:only="react" />
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+    <OrderCartDrawer client:only="react" />
+  </body>
+</html>

package/skills/wix-headless-templates/restaurants/project/src/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import Hero from '../components/Hero.astro';
+import Layout from '../layouts/Layout.astro';
+---
+
+<Layout>
+	<Hero />
+</Layout>

package/skills/wix-headless-templates/restaurants/project/src/pages/menu.astro

@@ -0,0 +1,22 @@
+---
+// Menu page — the full menu tree fetched SERVER-SIDE (SEO: dish names in view-source) and
+// handed to the island as DTO props. Keep this frontmatter; swap the island import to YOUR
+// menu component. The island is client:load — add-to-order needs the browser.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import MenuView from "../components/restaurants/MenuView";
+import { fetchMenus } from "../wix/restaurants/menu";
+import type { MenuData } from "../wix/restaurants/types";
+
+let menus: MenuData[] = [];
+try {
+  menus = await fetchMenus();
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // empty state instead.
+}
+---
+
+<SiteLayout title="Menu">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Menu</h1>
+  <MenuView client:load initialMenus={menus} />
+</SiteLayout>

package/skills/wix-headless-templates/restaurants/project/src/pages/reservations.astro

@@ -0,0 +1,12 @@
+---
+// Reservations page. The surface is client:only — availability is timezone- and
+// party-specific, so nothing useful can server-render. Swap the island import to YOUR
+// reservation component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import ReservationView from "../components/restaurants/ReservationView";
+---
+
+<SiteLayout title="Reservations" description="Reserve a table">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Reserve a table</h1>
+  <ReservationView client:only="react" />
+</SiteLayout>

package/skills/wix-headless-templates/restaurants/project/src/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

package/skills/wix-headless-templates/restaurants/project/src/wix/config.ts

@@ -0,0 +1,16 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. deploy.mjs copies it from `.env.local`
+//                         (`WIX_CLIENT_ID`, what `wix env pull` writes): the CONTENT site's app — on a
+//                         migration preview the site being migrated, while wix.config.json names
+//                         only the deploy target.
+export const WIX_CLIENT_ID: string | null = null;
+
+// Kept for projects deployed before the Members vertical moved onto the shared seam; the shipped
+// members code no longer reads it (ambient Astro uses the built-in /api/auth routes, manual mode
+// uses the shared client above). deploy.mjs still fills it so older code keeps compiling.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

package/skills/wix-headless-templates/restaurants/project/src/wix/media.ts

@@ -0,0 +1,106 @@
+// Wix media resolution — define once, use on EVERY image render path. Copy as-is.
+//
+// SDK media fields come back either as an already-absolute https URL, or as a
+// `wix:image://v1/<hash>/<file>#originWidth=…` identifier that a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The wix:image:// form must go through the SDK media module;
+// never hand-build a static.wixstatic.com URL (wrong format → 403).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import { media } from "@wix/sdk";
+
+type MediaLike =
+  | string
+  | null
+  | undefined
+  | { image?: unknown; url?: string | null; id?: string | null };
+
+/** A bare Wix media file id (`e6a89e_06cf…~mv2.png`): what REST-shaped media objects carry as `url` and `id`. */
+const BARE_FILE_ID = /^[\w-]+~mv2\.[a-z0-9]+$/i;
+
+function rawOf(value: MediaLike): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (value.image != null && typeof value.image === "object") return rawOf(value.image as MediaLike); // { image: { id, url } }
+  return (typeof value.image === "string" ? value.image : null) ?? value.url ?? value.id ?? "";
+}
+
+/** Resolve any Wix media value to a browser-loadable URL ("" when absent). */
+export function imgSrc(value: MediaLike, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) {
+    return media.getScaledToFillImageUrl(v, width, height, {});
+  }
+  // A bare file id (what REST-shaped media objects carry) or an absolute Wix media URL (bare, or
+  // already carrying a /v1/fill/ segment at some other size): re-issue it through the scaler at the
+  // requested size, so every image path lands on one shape.
+  const file = BARE_FILE_ID.test(v) ? v : v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/)?.[1];
+  if (file) return `https://static.wixstatic.com/media/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  return v;
+}
+
+/**
+ * Responsive candidates for `srcset`: the same image at several widths through Wix's scaler, so a
+ * card never downloads a hero-sized file. Pair with `sizes`:
+ *   <img src={imgSrc(m, 640, 640)} srcSet={imgSrcSet(m)} sizes="(min-width: 1024px) 25vw, 50vw"
+ *        width={640} height={640} loading="lazy" alt={…} />
+ * Accepts every form an image reaches you in: a raw `wix:image://` id, an ALREADY-RESOLVED Wix URL
+ * (what the DTOs carry — `imageUrl`, `gallery[]`; its `/v1/fill/w_…,h_…` segment is rewritten per
+ * width), or any other https URL (returned as the single candidate). `ratio` is height/width
+ * (1 = square). "" only when there is no image at all — still set `src` as well.
+ */
+export function imgSrcSet(value: MediaLike, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const raw = rawOf(value);
+  if (!raw) return "";
+  if (raw.startsWith("wix:image://") || BARE_FILE_ID.test(raw)) {
+    return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  }
+  // A resolved Wix URL: …/v1/fill/w_800,h_800,al_c,… — swap the size for each width.
+  const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+  if (/static\.wixstatic\.com\//.test(raw) && FILL.test(raw)) {
+    return widths.map((w) => `${raw.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return raw; // one candidate, never an empty srcset for a real image
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcSet` without `src`:
+ *   <img {...imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw")} alt={p.name} />
+ * `sizes` is the width the image renders at (a CSS length or media-query list); `ratio` is
+ * height/width. Returns an empty object when there is no image — render your placeholder then.
+ */
+export function imgAttrs(value: MediaLike, sizes: string, ratio = 1): { src: string; srcSet: string; sizes: string; loading: "lazy"; decoding: "async" } | Record<string, never> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcSet: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/**
+ * Height/width of a Wix image when the value carries its size: a raw
+ * `wix:image://…#originWidth=W&originHeight=H` id (the natural size) or a resolved `/v1/fill/w_W,h_H/`
+ * URL (the size it was scaled to). null when neither is present. Pass it as `ratio` to keep a
+ * srcset at the image's own aspect instead of the square default:
+ *   <img {...imgAttrs(item.photo, "33vw", imgRatio(item.photo) ?? 1)} alt={…} />
+ */
+export function imgRatio(value: MediaLike): number | null {
+  const v = rawOf(value);
+  if (typeof v !== "string" || !v) return null;
+  const size = v.startsWith("wix:image://")
+    ? [v.match(/[#&]originWidth=(\d+)/)?.[1], v.match(/[#&]originHeight=(\d+)/)?.[1]]
+    : (v.match(/\/v1\/fill\/w_(\d+),h_(\d+)/)?.slice(1) ?? []);
+  const w = Number(size[0]);
+  const h = Number(size[1]);
+  return w > 0 && h > 0 ? h / w : null;
+}
+
+/**
+ * The identity of a media value BEFORE scaling — de-duplicate galleries on this, never on a
+ * resolved URL (two scaled URLs of one photo differ in their size parameters).
+ */
+export function mediaKey(value: MediaLike): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  // The file id, whichever form the value takes — a raw id and a resolved URL of one photo share it.
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : v;
+}