@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-headless-fast/references/members/seed/SEED.md

@@ -0,0 +1,39 @@
+# Members — seeding
+
+**Members self-register — there is no member content to seed.** The Wix login page registers
+or logs in members at runtime; creating members at build time is intentionally out of scope
+(a headless run must never stall on an interactive login, and Create Member needs an
+elevated credential).
+
+What `seed-members.mjs` does is the one build-time setup the vertical needs: **install the
+Wix Members Area app** — the *profile* layer. Identity (log in / log out / "logged-in vs
+not" gating) needs no install; profile data does: without the app, `getCurrentMember()`
+returns nothing for a logged-in member and the account page can't render who they are.
+
+```bash
+# from the project root (where wix.config.json lives) — the plan file is optional:
+node <SKILL_ROOT>/references/members/seed/seed-members.mjs
+```
+
+```json
+{ "installMembersArea": true }
+```
+
+- `installMembersArea` — default `true`; set `false` only when the run needs pure
+  "logged-in vs not" gating and will never display member data.
+- Re-running is safe: an already-installed app is recorded in the result JSON
+  (`membersAreaInstall.note`), never thrown.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Escape hatch — individual functions
+`setupMembers` composes the exported steps — `installMembersAreaApp`, plus `makeCtx()` —
+import them for a partial re-run.
+
+## Reference
+The appDefId and the identity/profile split come from
+`wix-headless/references/SETUP.md` (§ members). Signup security (email verification, owner
+approval, reCAPTCHA) is dashboard-governed — never seeded. If a run's prompt explicitly needs
+a pre-created member (rare), the admin Create Member shape is in the live Wix API reference —
+read it via the `wix-docs` skill; don't guess it here.

package/skills/wix-headless-fast/references/members/seed/seed-members.mjs

@@ -0,0 +1,94 @@
+// Members seed — a BUILD-TIME script, never shipped in the app. Run from the project root
+// (where wix.config.json lives); the plan file is optional:
+//
+//   node <SKILL_ROOT>/references/members/seed/seed-members.mjs [plan.json]
+//
+// Members SELF-REGISTER — there is no member content to create (see SEED.md). The one
+// build-time setup this vertical needs is installing the Wix Members Area app, which serves
+// member PROFILE data: without it getCurrentMember() returns nothing for a logged-in member,
+// so the account page can't render who they are. Identity alone (log in / log out / gating)
+// needs no install. Prints a JSON result to stdout.
+//
+// Plan shape (see SEED.md): { "installMembersArea": true }   // default true
+//
+// Seeding is ADDITIVE — never deletes or overwrites existing content. Authoritative source:
+// wix-headless/references/SETUP.md § members (the appDefId and the identity/profile split).
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+const API = "https://www.wixapis.com";
+// The Wix Members Area app (the profile layer). Not in the "Apps Created by Wix" table —
+// the GUID comes from the App Market listing; recorded in wix-headless/references/SETUP.md.
+// Installing it pulls in its Site-Members dependency automatically.
+const MEMBERS_AREA_APP_ID = "14cc59bc-f0b7-15b8-e1c7-89ce41d0e0c9";
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
+  const siteId = config.siteId ?? config.projectId;
+  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
+  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
+    encoding: "utf8",
+    cwd,
+  }).trim();
+  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
+  return { token, siteId };
+}
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  const res = await fetch(API + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  return json;
+}
+
+// ---- operations ----------------------------------------------------------------------------------
+
+/**
+ * Install the Wix Members Area app (idempotent in effect: re-running against a site that
+ * already has it errors — recorded in the result, not thrown, since "already installed" and
+ * a real failure aren't distinguishable from the response).
+ * docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+ */
+export async function installMembersAreaApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: MEMBERS_AREA_APP_ID, enabled: true },
+    } });
+    return { requested: true, note: null };
+  } catch (e) {
+    return { requested: false, note: String(e.message).slice(0, 300) };
+  }
+}
+
+/** ONE-CALL seed: install the Members Area app (the profile layer). The default path. */
+export async function setupMembers(ctx, { installMembersArea = true } = {}) {
+  return {
+    membersAreaAppId: MEMBERS_AREA_APP_ID,
+    membersAreaInstall: installMembersArea ? await installMembersAreaApp(ctx) : { skipped: true },
+    membersCreated: 0, // members self-register — never created at build time
+  };
+}
+
+// ---- CLI entry ----------------------------------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const planPath = process.argv[2];
+  const plan = planPath ? JSON.parse(readFileSync(planPath, "utf8")) : {};
+  const ctx = makeCtx();
+  setupMembers(ctx, plan)
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}

package/skills/wix-headless-fast/references/portfolio/INSTRUCTIONS.md

@@ -0,0 +1,134 @@
+# Portfolio — playbook
+
+The portfolio machinery ships as files — collections, projects, the per-project media gallery
+(image AND video items), typed end-to-end. Portfolio is **read-only**: no cart, no checkout,
+no `@wix/ecom`. **The presentation is yours**: you design and implement the collection card,
+the project card + grid, the project-detail gallery, and the home page on the shipped
+hooks/DTOs, plus the brand. You never write read logic; you never skip designing.
+
+## The file map (deployed into `src/`)
+
+**Don't read the shipped files** — this table and the contracts below are everything you
+need. Open a shipped file's source only on a real fallback (runtime error / uncovered field),
+or to read a reference component's pattern.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` · `wix/media.ts` · `wix/money.ts` | shared auth seam + helpers (deploy configures; nothing to set) |
+| `wix/portfolio/types.ts` | the DTOs (`CollectionSummary`, `ProjectSummary`, `ProjectDetail`, `ProjectDetailRow`, `GalleryItem`) — contracts below |
+| `wix/portfolio/portfolio.ts` | `fetchCollections`, `fetchCollectionBySlug`, `fetchProjects`, `fetchProjectBySlug`, `fetchProjectGallery` |
+| `hooks/portfolio/useCollections.ts` | collections gallery — contract below |
+| `hooks/portfolio/useCollectionProjects.ts` | one collection + its projects, by slug — contract below |
+| `hooks/portfolio/useProjectDetail.ts` | one project + its media gallery, by slug — contract below |
+| `components/portfolio/CollectionsView.tsx` (+ `CollectionCard`) · `CollectionProjectsView.tsx` (+ `ProjectCard`) · `ProjectDetailView.tsx` (+ `GalleryMedia`) | **REFERENCE implementations** — correct, plain; build your own instead of shipping them |
+| `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `layouts/SiteLayout.astro` | site chrome — **yours to brand** (keep the `seo-tags` slot + global.css import). If another vertical is also deployed, its layout won — add a Portfolio nav link there |
+| `pages/portfolio.astro` | SSR collections gallery — **keep the frontmatter**, swap the island import to YOUR component |
+| `pages/portfolio/[slug].astro` | SSR collection page (header + projects) — **keep the frontmatter**, swap the island import |
+| `pages/projects/[slug].astro` | SSR project detail + gallery — **keep the frontmatter**, swap the island import. Portfolio has no documented Wix SEO item type, so these pages carry plain `<title>`/`<meta>` from the DTO (no `wixMetadata`/`<SEO.Tags>`) |
+
+## What you build — the design job
+
+1. **The collection card + gallery surface** — your tile (cover, title, description) and
+   rhythm, with skeletons while loading and an honest empty state — on `useCollections`.
+2. **The project card + collection page** — the collection header and your project grid — on
+   `useCollectionProjects` (route a not-found state off `notFound`, never off a transient
+   null).
+3. **The project-detail surface** — title/description, the `details` rows (text or link, as
+   given), and the media gallery: `kind: "image"` → `<img>`; `kind: "video"` → `<video>` with
+   `videoUrl` + `imageUrl` as poster; wrap in a link when `linkUrl` is set; empty gallery →
+   the project cover when it exists, else an honest empty note — on `useProjectDetail`.
+4. **The home page** — hero, featured collections or projects (fetch in frontmatter → your
+   components), brand story.
+
+Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
+Style everything with Tailwind utilities on the tokens.
+
+### The contracts your components consume
+
+```ts
+// CollectionSummary (tiles): { id, slug, title, description, imageUrl /* "" when none */ }
+// ProjectSummary (tiles): { id, slug, title, description, imageUrl /* cover or video poster */,
+//   collectionIds: string[] }
+// ProjectDetail adds: details: [{ label, text, url|null, target|null /* url set → link row */ }]
+// GalleryItem: { id, kind: "image"|"video", title, description,
+//   imageUrl /* image, or the video's poster; may be "" */,
+//   videoUrl /* video only, else null */, linkUrl|null, linkTarget|null }
+
+// useCollections({ initialCollections? }) →
+// { collections: CollectionSummary[]|null /* null = loading → skeletons */, error }
+
+// useCollectionProjects(slug, { initialCollection?, initialProjects? }) →
+// { collection: CollectionSummary|null,       // null while loading AND when notFound
+//   notFound,                                 // the real 404 signal
+//   projects: ProjectSummary[]|null,          // null = loading → skeletons
+//   error }
+
+// useProjectDetail(slug, { initialProject?, initialItems? }) →
+// { project: ProjectDetail|null, notFound,
+//   items: GalleryItem[]|null,                // dashboard order; null = loading
+//   error }
+```
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the
+   existing layout instead if another vertical is deployed).
+2. Write your components under `src/components/portfolio/` (new names — don't overwrite the
+   references), swap the island imports in `pages/portfolio.astro`,
+   `pages/portfolio/[slug].astro`, and `pages/projects/[slug].astro`. Islands are
+   `client:load` with the SSR props. **Author your surfaces in as few messages as possible** —
+   batch multiple Writes per message.
+3. Write `pages/index.astro` (home) — it exists from the scaffold; Read it before overwriting.
+
+### Wiring — React SPA (Vite etc.)
+
+Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite
+plugins — deploy added the dep). Routes: `/portfolio` → your gallery; `/portfolio/:slug` →
+your collection page on `useCollectionProjects(slug)`; `/projects/:slug` → your detail
+surface on `useProjectDetail(slug)`.
+
+## Hard rules
+
+- **Reads only through the shipped exports** — they filter `hidden`, sort collections by the
+  owner's `sortOrder` (projects have none — list order), and resolve every `wix:image://` /
+  `wix:video://` value. Never hand-build a `wixstatic.com` URL, never render a raw media
+  string into `src`.
+- **This vertical sells nothing** — no cart, no checkout, no `@wix/ecom`/`@wix/redirects`
+  imports. A "contact about this project" CTA is a link, not a purchase flow.
+- **Route not-found off `notFound`**, and surface `error` — a transient `null` is loading,
+  not a 404.
+- **Render `details` rows as given** (text or link per row); don't invent metadata.
+- **Gallery items branch on `kind`** — an image never gets a `<video>` tag and vice versa;
+  nothing renderable → skip the item, never a broken tag.
+- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+- Live data or an honest empty state — never mock collections, projects, or media.
+
+## Point the user to their dashboard
+
+Give the owner the dashboard link — the deploy step's JSON printed `dashboardUrl`; append
+`/wix-portfolio/projects` for Portfolio management (Projects and Collections are tabs on that
+one page: Projects adds projects and their media galleries; Collections groups them).
+
+## Seeding
+
+Per `seed/SEED.md` — plain-data `plan.json` into `seed-portfolio.mjs` from the project root.
+Seed collections + projects that exercise the UI (covers on everything, 2–3 gallery images
+per project, `details` rows on a couple of projects). A fresh install ships sample content —
+seeding never deletes it; ask the owner before any cleanup.
+
+## Verify (before declaring done)
+
+- [ ] `/portfolio` renders live collections SSR (view-source shows titles) through YOUR
+      components; empty portfolio shows your honest empty state.
+- [ ] A collection page lists its projects (and only its); an unknown slug 404s.
+- [ ] A project page renders the gallery in order, the `details` rows, and — if any project
+      has a video item — a playing `<video>` with poster.
+- [ ] Card/grid/detail/home are YOUR designs on the tokens; data-layer/hook files unedited.
+- [ ] No `@wix/ecom` import anywhere; no mocked content.
+- [ ] Dashboard link handed to the owner.

package/skills/wix-headless-fast/references/portfolio/app/components/portfolio/CollectionProjectsView.tsx

@@ -0,0 +1,110 @@
+// REFERENCE collection page: collection header + its projects grid on the @theme tokens.
+// Correct and complete; per the skill's model you design and build your own on
+// useCollectionProjects (ProjectCard is reusable for an all-work grid or a home strip).
+import type { ComponentType, ReactNode } from "react";
+import { useCollectionProjects } from "../../hooks/portfolio/useCollectionProjects";
+import type { CollectionSummary, ProjectSummary } from "../../wix/portfolio/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+export interface ProjectCardProps {
+  project: ProjectSummary;
+  projectHref?: (slug: string) => string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+export function ProjectCard({
+  project,
+  projectHref = (slug) => `/projects/${slug}`,
+  LinkComponent = PlainLink,
+}: ProjectCardProps) {
+  return (
+    <LinkComponent href={projectHref(project.slug)} className="group block no-underline">
+      <div className="relative aspect-[4/3] overflow-hidden rounded-lg bg-secondary">
+        {project.imageUrl && (
+          <img
+            src={project.imageUrl}
+            alt={project.title}
+            loading="lazy"
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
+          />
+        )}
+      </div>
+      <p className="mt-3 text-sm font-medium text-foreground">{project.title}</p>
+      {project.description && (
+        <p className="mt-0.5 text-xs text-muted-foreground">{project.description}</p>
+      )}
+    </LinkComponent>
+  );
+}
+
+export interface CollectionProjectsViewProps {
+  slug: string;
+  initialCollection?: CollectionSummary;
+  initialProjects?: ProjectSummary[];
+  emptyMessage?: string;
+  projectHref?: ProjectCardProps["projectHref"];
+  LinkComponent?: ComponentType<LinkLikeProps>;
+  CardComponent?: ComponentType<ProjectCardProps>;
+}
+
+export default function CollectionProjectsView({
+  slug,
+  initialCollection,
+  initialProjects,
+  emptyMessage = "No projects in this collection yet.",
+  projectHref,
+  LinkComponent,
+  CardComponent = ProjectCard,
+}: CollectionProjectsViewProps) {
+  const { collection, notFound, projects, error } = useCollectionProjects(slug, {
+    initialCollection,
+    initialProjects,
+  });
+
+  if (notFound) {
+    return <p className="py-16 text-center text-muted-foreground">Collection not found.</p>;
+  }
+
+  return (
+    <div>
+      <header className="mb-8">
+        <h1 className="text-2xl font-semibold tracking-tight">
+          {collection ? collection.title : <span className="inline-block h-7 w-48 animate-pulse rounded bg-secondary" />}
+        </h1>
+        {collection?.description && (
+          <p className="mt-2 max-w-2xl text-muted-foreground">{collection.description}</p>
+        )}
+      </header>
+      {error && <p className="mb-4 text-sm text-red-600">{error}</p>}
+      {projects === null ? (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3" aria-busy="true">
+          {Array.from({ length: 6 }, (_, i) => (
+            <div key={i}>
+              <div className="aspect-[4/3] animate-pulse rounded-lg bg-secondary" />
+              <div className="mt-3 h-3.5 w-2/3 animate-pulse rounded bg-secondary" />
+            </div>
+          ))}
+        </div>
+      ) : projects.length === 0 ? (
+        <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>
+      ) : (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
+          {projects.map((p) => (
+            <CardComponent key={p.id} project={p} projectHref={projectHref} LinkComponent={LinkComponent} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/portfolio/app/components/portfolio/CollectionsView.tsx

@@ -0,0 +1,90 @@
+// REFERENCE gallery surface: collections grid on the @theme tokens.
+// Correct and complete; per the skill's model you design and build your own on useCollections.
+import type { ComponentType, ReactNode } from "react";
+import { useCollections } from "../../hooks/portfolio/useCollections";
+import type { CollectionSummary } from "../../wix/portfolio/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+export interface CollectionCardProps {
+  collection: CollectionSummary;
+  collectionHref?: (slug: string) => string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+export function CollectionCard({
+  collection,
+  collectionHref = (slug) => `/portfolio/${slug}`,
+  LinkComponent = PlainLink,
+}: CollectionCardProps) {
+  return (
+    <LinkComponent href={collectionHref(collection.slug)} className="group block no-underline">
+      <div className="relative aspect-[4/3] overflow-hidden rounded-lg bg-secondary">
+        {collection.imageUrl && (
+          <img
+            src={collection.imageUrl}
+            alt={collection.title}
+            loading="lazy"
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
+          />
+        )}
+      </div>
+      <p className="mt-3 text-sm font-medium text-foreground">{collection.title}</p>
+      {collection.description && (
+        <p className="mt-0.5 text-xs text-muted-foreground">{collection.description}</p>
+      )}
+    </LinkComponent>
+  );
+}
+
+export interface CollectionsViewProps {
+  initialCollections?: CollectionSummary[];
+  emptyMessage?: string;
+  collectionHref?: CollectionCardProps["collectionHref"];
+  LinkComponent?: ComponentType<LinkLikeProps>;
+  CardComponent?: ComponentType<CollectionCardProps>;
+}
+
+export default function CollectionsView({
+  initialCollections,
+  emptyMessage = "No collections yet — check back soon.",
+  collectionHref,
+  LinkComponent,
+  CardComponent = CollectionCard,
+}: CollectionsViewProps) {
+  const { collections, error } = useCollections({ initialCollections });
+
+  return (
+    <div>
+      {error && <p className="mb-4 text-sm text-red-600">{error}</p>}
+      {collections === null ? (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3" aria-busy="true">
+          {Array.from({ length: 6 }, (_, i) => (
+            <div key={i}>
+              <div className="aspect-[4/3] animate-pulse rounded-lg bg-secondary" />
+              <div className="mt-3 h-3.5 w-2/3 animate-pulse rounded bg-secondary" />
+            </div>
+          ))}
+        </div>
+      ) : collections.length === 0 ? (
+        <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>
+      ) : (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
+          {collections.map((c) => (
+            <CardComponent key={c.id} collection={c} collectionHref={collectionHref} LinkComponent={LinkComponent} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,115 @@
+// 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. GalleryMedia's kind branching is the load-bearing
+// part — keep it (or its logic) in whatever you build.
+import type { ReactNode } from "react";
+import { useProjectDetail } from "../../hooks/portfolio/useProjectDetail";
+import type { GalleryItem, ProjectDetail } from "../../wix/portfolio/types";
+
+/** One gallery item: image, or video with poster. Nothing renderable → null (never a broken tag). */
+export function GalleryMedia({ item }: { item: GalleryItem }) {
+  if (item.kind === "video" && item.videoUrl) {
+    return (
+      <video
+        src={item.videoUrl}
+        poster={item.imageUrl || undefined}
+        controls
+        playsInline
+        className="block w-full rounded-lg bg-secondary"
+      />
+    );
+  }
+  if (item.imageUrl) {
+    return (
+      <img src={item.imageUrl} alt={item.title} loading="lazy" className="block w-full rounded-lg" />
+    );
+  }
+  return null;
+}
+
+function MaybeLink({ item, children }: { item: GalleryItem; children: ReactNode }) {
+  return item.linkUrl ? (
+    <a href={item.linkUrl} target={item.linkTarget ?? undefined} rel="noopener">
+      {children}
+    </a>
+  ) : (
+    <>{children}</>
+  );
+}
+
+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-red-600">{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 src={project.imageUrl} 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">
+              <MaybeLink item={item}>
+                <GalleryMedia item={item} />
+              </MaybeLink>
+              {item.title && (
+                <figcaption className="mt-1.5 text-sm text-muted-foreground">{item.title}</figcaption>
+              )}
+            </figure>
+          ))}
+        </div>
+      )}
+    </article>
+  );
+}

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

@@ -0,0 +1,59 @@
+// One collection's header + its projects, by slug. 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, useState } from "react";
+import { fetchCollectionBySlug, fetchProjects } from "../../wix/portfolio/portfolio";
+import type { CollectionSummary, ProjectSummary } from "../../wix/portfolio/types";
+
+export interface UseCollectionProjectsOptions {
+  initialCollection?: CollectionSummary;
+  initialProjects?: ProjectSummary[];
+}
+
+export interface UseCollectionProjects {
+  /** 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 function useCollectionProjects(
+  slug: string,
+  { initialCollection, initialProjects }: UseCollectionProjectsOptions = {},
+): UseCollectionProjects {
+  const [collection, setCollection] = useState<CollectionSummary | null>(initialCollection ?? null);
+  const [notFound, setNotFound] = useState(false);
+  const [projects, setProjects] = useState<ProjectSummary[] | null>(initialProjects ?? null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (initialCollection && initialProjects) return;
+    let alive = true;
+    (async () => {
+      try {
+        const col = initialCollection ?? (await fetchCollectionBySlug(slug));
+        if (!alive) return;
+        if (!col) {
+          setNotFound(true);
+          setProjects([]);
+          return;
+        }
+        setCollection(col);
+        const projs = await fetchProjects({ collectionId: col.id });
+        if (alive) setProjects(projs);
+      } catch (e) {
+        if (!alive) return;
+        setProjects([]);
+        setError(e instanceof Error ? e.message : String(e));
+      }
+    })();
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [slug]);
+
+  return { collection, notFound, projects, error };
+}