@wix/agent-skills 1.19.2 → 1.20.1

package/skills/wix-headless-fast/references/portfolio/app/hooks/portfolio/useCollections.ts

@@ -1,39 +1,21 @@
-// Collections gallery. SSR-friendly: pass server-fetched data as `initialCollections`
-// (Astro frontmatter / server component) and no client fetch happens; a SPA passes nothing.
-import { useEffect, useState } from "react";
-import { fetchCollections } from "../../wix/portfolio/portfolio";
-import type { CollectionSummary } from "../../wix/portfolio/types";
+// React binding of the collections store (wix/portfolio/collections-store.ts) — the gallery's
+// load state lives there, framework-free; this hook subscribes to one instance per mounted
+// gallery. SSR-friendly: pass server-fetched data as `initialCollections` and no client fetch
+// happens; a SPA passes nothing. A static page, Vue, or Svelte uses the store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createCollectionsStore, type CollectionsState, type CollectionsStore, type CollectionsStoreOptions } from "../../wix/portfolio/collections-store";
 
-export interface UseCollectionsOptions {
-  initialCollections?: CollectionSummary[];
-}
-
-export interface UseCollections {
-  /** null while the first load is in flight — render skeletons, not an empty state. */
-  collections: CollectionSummary[] | null;
-  error: string | null;
-}
+export type UseCollectionsOptions = CollectionsStoreOptions;
 
-export function useCollections({ initialCollections }: UseCollectionsOptions = {}): UseCollections {
-  const [collections, setCollections] = useState<CollectionSummary[] | null>(initialCollections ?? null);
-  const [error, setError] = useState<string | null>(null);
+export type UseCollections = CollectionsState;
 
+export function useCollections(options: UseCollectionsOptions = {}): UseCollections {
+  const ref = useRef<CollectionsStore | null>(null);
+  if (!ref.current) ref.current = createCollectionsStore(options);
+  const store = ref.current;
   useEffect(() => {
-    let alive = true;
-    if (!initialCollections) {
-      fetchCollections()
-        .then((c) => alive && setCollections(c))
-        .catch((e) => {
-          if (!alive) return;
-          setCollections([]);
-          setError(e instanceof Error ? e.message : String(e));
-        });
-    }
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  return { collections, error };
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
 }

package/skills/wix-headless-fast/references/portfolio/app/hooks/portfolio/useProjectDetail.ts

@@ -1,58 +1,31 @@
-// Project detail + media gallery, by slug. SSR-friendly: pass both `initial*` and no client
-// fetch happens. `notFound` is the real not-found signal (project stays null while loading).
-import { useEffect, useState } from "react";
-import { fetchProjectBySlug, fetchProjectGallery } from "../../wix/portfolio/portfolio";
-import type { GalleryItem, ProjectDetail } from "../../wix/portfolio/types";
+// React binding of the project-detail store (wix/portfolio/project-detail-store.ts) — slug →
+// project + media gallery lives there, framework-free; this hook subscribes to one instance per
+// (slug, mount) and recreates it when the slug changes. SSR-friendly: pass both `initial*` and no
+// client fetch happens. `notFound` is the real not-found signal (project stays null while loading).
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createProjectDetailStore,
+  type ProjectDetailState,
+  type ProjectDetailStore,
+  type ProjectDetailStoreOptions,
+} from "../../wix/portfolio/project-detail-store";
 
-export interface UseProjectDetailOptions {
-  initialProject?: ProjectDetail;
-  initialItems?: GalleryItem[];
-}
+export type UseProjectDetailOptions = ProjectDetailStoreOptions;
 
-export interface UseProjectDetail {
-  /** null while loading AND when not found — check `notFound` to tell them apart. */
-  project: ProjectDetail | null;
-  notFound: boolean;
-  /** null while the gallery load is in flight — render skeletons, not an empty state. */
-  items: GalleryItem[] | null;
-  error: string | null;
-}
+export type UseProjectDetail = ProjectDetailState;
 
 export function useProjectDetail(
   slug: string,
   { initialProject, initialItems }: UseProjectDetailOptions = {},
 ): UseProjectDetail {
-  const [project, setProject] = useState<ProjectDetail | null>(initialProject ?? null);
-  const [notFound, setNotFound] = useState(false);
-  const [items, setItems] = useState<GalleryItem[] | null>(initialItems ?? null);
-  const [error, setError] = useState<string | null>(null);
-
+  const ref = useRef<{ slug: string; store: ProjectDetailStore } | null>(null);
+  if (!ref.current || ref.current.slug !== slug) {
+    ref.current = { slug, store: createProjectDetailStore(slug, { initialProject, initialItems }) };
+  }
+  const store = ref.current.store;
   useEffect(() => {
-    if (initialProject && initialItems) return;
-    let alive = true;
-    (async () => {
-      try {
-        const proj = initialProject ?? (await fetchProjectBySlug(slug));
-        if (!alive) return;
-        if (!proj) {
-          setNotFound(true);
-          setItems([]);
-          return;
-        }
-        setProject(proj);
-        const gallery = await fetchProjectGallery(proj.id);
-        if (alive) setItems(gallery);
-      } 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
-  }, [slug]);
-
-  return { project, notFound, items, error };
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
 }

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

@@ -0,0 +1,82 @@
+// One collection's header + its projects, by slug, as a framework-free store — the logic behind
+// useCollectionProjects, usable from React (the hook wraps it), from a static page's collection
+// view, from Vue/Svelte, or as the specification for a port.
+//
+// SSR-friendly: pass BOTH `initialCollection` and `initialProjects` and nothing is fetched. With
+// only the collection seeded, `start()` fetches its projects; with nothing seeded it resolves the
+// slug first. `notFound` is the real not-found signal (collection stays null while loading too) —
+// route a 404 off it, never off a transient null. One store per (slug, mount):
+// createCollectionProjectsStore(slug, options), not a singleton.
+import { fetchCollectionBySlug, fetchProjects } from "./portfolio";
+import type { CollectionSummary, ProjectSummary } from "./types";
+
+export interface CollectionProjectsStoreOptions {
+  initialCollection?: CollectionSummary;
+  initialProjects?: ProjectSummary[];
+}
+
+export interface CollectionProjectsState {
+  /** null while loading AND when not found — check `notFound` to tell them apart. */
+  collection: CollectionSummary | null;
+  notFound: boolean;
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  projects: ProjectSummary[] | null;
+  error: string | null;
+}
+
+export interface CollectionProjectsStore {
+  getState(): CollectionProjectsState;
+  subscribe(listener: () => void): () => void;
+  /** Resolve the slug and load its projects unless both were seeded. Call once when mounted. */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+}
+
+export function createCollectionProjectsStore(
+  slug: string,
+  { initialCollection, initialProjects }: CollectionProjectsStoreOptions = {},
+): CollectionProjectsStore {
+  let collection: CollectionSummary | null = initialCollection ?? null;
+  let notFound = false;
+  let projects: ProjectSummary[] | null = initialProjects ?? null;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: CollectionProjectsState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  return {
+    getState() {
+      return (snapshot ??= { collection, notFound, projects, error });
+    },
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialCollection && initialProjects) return;
+      (async () => {
+        try {
+          const col = initialCollection ?? (await fetchCollectionBySlug(slug));
+          if (!started) return;
+          if (!col) {
+            notFound = true;
+            projects = [];
+            emit();
+            return;
+          }
+          collection = col;
+          emit();
+          const list = await fetchProjects({ collectionId: col.id });
+          if (started) { projects = list; emit(); }
+        } catch (e) {
+          if (!started) return;
+          projects = [];
+          error = e instanceof Error ? e.message : String(e);
+          emit();
+        }
+      })();
+    },
+    stop() { started = false; },
+  };
+}

package/skills/wix-headless-fast/references/portfolio/app/wix/portfolio/collections-store.ts

@@ -0,0 +1,58 @@
+// The collections gallery as a framework-free store — the logic behind useCollections, usable
+// from React (useCollections wraps it with useSyncExternalStore), from a static page or
+// Vue/Svelte (subscribe and render), or as the specification for a port. State, subscribe/getState,
+// start()/stop(), emit after every change.
+//
+// SSR-friendly: seed with `initialCollections` and nothing is fetched; without a seed `start()`
+// fetches once. One store per mounted gallery: createCollectionsStore(), not a singleton.
+import { fetchCollections } from "./portfolio";
+import type { CollectionSummary } from "./types";
+
+export interface CollectionsStoreOptions {
+  initialCollections?: CollectionSummary[];
+}
+
+export interface CollectionsState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  collections: CollectionSummary[] | null;
+  error: string | null;
+}
+
+export interface CollectionsStore {
+  getState(): CollectionsState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch when no seed was given. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop a late response. */
+  stop(): void;
+}
+
+export function createCollectionsStore({ initialCollections }: CollectionsStoreOptions = {}): CollectionsStore {
+  let collections: CollectionSummary[] | null = initialCollections ?? null;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: CollectionsState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  return {
+    getState() {
+      return (snapshot ??= { collections, error });
+    },
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialCollections) return;
+      fetchCollections()
+        .then((c) => { if (started) { collections = c; emit(); } })
+        .catch((e) => {
+          if (!started) return;
+          collections = [];
+          error = e instanceof Error ? e.message : String(e);
+          emit();
+        });
+    },
+    stop() { started = false; },
+  };
+}

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

@@ -0,0 +1,177 @@
+// Portfolio rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./portfolio.ts
+// (the SDK, managed Astro and React) and the REST twin in references/portfolio/rest/portfolio.ts
+// (fetch, a static site or a port to another language). Every rule about hidden entities, order,
+// covers, media kinds lives HERE, once. A raw entity may come from the SDK (`_id`) or from REST
+// (`id`); the mappers accept both. Imports are type-only so a strip to JS emits no imports.
+import type { CollectionSummary, GalleryItem, ProjectDetail, ProjectDetailRow, ProjectSummary } from "./types";
+
+/** A raw Portfolio v1 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;
+/**
+ * A `wix:video://` reference → its mp4 rendition and poster, or null when it can't be resolved.
+ * Injected: only the SDK can resolve the string form (media.getVideoUrl); REST never receives it
+ * (its videoInfo is already an object with resolutions + posters, handled here).
+ */
+export type VideoSrc = (wixVideoRef: string) => { url: string; thumbnail: string } | null;
+
+const id = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+/**
+ * An image reference as either transport carries it — the SDK's bare `wix:image://` string, or
+ * REST's `imageInfo` object `{ id, url, filename }` — normalized to the `wix:image://` form so
+ * imgSrc scales both to the SAME URL (REST's `url` is a fixed 1024×1024 rendition; the id is the
+ * media file). "" when there is no image.
+ */
+export function imageRef(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  const o = value as Raw;
+  if (typeof o.id === "string" && o.id) return `wix:image://v1/${o.id}/${o.filename ?? o.id}`;
+  return typeof o.url === "string" ? o.url : "";
+}
+
+/**
+ * A video as either transport carries it: the SDK's bare `wix:video://` string (resolved by the
+ * injected videoSrc — 720p is the standard transcode), or REST's videoInfo object
+ * `{ resolutions: [{ url }], posters: [{ id, url }] }` (optimal resolution first).
+ */
+export function toVideo(value: unknown, imgSrc: ImgSrc, videoSrc: VideoSrc): { videoUrl: string | null; posterUrl: string } {
+  if (typeof value === "string") {
+    const v = value.startsWith("wix:video://") ? videoSrc(value) : null;
+    return v ? { videoUrl: v.url, posterUrl: imgSrc(imageRef(v.thumbnail), 1200, 675) } : { videoUrl: null, posterUrl: "" };
+  }
+  const raw = value as Raw | null | undefined;
+  const url = raw?.resolutions?.[0]?.url;
+  return {
+    videoUrl: typeof url === "string" ? url : null,
+    posterUrl: imgSrc(imageRef(raw?.posters?.[0]), 1200, 675),
+  };
+}
+
+// ---- DTO mappers -----------------------------------------------------------------------------------
+
+export function toCollection(raw: Raw, imgSrc: ImgSrc): CollectionSummary {
+  return {
+    id: id(raw),
+    slug: raw.slug ?? "",
+    title: raw.title ?? "",
+    description: raw.description ?? "",
+    imageUrl: imgSrc(imageRef(raw.coverImage?.imageInfo), 1200, 900),
+  };
+}
+
+/** coverImage is ONE-OF with coverVideo — a video-covered project falls back to its poster. */
+export function projectCover(raw: Raw, imgSrc: ImgSrc, videoSrc: VideoSrc): string {
+  return imgSrc(imageRef(raw.coverImage?.imageInfo), 1200, 900) || toVideo(raw.coverVideo?.videoInfo, imgSrc, videoSrc).posterUrl;
+}
+
+export function toProject(raw: Raw, imgSrc: ImgSrc, videoSrc: VideoSrc): ProjectSummary {
+  return {
+    id: id(raw),
+    slug: raw.slug ?? "",
+    title: raw.title ?? "",
+    description: raw.description ?? "",
+    imageUrl: projectCover(raw, imgSrc, videoSrc),
+    collectionIds: raw.collectionIds ?? [],
+  };
+}
+
+/** A details row is a one-of: { label, text } or { label, link: { text, url, target } }. */
+export function toDetailRow(raw: Raw): ProjectDetailRow {
+  return {
+    label: raw.label ?? "",
+    text: raw.link?.text ?? raw.text ?? "",
+    url: raw.link?.url ?? null,
+    target: raw.link?.target ?? null,
+  };
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc, videoSrc: VideoSrc): ProjectDetail {
+  return { ...toProject(raw, imgSrc, videoSrc), details: ((raw.details ?? []) as Raw[]).map(toDetailRow) };
+}
+
+/** IMAGE → image item, VIDEO → video item; UNDEFINED or unresolvable media → null (nothing renderable). */
+export function toGalleryItem(raw: Raw, imgSrc: ImgSrc, videoSrc: VideoSrc): GalleryItem | null {
+  const base = {
+    id: id(raw),
+    title: raw.title ?? "",
+    description: raw.description ?? "",
+    linkUrl: raw.link?.url ?? null,
+    linkTarget: raw.link?.target ?? null,
+  };
+  if (raw.type === "IMAGE") {
+    const imageUrl = imgSrc(imageRef(raw.image?.imageInfo), 1600, 1200);
+    return imageUrl ? { ...base, kind: "image", imageUrl, videoUrl: null } : null;
+  }
+  if (raw.type === "VIDEO") {
+    const { videoUrl, posterUrl } = toVideo(raw.video?.videoInfo, imgSrc, videoSrc);
+    return videoUrl ? { ...base, kind: "video", imageUrl: posterUrl, videoUrl } : null;
+  }
+  return null;
+}
+
+// ---- list rules -----------------------------------------------------------------------------------
+
+/**
+ * Visible collections in the owner's dashboard order (sortOrder — collections have one, projects
+ * don't). An omitted `hidden` comes back ABSENT (proto3): test falsy, never === false.
+ */
+export function visibleCollections(raws: Raw[], imgSrc: ImgSrc): CollectionSummary[] {
+  return raws
+    .filter((c) => !c.hidden)
+    .sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
+    .map((c) => toCollection(c, imgSrc));
+}
+
+/** One visible collection, or null when missing or hidden (a real 404, never a fallback). */
+export function visibleCollection(raw: Raw | undefined | null, imgSrc: ImgSrc): CollectionSummary | null {
+  return raw && !raw.hidden ? toCollection(raw, imgSrc) : null;
+}
+
+/**
+ * Visible projects in list order (Project exposes no sortOrder), optionally only one collection's.
+ * The collection filter is client-side over the one list (portfolios are small; a project links
+ * to collections via collectionIds).
+ */
+export function visibleProjects(raws: Raw[], collectionId: string | undefined, imgSrc: ImgSrc, videoSrc: VideoSrc): ProjectSummary[] {
+  return raws
+    .filter((p) => !p.hidden)
+    .filter((p) => !collectionId || ((p.collectionIds ?? []) as string[]).includes(collectionId))
+    .map((p) => toProject(p, imgSrc, videoSrc));
+}
+
+/** One visible project with its details rows, or null when missing or hidden. */
+export function visibleProject(raw: Raw | undefined | null, imgSrc: ImgSrc, videoSrc: VideoSrc): ProjectDetail | null {
+  return raw && !raw.hidden ? toDetail(raw, imgSrc, videoSrc) : null;
+}
+
+/** A project's gallery in dashboard order (item sortOrder); UNDEFINED and unresolvable items dropped. */
+export function galleryItems(raws: Raw[], imgSrc: ImgSrc, videoSrc: VideoSrc): GalleryItem[] {
+  return raws
+    .slice()
+    .sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
+    .map((it) => toGalleryItem(it, imgSrc, videoSrc))
+    .filter((g): g is GalleryItem => g !== null);
+}
+
+// ---- render rule ----------------------------------------------------------------------------------
+
+/** The one element a gallery item renders as, attribute names as HTML spells them. */
+export type MediaElement =
+  | { tag: "img"; attrs: { src: string; alt: string; loading: "lazy"; decoding: "async" } }
+  | { tag: "video"; attrs: { src: string; poster?: string; controls: ""; playsinline: "" } };
+
+/**
+ * Branch on `kind` once, here: a video item is a <video> with its poster, an image item an <img>,
+ * anything else null — never a broken tag, never an <img> for a video. The shipped GalleryMedia.tsx
+ * renders this; a static page or a port creates the element from it.
+ */
+export function mediaElement(item: GalleryItem): MediaElement | null {
+  if (item.kind === "video" && item.videoUrl) {
+    return { tag: "video", attrs: { src: item.videoUrl, ...(item.imageUrl ? { poster: item.imageUrl } : {}), controls: "", playsinline: "" } };
+  }
+  if (item.imageUrl) return { tag: "img", attrs: { src: item.imageUrl, alt: item.title, loading: "lazy", decoding: "async" } };
+  return null;
+}

package/skills/wix-headless-fast/references/portfolio/app/wix/portfolio/portfolio.ts

@@ -1,6 +1,8 @@
-// Portfolio reads (Wix Portfolio v1) — the only file that touches raw portfolio entities.
-// Read-only vertical: no cart, no checkout, no @wix/ecom. Everything it returns is a plain
-// DTO from ./types. Copy as-is; extend by adding functions, not by editing these.
+// Portfolio reads (Wix Portfolio v1) over the SDK — the only file that touches raw portfolio
+// entities on this transport. Read-only vertical: no cart, no checkout, no @wix/ecom. Everything
+// it returns is a plain DTO from ./types. The rules and mappers live in ./portfolio-core (shared
+// with the REST twin in references/portfolio/rest/); this file is the transport only. Copy as-is;
+// extend by adding functions, not by editing these.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/list-collections.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/list-projects.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/list-project-items.md
@@ -13,142 +15,57 @@ import {
 import { media, VideoResolution } from "@wix/sdk";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
-import type {
-  CollectionSummary,
-  GalleryItem,
-  ProjectDetail,
-  ProjectDetailRow,
-  ProjectSummary,
-} from "./types";
+import {
+  galleryItems,
+  visibleCollection,
+  visibleCollections,
+  visibleProject,
+  visibleProjects,
+  type Raw,
+  type VideoSrc,
+} from "./portfolio-core";
+import type { CollectionSummary, GalleryItem, ProjectDetail, ProjectSummary } from "./types";
 
 const collections = wixModule(collectionsModule);
 const projects = wixModule(projectsModule);
 const projectItems = wixModule(projectItemsModule);
 
-type Raw = Record<string, any>;
-
-// The SDK types coverImage.imageInfo / item.image.imageInfo as a bare wix:image:// STRING
-// (the REST docs show an object with .url — the package wins); imgSrc resolves either shape.
-
-// videoInfo is likewise a bare wix:video:// string; getVideoUrl derives the mp4 rendition +
-// poster (a wix:image:// string → imgSrc again). 720p is the standard transcode. Tolerates
-// the REST-shaped object ({ resolutions, posters }) in case a surface returns it at runtime.
-function toVideo(value: unknown): { videoUrl: string | null; posterUrl: string } {
-  if (typeof value === "string" && value.startsWith("wix:video://")) {
-    try {
-      const v = media.getVideoUrl(value, VideoResolution.MID);
-      return { videoUrl: v.url, posterUrl: imgSrc(v.thumbnail, 1200, 675) };
-    } catch {
-      return { videoUrl: null, posterUrl: "" };
-    }
-  }
-  const raw = value as Raw | null | undefined;
-  const url = raw?.resolutions?.[0]?.url;
-  return {
-    videoUrl: typeof url === "string" ? url : null,
-    posterUrl: imgSrc(raw?.posters?.[0], 1200, 675),
-  };
-}
-
-function toCollection(raw: Raw): CollectionSummary {
-  return {
-    id: raw._id ?? "",
-    slug: raw.slug ?? "",
-    title: raw.title ?? "",
-    description: raw.description ?? "",
-    imageUrl: imgSrc(raw.coverImage?.imageInfo, 1200, 900),
-  };
-}
-
-// coverImage is ONE-OF with coverVideo — a video-covered project falls back to its poster.
-function projectCover(raw: Raw): string {
-  return imgSrc(raw.coverImage?.imageInfo, 1200, 900) || toVideo(raw.coverVideo?.videoInfo).posterUrl;
-}
-
-function toProject(raw: Raw): ProjectSummary {
-  return {
-    id: raw._id ?? "",
-    slug: raw.slug ?? "",
-    title: raw.title ?? "",
-    description: raw.description ?? "",
-    imageUrl: projectCover(raw),
-    collectionIds: raw.collectionIds ?? [],
-  };
-}
-
-// A details row is a one-of: { label, text } or { label, link: { text, url, target } }.
-function toDetailRow(raw: Raw): ProjectDetailRow {
-  return {
-    label: raw.label ?? "",
-    text: raw.link?.text ?? raw.text ?? "",
-    url: raw.link?.url ?? null,
-    target: raw.link?.target ?? null,
-  };
-}
-
-function toDetail(raw: Raw): ProjectDetail {
-  return { ...toProject(raw), details: (raw.details ?? []).map((d: Raw) => toDetailRow(d)) };
-}
-
-function toGalleryItem(raw: Raw): GalleryItem | null {
-  const base = {
-    id: raw._id ?? "",
-    title: raw.title ?? "",
-    description: raw.description ?? "",
-    linkUrl: raw.link?.url ?? null,
-    linkTarget: raw.link?.target ?? null,
-  };
-  if (raw.type === "IMAGE") {
-    const imageUrl = imgSrc(raw.image?.imageInfo, 1600, 1200);
-    return imageUrl ? { ...base, kind: "image", imageUrl, videoUrl: null } : null;
-  }
-  if (raw.type === "VIDEO") {
-    const { videoUrl, posterUrl } = toVideo(raw.video?.videoInfo);
-    return videoUrl ? { ...base, kind: "video", imageUrl: posterUrl, videoUrl } : null;
+// The SDK types coverImage.imageInfo / item.image.imageInfo as a bare wix:image:// STRING and
+// videoInfo as a bare wix:video:// string; getVideoUrl derives the mp4 rendition + poster.
+const videoSrc: VideoSrc = (ref) => {
+  try {
+    const v = media.getVideoUrl(ref, VideoResolution.MID);
+    return { url: v.url, thumbnail: v.thumbnail };
+  } catch {
+    return null;
   }
-  return null; // UNDEFINED — nothing renderable
-}
+};
 
-/**
- * List visible collections in the owner's dashboard order (sortOrder — collections have one,
- * projects don't). An omitted `hidden` comes back ABSENT (proto3): test falsy, never === false.
- */
+/** List visible collections in the owner's dashboard order (sortOrder). */
 export async function fetchCollections({ limit = 100 } = {}): Promise<CollectionSummary[]> {
   const res = await collections.listCollections({ paging: { limit } });
-  return (res.collections ?? [])
-    .filter((c: Raw) => !c.hidden)
-    .sort((a: Raw, b: Raw) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
-    .map((c: Raw) => toCollection(c));
+  return visibleCollections((res.collections ?? []) as Raw[], imgSrc);
 }
 
 /** Fetch one visible collection by its URL slug. Null when not found or hidden. */
 export async function fetchCollectionBySlug(slug: string): Promise<CollectionSummary | null> {
   const res = await collections.queryCollections().eq("slug", slug).limit(1).find();
-  const raw = res.items?.[0] as Raw | undefined;
-  return raw && !raw.hidden ? toCollection(raw) : null;
+  return visibleCollection(res.items?.[0] as Raw | undefined, imgSrc);
 }
 
-/**
- * List visible projects (list order — Project exposes no sortOrder), optionally only one
- * collection's. The collection filter is client-side over the one list call (portfolios are
- * small; a project links to collections via collectionIds).
- */
+/** List visible projects (list order), optionally only one collection's. */
 export async function fetchProjects({
   collectionId,
   limit = 100,
 }: { collectionId?: string; limit?: number } = {}): Promise<ProjectSummary[]> {
   const res = await projects.listProjects({ paging: { limit } });
-  return (res.projects ?? [])
-    .filter((p: Raw) => !p.hidden)
-    .filter((p: Raw) => !collectionId || (p.collectionIds ?? []).includes(collectionId))
-    .map((p: Raw) => toProject(p));
+  return visibleProjects((res.projects ?? []) as Raw[], collectionId, imgSrc, videoSrc);
 }
 
 /** Fetch one visible project by its URL slug. Null when not found or hidden. */
 export async function fetchProjectBySlug(slug: string): Promise<ProjectDetail | null> {
   const res = await projects.queryProjects().eq("slug", slug).limit(1).find();
-  const raw = res.items?.[0] as Raw | undefined;
-  return raw && !raw.hidden ? toDetail(raw) : null;
+  return visibleProject(res.items?.[0] as Raw | undefined, imgSrc, videoSrc);
 }
 
 /**
@@ -157,9 +74,5 @@ export async function fetchProjectBySlug(slug: string): Promise<ProjectDetail |
  */
 export async function fetchProjectGallery(projectId: string): Promise<GalleryItem[]> {
   const res = await projectItems.listProjectItems(projectId, { paging: { limit: 100 } });
-  return (res.items ?? [])
-    .slice()
-    .sort((a: Raw, b: Raw) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
-    .map((it: Raw) => toGalleryItem(it))
-    .filter((g: GalleryItem | null): g is GalleryItem => g !== null);
+  return galleryItems((res.items ?? []) as Raw[], imgSrc, videoSrc);
 }