@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/portfolio/project/src/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/project/src/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/project/src/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; },
+  };
+}

package/skills/wix-headless-templates/portfolio/project/src/wix/portfolio/types.ts

@@ -0,0 +1,55 @@
+// Portfolio DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or across server/client boundaries. Images are
+// resolved https URLs; videos are playable mp4 URLs with a poster frame.
+
+/** A collection as the gallery grid needs it. */
+export interface CollectionSummary {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  /** Resolved https URL ("" when the collection has no cover). */
+  imageUrl: string;
+}
+
+/** A project as a grid tile needs it. */
+export interface ProjectSummary {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  /** Cover image; a video-covered project falls back to its poster frame ("" when neither). */
+  imageUrl: string;
+  /** The collections this project belongs to (a project can be in several). */
+  collectionIds: string[];
+}
+
+/** One row of a project's metadata (Role, Year, Client…): plain text or an outbound link. */
+export interface ProjectDetailRow {
+  label: string;
+  text: string;
+  /** Non-null → render the row's text as a link. */
+  url: string | null;
+  /** Link rows only: "_blank" | "_self". */
+  target: string | null;
+}
+
+/** A project as the detail page needs it. */
+export interface ProjectDetail extends ProjectSummary {
+  details: ProjectDetailRow[];
+}
+
+/** One media item of a project's gallery (dashboard order). */
+export interface GalleryItem {
+  id: string;
+  kind: "image" | "video";
+  title: string;
+  description: string;
+  /** image: the resolved image. video: the poster frame ("" when the video has none). */
+  imageUrl: string;
+  /** video only: playable mp4 URL. */
+  videoUrl: string | null;
+  /** Optional owner-attached outbound link for this item. */
+  linkUrl: string | null;
+  linkTarget: string | null;
+}

package/skills/wix-headless-templates/portfolio/project/src/wix/sdk.ts

@@ -0,0 +1,89 @@
+// The one auth seam for every Wix SDK call in this app. Copy as-is; do not rewrite.
+//
+// Two modes, switched by WIX_CLIENT_ID in ./config:
+//   null (ambient)  — a Wix-managed Astro project: `@wix/astro` authenticates raw SDK module
+//                     calls automatically, server-side AND in client islands. `wixModule()`
+//                     returns the module untouched.
+//   string (manual) — any other React setup (Vite SPA, non-Astro): one shared client is built
+//                     with OAuthStrategy, and `wixModule()` returns the module bound to it.
+//                     The strategy self-manages visitor tokens on every call (mints on first
+//                     use, renews on expiry) and persists them through the storage below.
+//
+// The visitor token IS the identity of the current cart / member session, so in manual mode
+// tokens persist to localStorage — never re-minted per load (a fresh anonymous mint is a NEW
+// visitor and silently empties the cart).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
+// docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
+import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import { fetchWithAuth as ambientFetch } from "@wix/sdk/context";
+import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
+import { WIX_CLIENT_ID } from "./config";
+
+const STORAGE_KEY = `wix-session-${WIX_CLIENT_ID ?? "ambient"}`;
+
+function browserTokenStorage(): TokenStorage {
+  return {
+    getTokens(): Tokens {
+      if (typeof window !== "undefined") {
+        try {
+          const raw = window.localStorage.getItem(STORAGE_KEY);
+          if (raw) return JSON.parse(raw) as Tokens;
+        } catch {
+          /* disabled/corrupt storage — fall through to empty */
+        }
+      }
+      return EMPTY_TOKENS;
+    },
+    setTokens(tokens: Tokens): void {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+      } catch {
+        /* storage full/disabled — the session just won't survive a reload */
+      }
+    },
+  };
+}
+
+const client = WIX_CLIENT_ID
+  ? createClient({
+      auth: OAuthStrategy({
+        clientId: WIX_CLIENT_ID,
+        tokenStorage: browserTokenStorage(),
+      }),
+    })
+  : null;
+
+/**
+ * Bind an SDK module to this app's auth. Usage (identical in both modes):
+ *   import { productsV3 } from "@wix/stores";
+ *   const products = wixModule(productsV3);
+ *   await products.queryProducts(...)
+ */
+export function wixModule<T>(module: T): T {
+  // The cast bridges the SDK's internal Descriptors constraint; the in/out type is identical.
+  return client
+    ? (client.use(module as unknown as Record<string, unknown>) as unknown as T)
+    : module;
+}
+
+/**
+ * An authenticated fetch of a Wix REST endpoint under the SAME auth as the SDK modules (ambient
+ * on managed Astro, the shared client elsewhere) — for the few APIs whose generated SDK module is
+ * too heavy to bundle (the Forms schema module alone is 15 MB: server-side it pushes a Wix
+ * deploy past its size limit, client-side every visitor downloads it). Same visitor identity,
+ * same token, no second mint. `path` is the wixapis.com path; returns the raw Response.
+ */
+export function wixFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = path.startsWith("http") ? path : `https://www.wixapis.com${path}`;
+  return client ? client.fetchWithAuth(url, init) : ambientFetch(url, init);
+}
+
+/**
+ * The shared data client's manual-mode auth strategy, or null under ambient auth. The
+ * Members vertical deliberately owns a separate explicit client for its custom in-app login;
+ * app code reads that session through the members hooks instead.
+ */
+export function wixAuth(): IOAuthStrategy | null {
+  return client ? client.auth : null;
+}

package/skills/wix-headless-templates/portfolio/project/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/skills/wix-headless-templates/portfolio/rest/portfolio.ts

@@ -0,0 +1,75 @@
+// Portfolio reads over REST — the twin of app/wix/portfolio/portfolio.ts. Same exports, same DTOs;
+// the rules and mappers come from portfolio-core (the SAME file the SDK transport uses, deployed
+// flat next to this one by deploy.mjs --stack static), so this file is only the transport: one
+// fetch with a literal URL and body per function. Every call here is a public read, safe from a
+// browser with a visitor token. Porting: keep the paths, keep the bodies, port the core once.
+// 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/collections/query-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/projects/query-projects.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/list-project-items.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import {
+  galleryItems,
+  visibleCollection,
+  visibleCollections,
+  visibleProject,
+  visibleProjects,
+  type Raw,
+  type VideoSrc,
+} from "./portfolio-core.js";
+import type { CollectionSummary, GalleryItem, ProjectDetail, ProjectSummary } from "./types.js";
+
+// REST never returns the bare wix:video:// string — videoInfo arrives as { resolutions, posters },
+// which the core reads directly. A string here has no resolver on this transport → dropped.
+const videoSrc: VideoSrc = () => null;
+
+/** Visible collections in dashboard order.  GET /portfolio/v1/collections?paging.limit=N → { collections } */
+export async function fetchCollections({ limit = 100 } = {}): Promise<CollectionSummary[]> {
+  const res = await wixRequest<Raw>("/portfolio/v1/collections", { method: "GET", query: { "paging.limit": String(limit) } });
+  return visibleCollections((res?.collections ?? []) as Raw[], imgSrc);
+}
+
+/**
+ * One visible collection by URL slug; null when missing or hidden → a real 404.
+ * POST /portfolio/v1/collections/query  { query: { filter: { slug }, cursorPaging: { limit: 1 } } } → { collections }
+ */
+export async function fetchCollectionBySlug(slug: string): Promise<CollectionSummary | null> {
+  const res = await wixRequest<Raw>("/portfolio/v1/collections/query", {
+    body: { query: { filter: { slug }, cursorPaging: { limit: 1 } } },
+  });
+  return visibleCollection(res?.collections?.[0] as Raw | undefined, imgSrc);
+}
+
+/** Visible projects in list order, optionally one collection's.  GET /portfolio/v1/projects?paging.limit=N → { projects } */
+export async function fetchProjects({
+  collectionId,
+  limit = 100,
+}: { collectionId?: string; limit?: number } = {}): Promise<ProjectSummary[]> {
+  const res = await wixRequest<Raw>("/portfolio/v1/projects", { method: "GET", query: { "paging.limit": String(limit) } });
+  return visibleProjects((res?.projects ?? []) as Raw[], collectionId, imgSrc, videoSrc);
+}
+
+/**
+ * One visible project with its details rows by URL slug; null when missing or hidden.
+ * POST /portfolio/v1/projects/query  { query: { filter: { slug }, cursorPaging: { limit: 1 } } } → { projects }
+ */
+export async function fetchProjectBySlug(slug: string): Promise<ProjectDetail | null> {
+  const res = await wixRequest<Raw>("/portfolio/v1/projects/query", {
+    body: { query: { filter: { slug }, cursorPaging: { limit: 1 } } },
+  });
+  return visibleProject(res?.projects?.[0] as Raw | undefined, imgSrc, videoSrc);
+}
+
+/**
+ * A project's gallery in dashboard order; IMAGE and VIDEO items only.
+ * GET /portfolio/v1/projectItems/{projectId}/items?paging.limit=100 → { items }
+ */
+export async function fetchProjectGallery(projectId: string): Promise<GalleryItem[]> {
+  const res = await wixRequest<Raw>(`/portfolio/v1/projectItems/${encodeURIComponent(projectId)}/items`, {
+    method: "GET",
+    query: { "paging.limit": "100" },
+  });
+  return galleryItems((res?.items ?? []) as Raw[], imgSrc, videoSrc);
+}

package/skills/wix-headless-templates/portfolio/seed/SEED.md

@@ -0,0 +1,86 @@
+# Portfolio — seeding
+
+Seed by **running `seed-portfolio.mjs` with a plan file** — don't hand-write the REST calls.
+The script mints its own site token via the Wix CLI (logged-in session + `wix.config.json`
+required), installs the Portfolio app if needed, and creates everything in the right order:
+collections first (a project's `collectionIds` are NOT validated — a wrong id silently
+orphans the project), then projects, gallery items, and covers.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/portfolio/seed/seed-portfolio.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 2 collections × 2 projects
+each** (the seed shows the shape; the owner adds the rest in the dashboard) and make them
+exercise the UI: every collection and project gets a cover, every project gets 2–3 gallery
+`items` (a portfolio without images looks broken), and a couple of projects get `details`
+rows (Role, Year, Client…).
+
+```json
+{
+  "collections": [
+    { "title": "Brand Identity", "description": "Logo systems and visual identities.",
+      "coverImageUrl": "https://…" },
+    { "title": "Editorial", "description": "Print and digital editorial design.",
+      "coverImageUrl": "https://…" }
+  ],
+  "projects": [
+    { "title": "Northwind Rebrand", "description": "Full identity refresh for a logistics firm.",
+      "collection": "Brand Identity",
+      "details": [ { "label": "Role", "text": "Brand & Art Direction" }, { "label": "Year", "text": "2025" } ],
+      "coverImageUrl": "https://…",
+      "items": [
+        { "sortOrder": 1, "title": "Logo system", "imageUrl": "https://…" },
+        { "sortOrder": 2, "title": "Stationery", "imageUrl": "https://…" }
+      ] },
+    { "title": "Harbor Coffee", "description": "Packaging and label suite.",
+      "collection": "Brand Identity", "coverImageUrl": "https://…",
+      "items": [ { "sortOrder": 1, "title": "Label set", "imageUrl": "https://…" } ] },
+    { "title": "Field Notes Quarterly", "description": "Magazine layout and typography.",
+      "collection": "Editorial", "coverImageUrl": "https://…",
+      "items": [ { "sortOrder": 1, "title": "Spread", "imageUrl": "https://…" } ] },
+    { "title": "City Guides", "description": "Travel series covers.",
+      "collection": "Editorial", "coverImageUrl": "https://…",
+      "items": [ { "sortOrder": 1, "title": "Covers", "imageUrl": "https://…" } ] }
+  ]
+}
+```
+
+- `collection` — a collection **title from this plan**; resolved to its created id. A project
+  without one belongs to no collection (reachable only from an all-projects list).
+- `details` — optional `[{ label, text }]` rows; render on the project page. Omit for none.
+- Every image field's default is a prompt (`coverImagePrompt` / `items[].imagePrompt` —
+  AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
+  aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied
+  use a path (`coverImagePath` / `items[].imagePath` — a file on this machine, uploaded to
+  Wix Media) or a url (`coverImageUrl` / `items[].imageUrl` — their own hosted URL; verify it
+  with `curl -sI` → 200) — never a stock-photo or guessed URL. All images —
+  covers and gallery items alike — resolve in one parallel wave and never block the seed; a
+  failed image skips just that item/cover. The **cover** is the
+  listing thumbnail; **items** are the detail-page gallery — separate entities, both wanted.
+  If a project has only a cover, reuse its url as item 1 so the gallery isn't empty.
+- `sortOrder` (1, 2, 3…) sets the gallery render order.
+- `hidden` defaults to shown — omit it; send `hidden: true` only to hide an entity.
+- Gallery items seed as images only; the owner adds videos in the dashboard.
+- A fresh Portfolio install ships sample content ("My Portfolio" + sample projects). **Seeding
+  is additive — never delete or overwrite existing content**; if removing the samples seems
+  wanted, ask the owner first.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For a portfolio, each project the
+user lists is one entry. Its title becomes `title`; its category or series becomes `collection`
+(and joins the `collections` list); client, role, year and similar facts become `details`; their
+cover image becomes `coverImageUrl`; their project images become `items` in the order given. A
+photo with no caption gets its file name as `title`.
+
+## Escape hatch — individual functions
+`setupPortfolio` composes exported steps — `installPortfolioApp`, `createCollections`,
+`createProjects`, `importImage`, `attachProjectCovers`, `attachCollectionCovers`,
+`createProjectItems`, `listCollections`, `listProjects`, plus `makeCtx()` — import them only
+for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; every call the script
+makes carries a `docs:` line with its reference page.