@wix/agent-skills 1.19.2 → 1.20.1

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

@@ -1,14 +1,12 @@
-// One item — by `_id` or by a field match (slug routing). SSR-friendly: pass the
-// server-fetched item as `initialItem` and no client fetch happens; a SPA passes nothing.
-import { useEffect, useState } from "react";
-import { getItemBy, getItemById } from "../../wix/cms/items";
+// React binding of the item store (wix/cms/item-store.ts) — one item by `_id` or by a field match
+// (slug routing), the loader lives there, framework-free. SSR-friendly: pass the server-fetched
+// item as `initialItem` and no client fetch happens; a SPA passes nothing.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createItemStore, type ItemRef, type ItemStore } from "../../wix/cms/item-store";
 import type { CmsItem } from "../../wix/cms/types";
 
 /** Exactly one of `id` / `by`. */
-export interface UseItemRef {
-  id?: string;
-  by?: { field: string; value: string | number };
-}
+export type UseItemRef = ItemRef;
 
 export interface UseItemOptions {
   initialItem?: CmsItem;
@@ -25,33 +23,15 @@ export interface UseItem {
 
 export function useItem(collectionId: string, ref: UseItemRef, options: UseItemOptions = {}): UseItem {
   const { initialItem, include } = options;
-  const [item, setItem] = useState<CmsItem | null>(initialItem ?? null);
-  const [notFound, setNotFound] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
+  // A new ref (another id or slug) is another item — a fresh store, as useProductDetail does per slug.
+  const key = JSON.stringify([collectionId, ref.id ?? null, ref.by?.field ?? null, ref.by?.value ?? null]);
+  const holder = useRef<{ key: string; store: ItemStore } | null>(null);
+  if (!holder.current || holder.current.key !== key) holder.current = { key, store: createItemStore({ collectionId, ref, initialItem, include }) };
+  const store = holder.current.store;
   useEffect(() => {
-    if (initialItem) return;
-    let alive = true;
-    const fetching = ref.id
-      ? getItemById(collectionId, ref.id, { include })
-      : ref.by
-        ? getItemBy(collectionId, ref.by.field, ref.by.value, { include })
-        : Promise.reject(new Error("useItem: pass ref.id or ref.by"));
-    fetching
-      .then((found) => {
-        if (!alive) return;
-        setItem(found);
-        setNotFound(found === null);
-      })
-      .catch((e) => {
-        if (!alive) return;
-        setError(e instanceof Error ? e.message : String(e));
-      });
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [collectionId, ref.id, ref.by?.field, ref.by?.value]);
-
-  return { item, notFound, error };
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { item: state.item, notFound: state.notFound, error: state.error };
 }

package/skills/wix-headless-fast/references/cms/app/wix/cms/collection-store.ts

@@ -0,0 +1,158 @@
+// One collection as list state, framework-free — the logic behind useCollection, usable from React
+// (useCollection wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe
+// and render), or as the specification for a port. Same shape as the storefront stores: state,
+// actions, subscribe/getState, emit after every change.
+//
+// The query (collection, filters, sort, page size, includes) is identified BY VALUE; a changed
+// query refetches from the first page, a late response from a superseded query is dropped.
+// loadMore() appends the next page (skip paging: skip = items shown so far).
+//
+// SSR-friendly: seed with `initialItems` from the SAME query and no client fetch happens for the
+// first page. One store per mounted listing (a page can hold two collections): createCollectionStore(),
+// not a singleton.
+import { queryItems } from "./items";
+import type { CmsFilter, CmsItem, CmsSort } from "./types";
+
+export interface CollectionQuery {
+  collectionId?: string;
+  filters?: CmsFilter[];
+  sort?: CmsSort[];
+  /** Page size (default 20). */
+  limit?: number;
+  /** Reference field keys to inline as full items. */
+  include?: string[];
+}
+
+export interface CollectionStoreOptions extends CollectionQuery {
+  collectionId: string;
+  /** Server-fetched first page — must come from the SAME query (filters/sort/limit/include). */
+  initialItems?: CmsItem[];
+  /** The server fetch's hasNext. Omitted → inferred (a full first page ⇒ assume more). */
+  initialHasNext?: boolean;
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface CollectionState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  items: CmsItem[] | null;
+  hasNext: boolean;
+  loadingMore: boolean;
+  error: string | null;
+  /** True while items is null and a load is running (the same condition, named). */
+  loading: boolean;
+}
+
+export interface CollectionStore {
+  getState(): CollectionState;
+  subscribe(listener: () => void): () => void;
+  /** Run the first query unless the seed already answered it. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  /** Change the query by value — same values keep the page, a change refetches from the first page. */
+  setQuery(query: CollectionQuery): void;
+  /** Append the next page (skip = items shown so far). No-op while loading or when there is none. */
+  loadMore(): Promise<void>;
+  /** Re-run the current query after an error. */
+  retry(): void;
+}
+
+const queryKey = (q: Required<Pick<CollectionQuery, "collectionId" | "limit">> & CollectionQuery): string =>
+  // Dates in filters serialize to ISO, so this is stable.
+  JSON.stringify([q.collectionId, q.filters ?? null, q.sort ?? null, q.limit, q.include ?? null]);
+
+export function createCollectionStore(options: CollectionStoreOptions): CollectionStore {
+  let collectionId = options.collectionId;
+  let filters = options.filters;
+  let sort = options.sort;
+  let limit = options.limit ?? 20;
+  let include = options.include;
+  const key = () => queryKey({ collectionId, filters, sort, limit, include });
+
+  let items: CmsItem[] | null = options.initialItems ?? null;
+  let hasNext = options.initialHasNext ?? (options.initialItems ? options.initialItems.length >= limit : false);
+  let loadingMore = false;
+  let error: string | null = null;
+  // The query the current items answer (null = nothing answered yet).
+  let pageKey: string | null = options.initialItems ? key() : null;
+  let inflight = false;
+  let started = false;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+  let snapshot: CollectionState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function getState(): CollectionState {
+    if (snapshot) return snapshot;
+    snapshot = { items, hasNext, loadingMore, error, loading: items === null };
+    return snapshot;
+  }
+
+  function run(): void {
+    if (!started) return;
+    const k = key();
+    const id = ++generation;
+    pageKey = k; inflight = true;
+    items = null; error = null; loadingMore = false;
+    emit();
+    queryItems(collectionId, { filters, sort, limit, include })
+      .then((page) => {
+        if (generation !== id) return; // superseded — drop it
+        items = page.items; hasNext = page.hasNext; inflight = false;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id) return;
+        items = []; hasNext = false; inflight = false;
+        error = e instanceof Error ? e.message : String(e);
+        emit();
+      });
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      // The SSR seed answered this exact query — no fetch; a dropped first load reruns.
+      if (pageKey !== key() || (items === null && !inflight)) run();
+    },
+    stop() {
+      started = false;
+      generation++;
+      inflight = false;
+    },
+    setQuery(q) {
+      if (q.collectionId !== undefined) collectionId = q.collectionId;
+      filters = q.filters; sort = q.sort; include = q.include;
+      if (q.limit !== undefined) limit = q.limit;
+      if (key() === pageKey) return; // same values — same page
+      if (started) run();
+    },
+    async loadMore() {
+      const current = items;
+      if (!current || loadingMore) return;
+      const id = generation;
+      loadingMore = true; emit();
+      try {
+        const page = await queryItems(collectionId, { filters, sort, limit, include, skip: current.length });
+        if (generation !== id) return;
+        items = [...(items ?? []), ...page.items];
+        hasNext = page.hasNext;
+      } catch (e) {
+        if (generation !== id) return;
+        error = e instanceof Error ? e.message : String(e);
+      } finally {
+        if (generation === id) { loadingMore = false; emit(); }
+      }
+    },
+    retry() {
+      pageKey = null;
+      run();
+    },
+  };
+}

package/skills/wix-headless-fast/references/cms/app/wix/cms/item-store.ts

@@ -0,0 +1,93 @@
+// One item as a framework-free store — the logic behind useItem: by `_id` or by a field match
+// (slug routing), usable from React (useItem wraps it), from a static page's item view, from
+// Vue/Svelte, or as the specification for a port.
+//
+// SSR-friendly: pass the server-fetched item as `initialItem` and start() fetches nothing.
+// One store per item surface: createItemStore(), not a singleton.
+import { getItemBy, getItemById } from "./items";
+import type { CmsItem } from "./types";
+
+/** Exactly one of `id` / `by`. */
+export interface ItemRef {
+  id?: string;
+  by?: { field: string; value: string | number };
+}
+
+export interface ItemStoreOptions {
+  collectionId: string;
+  ref: ItemRef;
+  initialItem?: CmsItem;
+  /** Reference field keys to inline as full items. */
+  include?: string[];
+}
+
+export interface ItemState {
+  /** null while loading OR when not found — branch on notFound for the miss state. */
+  item: CmsItem | null;
+  notFound: boolean;
+  error: string | null;
+  /** True until the fetch settles (false at once with an initialItem). */
+  loading: boolean;
+}
+
+export interface ItemStore {
+  getState(): ItemState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch by ref when no `initialItem` was given. Call once when mounted. */
+  start(): void;
+  stop(): void;
+  /** Fetch again (after an error, or when the item may have changed). */
+  retry(): void;
+}
+
+export function createItemStore({ collectionId, ref, initialItem, include }: ItemStoreOptions): ItemStore {
+  let item: CmsItem | null = initialItem ?? null;
+  let notFound = false;
+  let error: string | null = null;
+  let loading = !initialItem;
+  let started = false;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+  let snapshot: ItemState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function getState(): ItemState {
+    if (snapshot) return snapshot;
+    snapshot = { item, notFound, error, loading };
+    return snapshot;
+  }
+
+  function load(): void {
+    const id = ++generation;
+    loading = true; error = null; emit();
+    const fetching = ref.id
+      ? getItemById(collectionId, ref.id, { include })
+      : ref.by
+        ? getItemBy(collectionId, ref.by.field, ref.by.value, { include })
+        : Promise.reject(new Error("useItem: pass ref.id or ref.by"));
+    fetching
+      .then((found) => {
+        if (generation !== id || !started) return;
+        item = found; notFound = found === null; loading = false;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id || !started) return;
+        error = e instanceof Error ? e.message : String(e); loading = false;
+        emit();
+      });
+  }
+
+  return {
+    getState,
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialItem) return;
+      load();
+    },
+    stop() { started = false; generation++; },
+    retry() { if (started) load(); },
+  };
+}

package/skills/wix-headless-fast/references/cms/app/wix/cms/items-core.ts

@@ -0,0 +1,177 @@
+// Wix Data rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./items.ts
+// (the SDK, managed Astro and React) and the REST twin in references/cms/rest/items.ts (fetch, a
+// static site or a port to another language). Every rule about normalizing an item, validating a
+// filter, and spelling a query for the wire lives HERE, once. A raw item may come from the SDK
+// (dates as Date objects) or from REST (dates as `{ "$date": iso }`); the mappers accept both.
+// Imports are type-only so a strip to JS emits no imports.
+import type { CmsFilter, CmsItem, CmsPage, CmsQuery, CmsSort } from "./types";
+
+/** A raw data item's payload as either transport returns it (fields flat, `_id` included). */
+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;
+
+/** Page size when a query names none. */
+export const DEFAULT_LIMIT = 20;
+/** The size every IMAGE field is resolved at — one URL per item, large enough for a detail page. */
+export const IMAGE_WIDTH = 1200;
+export const IMAGE_HEIGHT = 900;
+
+// ---- DTO normalization ---------------------------------------------------------------------------
+
+/** REST spells DATE/DATETIME fields as `{ "$date": "<iso>" }`; the SDK decodes them into Date objects. */
+function isDateWrapper(v: unknown): v is { $date: string } {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  const keys = Object.keys(v as Raw);
+  return keys.length === 1 && keys[0] === "$date" && typeof (v as Raw).$date === "string";
+}
+
+/**
+ * Raw → DTO value: dates become ISO strings (Date objects aren't serializable as island props;
+ * `{ $date }` wrappers aren't dates at all), IMAGE fields holding a `wix:image://` identifier
+ * become https URLs a browser can load. Recursive — included reference items too.
+ */
+export function toValue(v: unknown, imgSrc: ImgSrc): unknown {
+  if (v instanceof Date) return v.toISOString();
+  if (isDateWrapper(v)) {
+    // Same spelling as the SDK path (REST omits the milliseconds: "…T00:00:00Z").
+    const t = new Date(v.$date);
+    return Number.isNaN(t.getTime()) ? v.$date : t.toISOString();
+  }
+  if (typeof v === "string" && v.startsWith("wix:image://")) return imgSrc(v, IMAGE_WIDTH, IMAGE_HEIGHT);
+  if (Array.isArray(v)) return v.map((x) => toValue(x, imgSrc));
+  if (v && typeof v === "object") {
+    const out: Raw = {};
+    for (const [k, val] of Object.entries(v as Raw)) out[k] = toValue(val, imgSrc);
+    return out;
+  }
+  return v;
+}
+
+export const toItem = (raw: Raw, imgSrc: ImgSrc): CmsItem => toValue(raw, imgSrc) as CmsItem;
+
+export function toPage(items: Raw[], hasNext: boolean, total: number | null | undefined, imgSrc: ImgSrc): CmsPage {
+  return { items: items.map((r) => toItem(r, imgSrc)), hasNext, total: total ?? null };
+}
+
+/**
+ * A DATE/DATETIME field for display — the DTO carries an ISO string; this is the one place it
+ * becomes copy. "" for an absent or unparseable value (never "Invalid Date", never the raw ISO).
+ *   formatDate(item.publishDate)                       → "August 20, 2026"
+ *   formatDate(item.publishDate, "en-GB", { dateStyle: "medium" })
+ */
+export function formatDate(iso: unknown, locale = "en-US", options: Intl.DateTimeFormatOptions = { dateStyle: "long" }): string {
+  if (typeof iso !== "string" || !iso) return "";
+  const t = new Date(iso);
+  return Number.isNaN(t.getTime()) ? "" : new Intl.DateTimeFormat(locale, options).format(t);
+}
+
+// ---- filter rules --------------------------------------------------------------------------------
+
+/**
+ * An undefined comparand silently changes what a query matches (every row, or none) with no
+ * server error — the classic "my items shows everyone's items" bug. Throw at the call site;
+ * omit the filter entirely when you don't hold a value yet.
+ */
+export function assertFilterValue(f: CmsFilter): void {
+  if (f.op !== "isEmpty" && f.op !== "isNotEmpty" && f.value === undefined) {
+    throw new Error(
+      `cms: filter on "${f.field}" (${f.op}) has an undefined value — pass a real value or omit the filter.`,
+    );
+  }
+}
+
+// ---- the REST spelling of a query ---------------------------------------------------------------
+// The SDK's query builder serializes these itself; the REST twin sends them literally. Proven live:
+// a DATE comparand must travel as `{ "$date": iso }` (a plain ISO string compares as text and
+// matches nothing); isEmpty is `{ field: null }` and isNotEmpty `{ field: { $ne: null } }` — the
+// `$isEmpty` keyword is rejected (WDE0076).
+
+/** A comparand on the wire: Date → `{ $date }`, arrays element-wise, everything else as-is. */
+export function restValue(v: unknown): unknown {
+  if (v instanceof Date) return { $date: v.toISOString() };
+  if (Array.isArray(v)) return v.map(restValue);
+  return v;
+}
+
+const REST_OPS: Record<Exclude<CmsFilter["op"], "isEmpty" | "isNotEmpty">, string> = {
+  eq: "$eq",
+  ne: "$ne",
+  gt: "$gt",
+  ge: "$gte",
+  lt: "$lt",
+  le: "$lte",
+  contains: "$contains",
+  startsWith: "$startsWith",
+  hasSome: "$hasSome",
+  hasAll: "$hasAll",
+};
+
+/** One predicate → one filter object `{ field: condition }`. */
+export function restCondition(f: CmsFilter): Raw {
+  assertFilterValue(f);
+  if (f.op === "isEmpty") return { [f.field]: null };
+  if (f.op === "isNotEmpty") return { [f.field]: { $ne: null } };
+  return { [f.field]: { [REST_OPS[f.op]]: restValue(f.value) } };
+}
+
+/** All predicates AND-ed: `{}` for none, the one object for one, `{ $and: [...] }` otherwise. */
+export function restFilter(filters: CmsFilter[] = []): Raw {
+  const conditions = filters.map(restCondition);
+  if (conditions.length === 0) return {};
+  if (conditions.length === 1) return conditions[0];
+  return { $and: conditions };
+}
+
+export function restSort(sort: CmsSort[] = []): { fieldName: string; order: "ASC" | "DESC" }[] {
+  return sort.map((s) => ({ fieldName: s.field, order: s.direction === "desc" ? "DESC" : "ASC" }));
+}
+
+/**
+ * The full Query Data Items body. Offset paging (`skip` = page N × limit) so every page can carry
+ * its own filter/sort and `returnTotalCount` works; `includeReferences[].field` inlines reference
+ * items.  POST /wix-data/v2/items/query
+ */
+export function queryBody(collectionId: string, query: CmsQuery = {}): Raw {
+  const { filters = [], sort = [], limit = DEFAULT_LIMIT, skip = 0, include = [], withTotal = false } = query;
+  return {
+    dataCollectionId: collectionId,
+    query: {
+      filter: restFilter(filters),
+      ...(sort.length ? { sort: restSort(sort) } : {}),
+      paging: { limit, offset: skip },
+    },
+    ...(include.length ? { includeReferences: include.map((field) => ({ field })) } : {}),
+    ...(withTotal ? { returnTotalCount: true } : {}),
+  };
+}
+
+/** Whether another page follows — the response says so; the arithmetic is the fallback. */
+export function restHasNext(pagingMetadata: Raw | undefined, offset: number, limit: number): boolean {
+  if (typeof pagingMetadata?.hasNext === "boolean") return pagingMetadata.hasNext;
+  if (typeof pagingMetadata?.total === "number") return offset + (pagingMetadata.count ?? 0) < pagingMetadata.total;
+  return (pagingMetadata?.count ?? 0) >= limit;
+}
+
+// ---- the REST spelling of a write ---------------------------------------------------------------
+
+/**
+ * Field values for an insert/update body. A DATE field must arrive as `{ $date }` — JSON.stringify
+ * turns a Date into a plain ISO string, which Wix stores as TEXT and never matches a date query.
+ * The read-only system fields are Wix's to stamp, never sent.
+ */
+export function restWriteData(data: Record<string, unknown>): Raw {
+  const out: Raw = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (k === "_createdDate" || k === "_updatedDate" || k === "_owner") continue;
+    out[k] = restValue(v);
+  }
+  return out;
+}
+
+/** The Patch Data Item modifications for "set these fields" — one SET_FIELD per key.  PATCH /wix-data/v2/items/{id} */
+export function patchModifications(fields: Record<string, unknown>): Raw[] {
+  const entries = Object.entries(fields);
+  if (!entries.length) throw new Error("cms: patchItemFields called with no fields.");
+  return entries.map(([fieldPath, value]) => ({ fieldPath, action: "SET_FIELD", setFieldOptions: { value: restValue(value) } }));
+}

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

@@ -1,52 +1,24 @@
-// Wix Data reads/writes (@wix/data `items`) — the only file that touches raw data items.
-// CMS is schema-generic: every function takes the collection id from the seed plan
-// (seed/SEED.md) and returns plain CmsItem DTOs from ./types. Copy as-is; extend by adding
-// functions, not by editing these.
+// Wix Data reads/writes (@wix/data `items`) over the SDK — the only file that touches raw data
+// items on this transport. CMS is schema-generic: every function takes the collection id from the
+// seed plan (seed/SEED.md) and returns plain CmsItem DTOs from ./types. The rules and mappers live
+// in ./items-core (shared with the REST twin in references/cms/rest/); this file is the transport
+// only. Copy as-is; extend by adding functions, not by editing these.
 // docs: https://dev.wix.com/docs/sdk/business-solutions/data/items/query.md
 // docs: https://dev.wix.com/docs/sdk/business-solutions/data/items/update.md
 import { items as itemsModule } from "@wix/data";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
+import { DEFAULT_LIMIT, assertFilterValue, toItem, type Raw } from "./items-core";
 import type { CmsFilter, CmsItem, CmsPage, CmsQuery } from "./types";
 
 const items = wixModule(itemsModule);
 
-type Raw = Record<string, any>;
-
-// SDK → DTO: the SDK decodes date fields into Date objects (not serializable as island
-// props) and IMAGE fields arrive as wix:image:// identifiers a browser can't load
-// (ERR_UNKNOWN_URL_SCHEME). Normalize recursively — included reference items too.
-function toValue(v: unknown): unknown {
-  if (v instanceof Date) return v.toISOString();
-  if (typeof v === "string" && v.startsWith("wix:image://")) return imgSrc(v, 1200, 900);
-  if (Array.isArray(v)) return v.map(toValue);
-  if (v && typeof v === "object") {
-    const out: Raw = {};
-    for (const [k, val] of Object.entries(v as Raw)) out[k] = toValue(val);
-    return out;
-  }
-  return v;
-}
-
-const toItem = (raw: Raw): CmsItem => toValue(raw) as CmsItem;
-
-// An undefined comparand silently changes what a query matches (every row, or none) with no
-// server error — the classic "my items shows everyone's items" bug. Throw at the call site;
-// omit the filter entirely when you don't hold a value yet.
-function assertFilterValue(f: CmsFilter): void {
-  if (f.op !== "isEmpty" && f.op !== "isNotEmpty" && f.value === undefined) {
-    throw new Error(
-      `cms: filter on "${f.field}" (${f.op}) has an undefined value — pass a real value or omit the filter.`,
-    );
-  }
-}
-
 /**
  * Query one page of a collection. An empty result on a PUBLIC collection is a seed
  * permissions bug (read must be "ANYONE"), not a query bug — never reach for auth.elevate.
  */
 export async function queryItems(collectionId: string, query: CmsQuery = {}): Promise<CmsPage> {
-  const { filters = [], sort = [], limit = 20, skip = 0, include = [], withTotal = false } = query;
+  const { filters = [], sort = [], limit = DEFAULT_LIMIT, skip = 0, include = [], withTotal = false } = query;
   let q = items.query(collectionId);
   for (const f of filters) {
     assertFilterValue(f);
@@ -70,7 +42,7 @@ export async function queryItems(collectionId: string, query: CmsQuery = {}): Pr
   if (include.length) q = q.include(...include);
   const res = await q.limit(limit).skip(skip).find(withTotal ? { returnTotalCount: true } : undefined);
   return {
-    items: (res.items ?? []).map((r: Raw) => toItem(r)),
+    items: (res.items ?? []).map((r: Raw) => toItem(r, imgSrc)),
     hasNext: res.hasNext(),
     total: res.totalCount ?? null,
   };
@@ -85,7 +57,7 @@ export async function getItemById(
   const raw = await items.get(collectionId, itemId, {
     ...(include.length ? { includeReferences: include.map((field) => ({ field })) } : {}),
   });
-  return raw ? toItem(raw as Raw) : null;
+  return raw ? toItem(raw as Raw, imgSrc) : null;
 }
 
 /**
@@ -116,7 +88,7 @@ export async function countItems(collectionId: string, filters: CmsFilter[] = []
  */
 export async function insertItem(collectionId: string, data: Record<string, unknown>): Promise<CmsItem> {
   const created = await items.insert(collectionId, data as Raw);
-  return toItem(created as Raw);
+  return toItem(created as Raw, imgSrc);
 }
 
 /**
@@ -127,7 +99,7 @@ export async function insertItem(collectionId: string, data: Record<string, unkn
  */
 export async function updateItem(collectionId: string, item: CmsItem): Promise<CmsItem> {
   const updated = await items.update(collectionId, item as Raw & { _id: string });
-  return toItem(updated as Raw);
+  return toItem(updated as Raw, imgSrc);
 }
 
 /** Patch only the named fields — the safe partial change (no replace-wipes-fields footgun). */
@@ -141,11 +113,11 @@ export async function patchItemFields(
   let p = items.patch(collectionId, itemId);
   for (const [k, v] of entries) p = p.setField(k, v);
   const patched = await p.run();
-  return toItem(patched as Raw);
+  return toItem(patched as Raw, imgSrc);
 }
 
 /** Remove an item by `_id`. Irreversible. Returns the removed item (null if it didn't exist). */
 export async function removeItem(collectionId: string, itemId: string): Promise<CmsItem | null> {
   const removed = await items.remove(collectionId, itemId);
-  return removed ? toItem(removed as Raw) : null;
+  return removed ? toItem(removed as Raw, imgSrc) : null;
 }