@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -1,111 +1,240 @@
+# Wix Portfolio — ready-made client
 
-# Wix Portfolio Skill
+The portfolio client is **shipped as real files**, not snippets to regenerate. It's a complete
+collections gallery + collection page + project detail (media gallery + `details[]` rows), styled
+with your app's design tokens (base44's `src/index.css` — the shadcn palette the design phase already
+set). The install step copied it into `src/`; you wire the routes — you generate almost none of the
+read/render code (return-object destructuring, `item.type` media branching, the `details[]` link
+shape all ship and are correct).
 
-> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/portfolio/wix-portfolio.js`. Copy **both** into your app's `src/rest/` side by side — the helper does `import { wixApiRequest } from "./wix-client.js"`, so they must land in the same folder.
+Talks to Wix directly over the public `WIX_CLIENT_ID` (anonymous visitor tokens). Portfolio is
+**read-only**: never mock projects, never invent media — render live Wix data or the shipped empty
+state. The content tree is **Collection → Project → Project Item (image/video)**.
 
-Builds a real, client-only Wix portfolio showcase. The browser talks to Wix directly over a
-public `WIX_CLIENT_ID`. Portfolio is **read-only**: never mock projects, never invent media,
-and always render live Wix data (or an honest empty state). The content tree is
-**Collection → Project → Project Item (image/video)**.
+## Prerequisites
+- The site's **Wix Portfolio** is the read target. It's installed and seeded separately (see
+  **Seeding** below), in parallel with this build — so it may be empty at build time; the client
+  renders the shipped empty state until collections and projects land.
+- The public headless **`WIX_CLIENT_ID`** from your prompt (visitor-facing, safe to hardcode/commit).
+- If the read calls return `403`/`428` before content is published, the Portfolio app or its content
+  may not be live yet — a **Wix dashboard step the owner completes**, out of scope here. Flag it and
+  continue; don't fall back to mock data.
 
-## When to use
-- User wants a Wix portfolio / showcase site or asks to "connect Wix Portfolio".
-- Replacing placeholder/mock galleries with live Wix Portfolio data.
-- Adding a collections gallery, project grids, or a project detail page (media gallery +
-  details/links) over an existing Wix Portfolio.
+## STEP 1 — The client is already in `src/`
+The install step (base44.md STEP 1) deployed the whole portfolio UI client + REST scaffolds into
+`src/` (imports use the `@/` alias → `src/`). Here's every file and what it is — **this is your map,
+so you don't need to open them:**
 
-## Prerequisites
-1. A Wix site with **Wix Portfolio installed and content already added** — at least one
-   collection with projects, and projects with items (this skill does NOT provision; it is
-   read-only over the content).
-2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the Wix
-   Business Manager surfaces a copyable prompt with the id filled in — see the router `SKILL.md`).
-   Paste it into `src/rest/wix-client.js` in place of the placeholder. It is a visitor-facing
-   credential (it only mints anonymous visitor tokens), **not** a secret, so
-   hardcoding/committing it is fine.
-3. If the read calls return `403`/`428` before content is published, the Portfolio app or its
-   content may not be live yet. That is a **Wix dashboard setup step the owner completes** —
-   out of this skill's scope. Flag it and continue; don't fall back to mock data.
-
-## The API (copy as-is; do not re-derive it)
-This skill ships only the REST layer — no UI components. Build the portfolio's UI however the
-project wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
-adjust import paths:
-- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to the
-  id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor refresh token is
-  persisted to localStorage; do not re-mint anonymously per load.
-- `src/rest/wix-portfolio.js` — exports:
-  - **Collections:** `queryCollections`, `getCollectionBySlug`, `countCollections`
-  - **Projects:** `queryProjects`, `queryProjectsByCollection`, `getProjectBySlug`, `getProject`
-  - **Project items (media):** `listProjectItems`
-
-The Collection, Project, and Project Item shapes are documented as JSDoc comments at the top of
-`wix-portfolio.js`. Read them before building the UI — they describe the key fields (cover
-image/video, media resolutions, details rows) and link to the full API reference.
-
-## How to wire it (UI is the project's choice)
-- **Collections gallery (home)** — `queryCollections()` for the listing (visible collections
-  only, in dashboard order); pass `nextCursor` back as `cursor` to load the next page. Render
-  `collection.title`, `collection.description`, and `collection.coverImage.imageInfo.url`. Link
-  each card to a collection page keyed on `collection.slug`.
-- **Collection page** — `getCollectionBySlug(slug)` for the header (returns null on miss — show
-  a not-found state, never invent one). Then `queryProjectsByCollection(collection.id, { limit?, cursor? })`
-  for its project grid; paginate exactly like `queryCollections`.
-- **All-work gallery (optional)** — `queryProjects()` to list every visible project across
-  collections (newest-first); paginate the same way.
-- **Project grid card** — render `project.title` and the cover: use `project.coverImage.imageInfo.url`
-  when present, else the `project.coverVideo.videoInfo.posters[0]` / first
-  `coverVideo.videoInfo.resolutions[]` entry. Link each card to a project page keyed on `project.slug`.
-- **Project detail page** — `getProjectBySlug(slug)` for the header (title, description, and the
-  `details[]` rows: each has a `label` plus either `text` or `link: { text, url, target }`).
-  Then `listProjectItems(project.id)` for the media gallery — render IMAGE items from
-  `image.imageInfo.url` and VIDEO items from the first `video.videoInfo.resolutions[]` entry
-  (with `video.videoInfo.posters[0]` as the poster). Honor each item's optional `link`.
-  - If you already hold a project id (not a slug), use `getProject(projectId)` instead.
-- **Empty state** — if `countCollections()` is 0, show an empty state telling the user to add
-  collections and projects in their Wix dashboard. Never invent projects or media.
-
-## Hard rules (do not violate)
-- ✅ Render only live Wix Portfolio data — collections, projects, and items as returned.
-- ❌ Never mock projects, collections, or media — render live data or the empty state.
-- ❌ Never hand-build Wix Media URLs or page permalinks — use the `url`/`imageInfo.url`/
-  `videoInfo.resolutions[].url` fields Wix returns.
-- ❌ Never invent project details, captions, dates, or testimonials. Show only what the API returns.
-- ❌ Never show `hidden: true` collections or projects to visitors (the helpers already filter
-  `hidden` out — don't add them back).
-- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
-- ✅ Route on `slug` (`getCollectionBySlug` / `getProjectBySlug`); fall back to `getProject(id)`
-  only when you hold a GUID.
-- The helpers fail soft on read: single fetches return `null` on a miss so you render a
-  not-found/empty state rather than a crash — surface that state, don't paper over it with fake data.
-
-## Beyond the snippets
-The snippets cover the common portfolio paths. If you hit a use case they don't cover (e.g.
-collection SEO tags, project watermark settings, portfolio-wide settings, or filtering by a
-field not shown), make the call yourself with `wixApiRequest` — but look up the exact endpoint,
-HTTP method, and request body in the **official Wix API reference** first; never guess:
-- Wix Portfolio API reference: https://dev.wix.com/docs/api-reference/business-solutions/portfolio.md
-- Portfolio Settings (logo, layout, options): https://dev.wix.com/docs/api-reference/business-solutions/portfolio/portfolio-settings/get-portfolio-settings.md
-- API query language (filters, sort, paging): https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md
-
-Keep the snippets as the default for everything they already do; reach for the API reference
-only for the gap.
+| file | what it is |
+|---|---|
+| `hooks/usePortfolioGallery.js` | collections gallery data — first page + count + cursor paging |
+| `hooks/useCollectionProjects.js` | one collection's header + its projects (paged), by slug |
+| `hooks/useProjectDetail.js` | project + its media gallery, by slug (null → not-found) |
+| `components/CollectionCard.jsx`, `CollectionGrid.jsx` | collections listing UI (grid + card, with empty state) |
+| `components/ProjectCard.jsx`, `ProjectGrid.jsx` | projects listing UI (grid + card, with empty state) |
+| `components/ProjectMedia.jsx` | one gallery item — branches on `item.type` (IMAGE / VIDEO) |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `pages/Portfolio.jsx` | collections gallery route (`/portfolio`) |
+| `pages/CollectionPage.jsx` | collection page route (`/collection/:slug`) |
+| `pages/ProjectDetail.jsx` | project detail route (`/project/:slug`) |
+| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-client.js` + `rest/wix-portfolio.js` | REST transport + portfolio read helpers |
+
+They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
+`read_file` the shipped page/component/hook source to inspect it** — the table above says what each
+is and every field shape you need is in the snippets below. Read a shipped file's source **only** on
+a real fallback — a runtime error, or a field the snippets don't cover (see "Fallback only" at the
+end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
+`references/portfolio/app/` → `src/`.)
+
+## STEP 2 — Credentials
+Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
+one place both ids live.
+
+## STEP 3 — Theme (nothing to style on the shipped components)
+The shipped components carry **no palette of their own** — they render from base44's design tokens in
+`src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`, `--muted`,
+`--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`, `text-foreground`,
+`bg-primary`, `text-muted-foreground`, `border-border`, `rounded-lg`, `font-display`). Those tokens
+are **already set to the brand by the design phase**, so the shipped pages are themed with zero work
+here. To adjust the palette, edit `index.css` (`:root` **and** `.dark`) — the base44 way; **never add
+a parallel theme file (e.g. a `theme.css`) or restyle the shipped JSX.** Build the Home/Header you add
+(STEP 4) from the **same** base44 tokens/classes so it matches automatically. A dark brand is just
+base44's dark palette in `index.css` — no per-component work.
+
+## STEP 4 — Wire routes (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+**No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
+`App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
+replace it. Portfolio is read-only with no cross-page state, so there's **no provider to wrap** (no
+cart equivalent) — just the Layout and the routes.
+- Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
+  route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every** page
+  — including the shipped `Portfolio` / `CollectionPage` / `ProjectDetail` — so you **never edit the
+  shipped pages to add a header/footer** (they render inside `<Outlet/>` as-is).
+- **Pin the top chrome as one fixed block.** Put `<WixManageBanner/>` (shipped, preview-only) **above**
+  your `<Header/>` inside a single `position:fixed` top region — the header itself is plain in-flow
+  markup, the region owns the fixing — so banner + header ride together (no scroll drift/gap). Pad
+  the content by the region's measured height so it clears the chrome and self-corrects when the
+  banner is dismissed.
+- Routes under the Layout: `/portfolio` → `Portfolio`, `/collection/:slug` → `CollectionPage`,
+  `/project/:slug` → `ProjectDetail` (all shipped, as-is). **You add `/` → your own Home** page.
+
+```jsx
+import { useRef, useState, useEffect } from "react";
+import { Routes, Route, Outlet } from "react-router-dom";
+import WixManageBanner from "@/components/WixManageBanner";   // shipped, preview-only · default export, no props
+import Portfolio from "@/pages/Portfolio";             // shipped · default export, no props
+import CollectionPage from "@/pages/CollectionPage";   // shipped · default export, no props
+import ProjectDetail from "@/pages/ProjectDetail";     // shipped · default export, no props
+import Home from "@/pages/Home";        // YOU build
+import Header from "@/components/Header";   // YOU build — plain in-flow markup, NOT position:fixed
+import Footer from "@/components/Footer";   // YOU build
+
+function Layout() {
+  const topRef = useRef(null);
+  const [offset, setOffset] = useState(0);
+  useEffect(() => {                                  // measure the fixed region → pad content below it
+    const ro = new ResizeObserver(() => setOffset(topRef.current?.offsetHeight ?? 0));
+    if (topRef.current) ro.observe(topRef.current);
+    return () => ro.disconnect();
+  }, []);
+  return (<>
+    <div ref={topRef} style={{ position: "fixed", top: 0, left: 0, right: 0, zIndex: 50 }}>
+      <WixManageBanner />                    {/* null on the published site / when dismissed */}
+      <Header />                             {/* your brand header, in-flow inside this fixed block */}
+    </div>
+    <div style={{ paddingTop: offset }}>     {/* clears the chrome; shrinks when the banner is dismissed */}
+      <Outlet />                             {/* shipped pages render here, untouched */}
+      <Footer />
+    </div>
+  </>);
+}
+
+<Routes>
+  <Route element={<Layout />}>                                     {/* chrome wraps all */}
+    <Route path="/" element={<Home />} />                          {/* yours */}
+    <Route path="/portfolio" element={<Portfolio />} />            {/* shipped, as-is */}
+    <Route path="/collection/:slug" element={<CollectionPage />} />{/* shipped, as-is */}
+    <Route path="/project/:slug" element={<ProjectDetail />} />    {/* shipped, as-is */}
+  </Route>
+</Routes>
+```
+
+## What you build (not shipped)
+The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the `Layout`
+(STEP 4) so they wrap every route — plus the overall brand story, styled with the same base44
+tokens/classes. **Compose the shipped pieces** — a featured strip is just `queryCollections` (or
+`queryProjects`) + the shipped `CollectionGrid` / `ProjectGrid`; the nav is a link to `/portfolio`:
+
+```jsx
+import { useState, useEffect } from "react";
+import { Link } from "react-router-dom";
+import { queryCollections } from "@/rest/wix-portfolio";
+import CollectionGrid from "@/components/CollectionGrid";
+
+// Responsive header: choose ONE branch with a state flag — do NOT render a desktop nav AND a mobile
+// nav toggled by `hidden md:flex` / `md:hidden`. These navs are inline-styled, and an inline
+// `display` beats a Tailwind class, so `hidden` never applies — BOTH branches render. One branch.
+export function Header() {
+  const [mobile, setMobile] = useState(() => window.innerWidth < 768);
+  useEffect(() => {
+    const onResize = () => setMobile(window.innerWidth < 768);
+    window.addEventListener("resize", onResize);            // keep it reactive to viewport changes
+    return () => window.removeEventListener("resize", onResize);
+  }, []);
+  return (
+    <nav style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+      {/* brand/logo */}
+      {mobile
+        ? <YourMenu />                                       // your hamburger + a link to /portfolio
+        : <div style={{ display: "flex", gap: 24 }}><Link to="/portfolio">Work</Link></div>}
+    </nav>
+  );
+}
+export function Featured() {                                // on your home page
+  const [collections, setCollections] = useState([]);
+  // NB: queryCollections returns { collections, nextCursor } — destructure the array.
+  useEffect(() => { queryCollections({ limit: 6 }).then(({ collections }) => setCollections(collections)); }, []);
+  return <CollectionGrid collections={collections} empty="Collections coming soon." />;
+}
+```
+Everything reads base44's design tokens (`index.css`), so your home/nav match the shipped pages automatically.
+
+**Editing a component and the change doesn't show? It's the preview, not your code.** The dev preview
+can serve a stale module after a write. Before diagnosing a visual bug you just "fixed", do a fresh
+full navigate/reload of the preview and re-check — don't keep rewriting correct code against a stale
+render.
+
+## Using the client from your own UI (hand-built lists, images)
+
+**Every list helper returns an OBJECT, not a bare array** — destructure the named key first, or
+`.map`/`.filter` on the result throws `… is not a function` (the #1 portfolio-listing bug):
+
+```jsx
+// listings — destructure the named array + the cursor:
+const { collections, nextCursor } = await queryCollections({ limit: 24 });   // visible, dashboard order
+const { projects } = await queryProjects({ limit: 24 });                     // all work, newest-first
+const { projects: inCollection } = await queryProjectsByCollection(collectionId, { limit: 24 });
+const { items, total } = await listProjectItems(projectId);                  // gallery — iterate `items`
+
+// single fetches return the object or null (render a not-found/empty state, never invent one):
+const collection = await getCollectionBySlug(slug);
+const project = await getProjectBySlug(slug);   // or getProject(id) when you hold a GUID
+const n = await countCollections();             // number → 0 means the empty state
+
+// media item branches on item.type ("IMAGE" | "VIDEO" | "UNDEFINED") — the shipped ProjectMedia
+// already does this: IMAGE → item.image.imageInfo.url; VIDEO → item.video.videoInfo.resolutions[0].url
+// (poster item.video.videoInfo.posters[0]). details[] rows: { label, text? } OR { label, link: { text, url, target } }.
+
+// An image you render yourself (hero / custom card): make the url https + keep a token bg so a
+// just-generated url that 404s for a second reads as a surface, not a blank block.
+function BrandImage({ url, alt }) {
+  const src = url?.startsWith("//") ? `https:${url}` : url;      // the shipped cards already do this
+  return <div className="bg-card"><img src={src} alt={alt} /></div>;
+}
+```
+
+Cover images live at `collection.coverImage.imageInfo.url` and `project.coverImage.imageInfo.url`
+(projects are a one-of: fall back to `coverVideo.videoInfo.posters[0].url` / `resolutions[0].url`).
+
+Fallback only — when you hit an error or need something not shown here (collection SEO, portfolio
+settings, a field these snippets don't have): read the relevant shipped file under `src/`, or look
+it up via the **`wix-docs`** skill / the Portfolio API reference. Each helper in `wix-portfolio.js`
+links its own reference page inline; the whole area is here:
+- Portfolio (collections, projects, project items): https://dev.wix.com/docs/api-reference/business-solutions/portfolio.md
+
+## Hard rules
+- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
+- Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped
+  `Portfolio`/`CollectionPage`/`ProjectDetail` to add chrome.
+- The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your
+  `Header` is plain in-flow markup (not `position:fixed`).
+- Route on `slug` (`getCollectionBySlug`/`getProjectBySlug`); use `getProject(id)` only when you hold a GUID.
+- Render live Wix data or the shipped empty state — never mock projects, collections, or media, and
+  never hand-build Wix Media URLs or page permalinks (use the `url`/`imageInfo.url`/`resolutions[].url`
+  fields Wix returns). Hidden collections/projects are already filtered out — don't add them back.
 
 ## Point the user to their dashboard
-In some cases, users need to access the Wix dashboard in order to edit the portfolio content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For portfolio data those pages are:
-- **Portfolio** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-portfolio/projects` (`Dashboard → Portfolio`). Projects and Collections are tabs on this one page: the **Projects** tab adds projects and their media galleries; the **Collections** tab groups projects into collections.
-
-Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
-
-## Verification checklist (before declaring done)
-- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
-- [ ] Visitor token persists across reload (no re-mint storm; reads stay fast)
-- [ ] Collections gallery renders live collections with cover images, in dashboard order
-- [ ] Clicking a collection lists its projects via `queryProjectsByCollection`
-- [ ] Project page renders the project's media gallery from `listProjectItems` (images AND videos)
-- [ ] Project `details[]` rows render (text rows and link rows both)
-- [ ] Slug routing works; an unknown slug shows a not-found state (no invented project)
-- [ ] Hidden collections/projects never appear
-- [ ] Empty state shown when `countCollections()` is 0
-- [ ] No mock projects, collections, or media anywhere
-- [ ] Told the user at least once that they can continue setting up their portfolio in the dashboard and provided deep links.
+Provide the deep link so the owner can edit content (substitute the site's `metaSiteId`):
+- **Portfolio** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-portfolio/projects`
+  (`Dashboard → Portfolio`). Projects and Collections are tabs on this one page: the **Projects** tab
+  adds projects and their media galleries; the **Collections** tab groups projects into collections.
+
+## Seeding
+Seed collections and projects per `seed/SEED.md` — separate from this client build; run in parallel.
+
+## Verify (before declaring done)
+- [ ] Client files copied into `src/`; `WIX_CLIENT_ID` set (not the placeholder).
+- [ ] Brand palette lives in `index.css` (`:root`/`.dark`); no parallel theme file; shipped components/pages not restyled or rewritten.
+- [ ] Opened the vertical's data route(s) (`/portfolio`, a collection, a project) — not just the home page — and confirmed the shipped components render themed (surface, text, brand) with images.
+- [ ] `Layout` (fixed `<WixManageBanner/>` + `<Header/>` region, then `<Outlet/>` + Footer) wraps all
+      routes; shipped `Portfolio`/`CollectionPage`/`ProjectDetail` untouched; content clears the fixed chrome.
+- [ ] Visitor token persists across reload (no re-mint storm; reads stay fast).
+- [ ] Collections gallery renders live collections with cover images, in dashboard order.
+- [ ] Clicking a collection lists its projects via `queryProjectsByCollection`.
+- [ ] Project page renders the media gallery from `listProjectItems` (images AND videos) and the
+      `details[]` rows (text rows and link rows both).
+- [ ] Slug routing works; an unknown slug shows the shipped not-found state (no invented content).
+- [ ] Empty catalog shows the shipped empty state (`countCollections()` is 0); no mock content anywhere.
+- [ ] Told the user they can continue setting up their portfolio in the dashboard, with the deep link.

package/skills/wix-vibe-headless/references/portfolio/app/components/CollectionCard.jsx

@@ -0,0 +1,31 @@
+// Collection tile → links to /collection/:slug. Styled with base44 design tokens (shadcn Tailwind
+// classes) — re-skin via the app's design tokens (src/index.css :root/.dark), not this JSX. The
+// `//`-protocol image fix and the coverImage.imageInfo.url field path are load-bearing.
+import { Link } from "react-router-dom";
+
+function coverUrl(collection) {
+  const url = collection?.coverImage?.imageInfo?.url;
+  return url ? (url.startsWith("//") ? `https:${url}` : url) : null;
+}
+
+export default function CollectionCard({ collection }) {
+  const image = coverUrl(collection);
+
+  return (
+    <Link to={`/collection/${collection.slug}`}
+      className="flex flex-col no-underline text-foreground bg-card border border-border rounded-lg overflow-hidden shadow-sm">
+      <div className="aspect-[4/3] bg-background">
+        {image
+          ? <img src={image} alt={collection.title} loading="lazy"
+              className="w-full h-full object-cover" />
+          : <div className="w-full h-full bg-muted flex items-center justify-center" aria-hidden="true"><svg viewBox="0 0 24 24" className="w-8 h-8 text-muted-foreground/40" fill="none" stroke="currentColor" strokeWidth="1.5"><rect x="3" y="3" width="18" height="18" rx="2" /><circle cx="8.5" cy="8.5" r="1.5" /><path d="m21 15-5-5L5 21" /></svg></div>}
+      </div>
+      <div className="p-3 flex flex-col gap-1">
+        <h3 className="m-0 font-display text-base font-semibold">{collection.title}</h3>
+        {collection.description && (
+          <p className="m-0 text-muted-foreground text-sm leading-normal">{collection.description}</p>
+        )}
+      </div>
+    </Link>
+  );
+}

package/skills/wix-vibe-headless/references/portfolio/app/components/CollectionGrid.jsx

@@ -0,0 +1,15 @@
+// Responsive collections grid + empty state. Styled with base44 design tokens (shadcn Tailwind classes).
+import CollectionCard from "./CollectionCard";
+
+export default function CollectionGrid({ collections, empty = "No collections yet." }) {
+  if (!collections?.length) {
+    return (
+      <p className="text-muted-foreground p-4 text-center">{empty}</p>
+    );
+  }
+  return (
+    <div className="grid gap-4 [grid-template-columns:repeat(auto-fill,minmax(280px,1fr))]">
+      {collections.map((c) => <CollectionCard key={c.id} collection={c} />)}
+    </div>
+  );
+}

package/skills/wix-vibe-headless/references/portfolio/app/components/ProjectCard.jsx

@@ -0,0 +1,39 @@
+// Project tile → links to /project/:slug. Styled with base44 design tokens (shadcn Tailwind classes)
+// — re-skin via the app's design tokens (src/index.css :root/.dark), not this JSX. The cover is a
+// one-of: image when present, else the video's poster / first resolution. The `//`-protocol fix and
+// these field paths are load-bearing.
+import { Link } from "react-router-dom";
+
+function https(url) {
+  return url ? (url.startsWith("//") ? `https:${url}` : url) : null;
+}
+
+// coverImage.imageInfo is ONE-OF with coverVideo.videoInfo — fall back through the video.
+function coverUrl(project) {
+  const image = project?.coverImage?.imageInfo?.url;
+  if (image) return https(image);
+  const vi = project?.coverVideo?.videoInfo;
+  return https(vi?.posters?.[0]?.url || vi?.resolutions?.[0]?.url || null);
+}
+
+export default function ProjectCard({ project }) {
+  const image = coverUrl(project);
+
+  return (
+    <Link to={`/project/${project.slug}`}
+      className="flex flex-col no-underline text-foreground bg-card border border-border rounded-lg overflow-hidden shadow-sm">
+      <div className="aspect-[4/3] bg-background">
+        {image
+          ? <img src={image} alt={project.title} loading="lazy"
+              className="w-full h-full object-cover" />
+          : <div className="w-full h-full bg-muted flex items-center justify-center" aria-hidden="true"><svg viewBox="0 0 24 24" className="w-8 h-8 text-muted-foreground/40" fill="none" stroke="currentColor" strokeWidth="1.5"><rect x="3" y="3" width="18" height="18" rx="2" /><circle cx="8.5" cy="8.5" r="1.5" /><path d="m21 15-5-5L5 21" /></svg></div>}
+      </div>
+      <div className="p-3 flex flex-col gap-1">
+        <h3 className="m-0 font-display text-[15px] font-semibold">{project.title}</h3>
+        {project.description && (
+          <p className="m-0 text-muted-foreground text-sm leading-normal">{project.description}</p>
+        )}
+      </div>
+    </Link>
+  );
+}

package/skills/wix-vibe-headless/references/portfolio/app/components/ProjectGrid.jsx

@@ -0,0 +1,15 @@
+// Responsive projects grid + empty state. Styled with base44 design tokens (shadcn Tailwind classes).
+import ProjectCard from "./ProjectCard";
+
+export default function ProjectGrid({ projects, empty = "No projects yet." }) {
+  if (!projects?.length) {
+    return (
+      <p className="text-muted-foreground p-4 text-center">{empty}</p>
+    );
+  }
+  return (
+    <div className="grid gap-4 [grid-template-columns:repeat(auto-fill,minmax(240px,1fr))]">
+      {projects.map((p) => <ProjectCard key={p.id} project={p} />)}
+    </div>
+  );
+}

package/skills/wix-vibe-headless/references/portfolio/app/components/ProjectMedia.jsx

@@ -0,0 +1,29 @@
+// One gallery media item. Branch on item.type ("IMAGE" | "VIDEO" | "UNDEFINED") — this branching
+// and the field paths (image.imageInfo.url, video.videoInfo.resolutions[0].url) are load-bearing;
+// re-skin via base44 design tokens (shadcn Tailwind classes), don't rewire the paths.
+
+function https(url) {
+  return url ? (url.startsWith("//") ? `https:${url}` : url) : null;
+}
+
+export default function ProjectMedia({ item }) {
+  if (item.type === "IMAGE") {
+    const src = https(item.image?.imageInfo?.url);
+    return src ? (
+      <img src={src} alt={item.title || ""} loading="lazy"
+        className="block w-full h-auto rounded-sm" />
+    ) : null;
+  }
+  if (item.type === "VIDEO") {
+    // resolutions[].url is the confirmed field; posters[0] is the poster (sub-shape not in the
+    // helper JSDoc — posters[0].url used here; confirm in wix-docs if a brand needs more).
+    const vi = item.video?.videoInfo;
+    const src = https(vi?.resolutions?.[0]?.url);
+    const poster = https(vi?.posters?.[0]?.url);
+    return src ? (
+      <video src={src} poster={poster || undefined} controls playsInline
+        className="block w-full h-auto rounded-sm bg-card" />
+    ) : null;
+  }
+  return null; // UNDEFINED — nothing renderable
+}

package/skills/wix-vibe-headless/references/portfolio/app/hooks/useCollectionProjects.js

@@ -0,0 +1,35 @@
+// useCollectionProjects — one collection's header + its project grid, no markup. Resolve the
+// collection by slug (null → not-found), then page its projects. getCollectionBySlug returns the
+// object or null; queryProjectsByCollection returns { projects, nextCursor } (an OBJECT) — keep
+// the destructuring, or `.map` on the result throws.
+import { useState, useEffect } from "react";
+import { getCollectionBySlug, queryProjectsByCollection } from "@/rest/wix-portfolio";
+
+export function useCollectionProjects(slug, { limit = 24 } = {}) {
+  const [collection, setCollection] = useState(null);
+  const [notFound, setNotFound] = useState(false);
+  const [projects, setProjects] = useState(null); // null = loading
+  const [cursor, setCursor] = useState(null);
+
+  useEffect(() => {
+    setNotFound(false);
+    setProjects(null);
+    getCollectionBySlug(slug).then((c) => {
+      if (!c) return setNotFound(true);
+      setCollection(c);
+      queryProjectsByCollection(c.id, { limit }).then(({ projects, nextCursor }) => {
+        setProjects(projects);
+        setCursor(nextCursor);
+      });
+    });
+  }, [slug, limit]);
+
+  const loadMore = () =>
+    collection &&
+    queryProjectsByCollection(collection.id, { limit, cursor }).then(({ projects: more, nextCursor }) => {
+      setProjects((p) => [...(p ?? []), ...more]);
+      setCursor(nextCursor);
+    });
+
+  return { collection, notFound, projects, cursor, loadMore };
+}

package/skills/wix-vibe-headless/references/portfolio/app/hooks/usePortfolioGallery.js

@@ -0,0 +1,27 @@
+// usePortfolioGallery — collections-gallery data, no markup: first page + count for the empty
+// state + cursor paging. queryCollections returns { collections, nextCursor } (an OBJECT, not an
+// array) and countCollections returns a number — those shapes are the bug-prone part; keep them.
+import { useState, useEffect } from "react";
+import { queryCollections, countCollections } from "@/rest/wix-portfolio";
+
+export function usePortfolioGallery({ limit = 24 } = {}) {
+  const [collections, setCollections] = useState(null); // null = loading
+  const [cursor, setCursor] = useState(null);
+  const [total, setTotal] = useState(null);             // 0 → empty state
+
+  useEffect(() => {
+    countCollections().then(setTotal);
+    queryCollections({ limit }).then(({ collections, nextCursor }) => {
+      setCollections(collections);
+      setCursor(nextCursor);
+    });
+  }, [limit]);
+
+  const loadMore = () =>
+    queryCollections({ limit, cursor }).then(({ collections: more, nextCursor }) => {
+      setCollections((c) => [...(c ?? []), ...more]);
+      setCursor(nextCursor);
+    });
+
+  return { collections, total, cursor, loadMore };
+}

package/skills/wix-vibe-headless/references/portfolio/app/hooks/useProjectDetail.js

@@ -0,0 +1,25 @@
+// useProjectDetail — project-detail data, no markup: load a project by slug (null → not-found),
+// then load its media gallery. listProjectItems returns { items, total } (an OBJECT, not a bare
+// array) — iterate `items`; that shape is the bug-prone part. The PDP page only renders what this
+// returns. details[] rows come through untouched: [{ label, text? OR link: { text, url, target } }].
+import { useState, useEffect } from "react";
+import { getProjectBySlug, listProjectItems } from "@/rest/wix-portfolio";
+
+export function useProjectDetail(slug) {
+  const [project, setProject] = useState(null);
+  const [notFound, setNotFound] = useState(false);
+  const [items, setItems] = useState([]);
+
+  useEffect(() => {
+    setNotFound(false);
+    setProject(null);
+    setItems([]);
+    getProjectBySlug(slug).then((p) => {
+      if (!p) return setNotFound(true);
+      setProject(p);
+      listProjectItems(p.id).then(({ items }) => setItems(items));
+    });
+  }, [slug]);
+
+  return { project, notFound, items };
+}