@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/portfolio/app/components/portfolio/ProjectDetailView.tsx

@@ -0,0 +1,85 @@
+// REFERENCE project detail: header, details[] rows (text or link), media gallery (image AND
+// video items) on the @theme tokens. Correct and complete; per the skill's model you design
+// and build your own on useProjectDetail. The gallery items render through the SHIPPED
+// GalleryMedia (kind branching, poster, link wrap) — keep that in whatever you build.
+import { useProjectDetail } from "../../hooks/portfolio/useProjectDetail";
+import { imgAttrs } from "../../wix/media";
+import type { GalleryItem, ProjectDetail } from "../../wix/portfolio/types";
+import { GalleryLink, GalleryMedia } from "./GalleryMedia";
+
+export interface ProjectDetailViewProps {
+  slug: string;
+  initialProject?: ProjectDetail;
+  initialItems?: GalleryItem[];
+}
+
+export default function ProjectDetailView({ slug, initialProject, initialItems }: ProjectDetailViewProps) {
+  const { project, notFound, items, error } = useProjectDetail(slug, { initialProject, initialItems });
+
+  if (notFound) {
+    return <p className="py-16 text-center text-muted-foreground">Project not found.</p>;
+  }
+  if (!project) {
+    return (
+      <div aria-busy="true">
+        <div className="h-7 w-64 animate-pulse rounded bg-secondary" />
+        <div className="mt-6 aspect-[4/3] animate-pulse rounded-lg bg-secondary" />
+      </div>
+    );
+  }
+
+  return (
+    <article>
+      <header className="mb-8 max-w-2xl">
+        <h1 className="text-2xl font-semibold tracking-tight">{project.title}</h1>
+        {project.description && (
+          <p className="mt-2 leading-relaxed text-muted-foreground">{project.description}</p>
+        )}
+        {project.details.length > 0 && (
+          <dl className="mt-5 grid grid-cols-[auto_1fr] items-baseline gap-x-6 gap-y-1.5">
+            {project.details.map((d, i) => (
+              <div key={i} className="contents">
+                <dt className="text-sm text-muted-foreground">{d.label}</dt>
+                <dd className="m-0 text-sm text-foreground">
+                  {d.url ? (
+                    <a href={d.url} target={d.target ?? undefined} rel="noopener" className="underline">
+                      {d.text}
+                    </a>
+                  ) : (
+                    d.text
+                  )}
+                </dd>
+              </div>
+            ))}
+          </dl>
+        )}
+      </header>
+      {error && <p className="mb-4 text-sm text-destructive">{error}</p>}
+      {items === null ? (
+        <div className="flex flex-col gap-6" aria-busy="true">
+          <div className="aspect-[4/3] animate-pulse rounded-lg bg-secondary" />
+        </div>
+      ) : items.length === 0 ? (
+        // No gallery items — the cover is the project's only real media; text-only otherwise.
+        project.imageUrl ? (
+          <img {...imgAttrs(project.imageUrl, "(min-width: 1024px) 64rem, 100vw", 0.75)} alt={project.title} className="block w-full rounded-lg" />
+        ) : (
+          <p className="py-16 text-center text-muted-foreground">No media in this project yet.</p>
+        )
+      ) : (
+        <div className="flex flex-col gap-6">
+          {items.map((item) => (
+            <figure key={item.id} className="m-0">
+              <GalleryLink item={item}>
+                <GalleryMedia item={item} className="block w-full rounded-lg bg-secondary" />
+              </GalleryLink>
+              {item.title && (
+                <figcaption className="mt-1.5 text-sm text-muted-foreground">{item.title}</figcaption>
+              )}
+            </figure>
+          ))}
+        </div>
+      )}
+    </article>
+  );
+}

package/skills/wix-headless-templates/portfolio/app/hooks/portfolio/useCollectionProjects.ts

@@ -0,0 +1,32 @@
+// React binding of the collection-projects store (wix/portfolio/collection-projects-store.ts) —
+// slug → collection header + its projects 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 (collection
+// stays null while loading too) — route a 404 off it, never off a transient null.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createCollectionProjectsStore,
+  type CollectionProjectsState,
+  type CollectionProjectsStore,
+  type CollectionProjectsStoreOptions,
+} from "../../wix/portfolio/collection-projects-store";
+
+export type UseCollectionProjectsOptions = CollectionProjectsStoreOptions;
+
+export type UseCollectionProjects = CollectionProjectsState;
+
+export function useCollectionProjects(
+  slug: string,
+  { initialCollection, initialProjects }: UseCollectionProjectsOptions = {},
+): UseCollectionProjects {
+  const ref = useRef<{ slug: string; store: CollectionProjectsStore } | null>(null);
+  if (!ref.current || ref.current.slug !== slug) {
+    ref.current = { slug, store: createCollectionProjectsStore(slug, { initialCollection, initialProjects }) };
+  }
+  const store = ref.current.store;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}

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

@@ -0,0 +1,21 @@
+// 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 type UseCollectionsOptions = CollectionsStoreOptions;
+
+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(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}

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

@@ -0,0 +1,31 @@
+// 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 type UseProjectDetailOptions = ProjectDetailStoreOptions;
+
+export type UseProjectDetail = ProjectDetailState;
+
+export function useProjectDetail(
+  slug: string,
+  { initialProject, initialItems }: UseProjectDetailOptions = {},
+): UseProjectDetail {
+  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(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}

package/skills/wix-headless-templates/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-templates/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-templates/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 templates/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-templates/portfolio/app/wix/portfolio/portfolio.ts

@@ -0,0 +1,78 @@
+// 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 templates/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
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import {
+  collections as collectionsModule,
+  projects as projectsModule,
+  projectItems as projectItemsModule,
+} from "@wix/portfolio";
+import { media, VideoResolution } from "@wix/sdk";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+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);
+
+// 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;
+  }
+};
+
+/** 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 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();
+  return visibleCollection(res.items?.[0] as Raw | undefined, imgSrc);
+}
+
+/** 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 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();
+  return visibleProject(res.items?.[0] as Raw | undefined, imgSrc, videoSrc);
+}
+
+/**
+ * A project's media gallery in dashboard order (item sortOrder). IMAGE and VIDEO items only —
+ * UNDEFINED and unresolvable media are dropped. First arg is the project _id (positional).
+ */
+export async function fetchProjectGallery(projectId: string): Promise<GalleryItem[]> {
+  const res = await projectItems.listProjectItems(projectId, { paging: { limit: 100 } });
+  return galleryItems((res.items ?? []) as Raw[], imgSrc, videoSrc);
+}

package/skills/wix-headless-templates/portfolio/app/wix/portfolio/project-detail-store.ts

@@ -0,0 +1,81 @@
+// Project detail + media gallery, by slug, as a framework-free store — the logic behind
+// useProjectDetail, usable from React (the hook wraps it), from a static page's project view,
+// from Vue/Svelte, or as the specification for a port.
+//
+// SSR-friendly: pass BOTH `initialProject` and `initialItems` and nothing is fetched. With only
+// the project seeded, `start()` fetches its gallery; with nothing seeded it resolves the slug
+// first. `notFound` is the real not-found signal (project stays null while loading). One store
+// per (slug, mount): createProjectDetailStore(slug, options), not a singleton.
+import { fetchProjectBySlug, fetchProjectGallery } from "./portfolio";
+import type { GalleryItem, ProjectDetail } from "./types";
+
+export interface ProjectDetailStoreOptions {
+  initialProject?: ProjectDetail;
+  initialItems?: GalleryItem[];
+}
+
+export interface ProjectDetailState {
+  /** 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 interface ProjectDetailStore {
+  getState(): ProjectDetailState;
+  subscribe(listener: () => void): () => void;
+  /** Resolve the slug and load its gallery unless both were seeded. Call once when mounted. */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+}
+
+export function createProjectDetailStore(
+  slug: string,
+  { initialProject, initialItems }: ProjectDetailStoreOptions = {},
+): ProjectDetailStore {
+  let project: ProjectDetail | null = initialProject ?? null;
+  let notFound = false;
+  let items: GalleryItem[] | null = initialItems ?? null;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: ProjectDetailState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  return {
+    getState() {
+      return (snapshot ??= { project, notFound, items, error });
+    },
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialProject && initialItems) return;
+      (async () => {
+        try {
+          const proj = initialProject ?? (await fetchProjectBySlug(slug));
+          if (!started) return;
+          if (!proj) {
+            notFound = true;
+            items = [];
+            emit();
+            return;
+          }
+          project = proj;
+          emit();
+          const gallery = await fetchProjectGallery(proj.id);
+          if (started) { items = gallery; emit(); }
+        } catch (e) {
+          if (!started) return;
+          items = [];
+          error = e instanceof Error ? e.message : String(e);
+          emit();
+        }
+      })();
+    },
+    stop() { started = false; },
+  };
+}