@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -1,128 +1,239 @@
+# Wix Blog — ready-made client
 
-# Wix Blog Skill
+The blog reader is **shipped as real files**, not snippets to regenerate. It's a complete feed + post
+detail + category/tag landing pages, styled with your app's design tokens (base44's `src/index.css` —
+the shadcn palette the design phase already set). Copy it into the app and wire the routes — you
+generate almost none of the reader code (post paging, slug routing, the category/tag id→label
+resolution, the plain-text body split all ship and are correct).
 
-> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/blog/wix-blog.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). The reader is
+**read-only and visitor-facing** — it never creates, edits, or moderates content. Never mock posts;
+never hand-build a post/category/tag URL — route by `slug` through the shipped helpers.
 
-Builds a real, client-only Wix blog reader. The browser talks to Wix directly over a
-public `WIX_CLIENT_ID`. Never mock posts; never hand-build post/category/tag URLs — always
-fetch live data through the official Blog REST endpoints and route by `slug`.
+## Prerequisites
+- The site's **Wix Blog** 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 posts land. Draft/unpublished posts are never returned.
+- The public headless **`WIX_CLIENT_ID`** from your prompt (visitor-facing, safe to hardcode/commit).
 
-## When to use
-- User wants a Wix blog/news/articles section or asks to "connect my Wix blog".
-- Replacing placeholder/mock articles with live Wix Blog posts.
-- Adding a post feed, post detail pages, category pages, or tag pages over an existing
-  Wix Blog with published posts.
+## STEP 1 — The client is already in `src/`
+The install step (base44.md STEP 1) deployed the whole blog 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:**
 
-This skill is **read-only and visitor-facing**. It does not create, edit, publish, or
-moderate posts — the author manages all content in the Wix dashboard.
+| file | what it is |
+|---|---|
+| `context/TaxonomyContext.jsx` | `useTaxonomy()` provider: categories + tags fetched **once**, exposed as `catById` / `tagById` id→object maps |
+| `hooks/usePostDetail.js` | post-detail data — load by slug, not-found state, resolved category/tag chips, body paragraphs |
+| `components/PostCard.jsx`, `PostGrid.jsx` | post listing UI (grid + card, with cover image + empty state) |
+| `components/PostChips.jsx` | category/tag chips for a post (resolves ids via the taxonomy, routes by slug) |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `pages/Blog.jsx` | the feed route (`/blog`) — lists posts, paginates, empty state |
+| `pages/PostDetail.jsx` | the post route (`/blog/:slug`) |
+| `pages/CategoryPage.jsx`, `TagPage.jsx` | the taxonomy landing routes (`/blog/category/:slug`, `/blog/tag/:slug`) |
+| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-client.js` + `rest/wix-blog.js` | REST transport + blog helpers (posts/categories/tags) |
 
-## Prerequisites
-1. A Wix site with **Wix Blog installed and posts already published** (this skill does
-   NOT provision — it's read-only over published content). Draft/unpublished posts are
-   never returned.
-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.
-
-## The API (copy as-is; do not re-derive it)
-This skill ships only the REST layer — no UI components. Build the blog'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 refresh token is
-  persisted to localStorage so the same anonymous visitor is reused across reloads; do not
-  re-mint anonymously per load.
-- `src/rest/wix-blog.js` — exports:
-  - **Posts:** `queryPosts`, `getPostBySlug`, `queryPostsByCategory`, `queryPostsByTag`, `getTotalPosts`
-  - **Categories:** `queryCategories`, `getCategoryBySlug`
-  - **Tags:** `queryTags`, `getTagBySlug`
-
-The Post, Category, and Tag shapes are documented as JSDoc comments at the top of
-`wix-blog.js`. Read them before building the UI — they describe the key fields and link to
-the full API reference for anything not shown.
-
-## How to wire it (UI is the project's choice)
-- **Post feed** — `queryPosts()` for the listing (published posts only, newest first with
-  pinned posts leading); pass `nextCursor` back as `cursor` to load the next page. Render
-  `title`, `excerpt`, `firstPublishedDate`, `minutesToRead`, and the cover image from
-  **`post.media.wixMedia.image.url`** (see the cover-image note below). Route to the detail page by `slug`.
-- **Post detail** — `getPostBySlug(slug)` keyed off the URL slug; returns `null` on miss —
-  show a not-found state, never invent a post. It returns full content:
-  - `contentText` — the body as plain text. Split on `"\n"` to render simple paragraphs.
-  - `richContent` — the body as a Ricos rich-content document (images, embeds, formatting).
-    Render it with a Ricos renderer for a faithful post. See "Beyond the snippets" if you
-    need rich rendering; `contentText` is the zero-dependency default.
-  - Resolve `categoryIds` / `tagIds` to labels with `queryCategories()` / `queryTags()`
-    (build an id→label map) to show category/tag chips.
-- **Cover image** — use **`post.media.wixMedia.image.url`** (a ready-to-use https URL) for the card
-  thumbnail and post header. `media` is returned by default (including on the list query), so no extra
-  fieldset is needed. When `post.media?.wixMedia?.image` is absent, the cover is the first image inside
-  `richContent` — fall back to the first IMAGE node there, or show a text-only card. Never substitute a
-  stock/placeholder image.
-- **Category page** — `queryCategories()` for a category menu (ordered by `displayPosition`;
-  hide categories with `postCount === 0` if you want); `getCategoryBySlug(slug)` for a
-  category landing page. Pass `category.id` to `queryPostsByCategory(categoryId, { limit?, cursor? })`
-  to list that category's posts; paginate exactly like `queryPosts`.
-- **Tag page** — `queryTags()` for a tag cloud/list (most-used first); `getTagBySlug(slug)`
-  for a tag landing page. Pass `tag.id` to `queryPostsByTag(tagId, { limit?, cursor? })`.
-- **Empty state** — if `getTotalPosts()` is 0, show an empty state telling the user to
-  publish posts in their Wix dashboard. Never invent posts.
-
-## Hard rules (do not violate)
-- ✅ Fetch posts/categories/tags ONLY through the shipped helpers (the official Blog REST
-  endpoints). Route between screens by `slug`.
-- ❌ Never hand-build post, category, or tag URLs to fetch content. Use `getPostBySlug`,
-  `getCategoryBySlug`, `getTagBySlug`. (For an outbound link to the live Wix page, use the
-  `url` field — `url.base + url.path` — returned on the object, not a string you assemble.)
-- ❌ Never mock posts, authors, or content — render live Wix data or the empty state.
-- ❌ Never generate fake comments, likes, view counts, or ratings. This skill is read-only
-  and does not expose engagement actions; leave such UI empty or omit it.
-- ❌ Never use a placeholder/stock cover image. If `post.media?.wixMedia?.image` is missing, fall back
-  to the first richContent image or a text-only card.
-- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
-- ✅ Use `post.media.wixMedia.image.url` for the cover image.
-- The helpers fail soft on single-item lookups: `getPostBySlug` / `getCategoryBySlug` /
-  `getTagBySlug` return `null` on a miss so you can show a proper not-found state — don't
-  swallow that into a fake item.
-
-## Beyond the snippets
-The snippets cover the common blog-reader paths. If you hit a use case they don't cover
-(e.g. rendering `richContent` faithfully, full-text search/filtering, related posts,
-post metrics, members-only/pricing-plan posts, multilingual posts), extend the client
-yourself with `wixApiRequest` — but look up the exact endpoint, HTTP method, and request
-body in the **official Wix API reference** first; never guess:
+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/blog/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 + provider (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.
+- Wrap the routed tree in `<TaxonomyProvider>` (from `@/context/TaxonomyContext`) so categories/tags
+  are fetched **once** and every card/chip reuses the shared map (never re-query per post).
+- 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 `Blog` / `PostDetail` / category / tag pages — 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: `/blog` → `Blog`, `/blog/:slug` → `PostDetail`, `/blog/category/:slug` →
+  `CategoryPage`, `/blog/tag/:slug` → `TagPage` (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 { TaxonomyProvider } from "@/context/TaxonomyContext";
+import WixManageBanner from "@/components/WixManageBanner";   // shipped, preview-only · default export, no props
+import Blog from "@/pages/Blog";                       // shipped · default export, no props
+import PostDetail from "@/pages/PostDetail";           // shipped · default export, no props
+import CategoryPage from "@/pages/CategoryPage";       // shipped · default export, no props
+import TagPage from "@/pages/TagPage";                 // 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 Blog / PostDetail / Category / Tag render here, untouched */}
+      <Footer />
+    </div>
+  </>);
+}
+
+<TaxonomyProvider>
+  <Routes>
+    <Route element={<Layout />}>                                    {/* chrome wraps all */}
+      <Route path="/" element={<Home />} />                         {/* yours */}
+      <Route path="/blog" element={<Blog />} />                     {/* shipped, as-is */}
+      <Route path="/blog/:slug" element={<PostDetail />} />         {/* shipped, as-is */}
+      <Route path="/blog/category/:slug" element={<CategoryPage />} /> {/* shipped, as-is */}
+      <Route path="/blog/tag/:slug" element={<TagPage />} />        {/* shipped, as-is */}
+    </Route>
+  </Routes>
+</TaxonomyProvider>
+```
+
+## 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 "latest posts" strip is just `queryPosts` + the shipped
+`PostGrid`; a category nav is `useTaxonomy()` + links to `/blog/category/:slug`:
+
+```jsx
+import { useState, useEffect } from "react";
+import { Link } from "react-router-dom";
+import { queryPosts } from "@/rest/wix-blog";
+import { useTaxonomy } from "@/context/TaxonomyContext";
+import PostGrid from "@/components/PostGrid";
+
+// Responsive header: choose ONE branch with a state flag (never a Tailwind `hidden md:*` toggle —
+// these navs are inline-styled, and an inline `display` beats a Tailwind class, so `hidden` never
+// applies and BOTH branches render). One branch = one nav.
+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 + links here
+        : <div style={{ display: "flex", gap: 24 }}><Link to="/">Home</Link><Link to="/blog">Blog</Link></div>}
+    </nav>
+  );
+}
+export function Latest() {                                   // on your home page
+  const [posts, setPosts] = useState([]);
+  // NB: queryPosts returns { posts, nextCursor } — destructure the array.
+  useEffect(() => { queryPosts({ limit: 6 }).then(({ posts }) => setPosts(posts)); }, []);
+  return <PostGrid posts={posts} empty="Posts coming soon." />;
+}
+export function CategoryNav() {                              // a menu of the blog's categories
+  const { categories } = useTaxonomy();                     // fetched once by the provider
+  return categories.filter((c) => c.postCount > 0)          // hide empty categories if you want
+    .map((c) => <Link key={c.id} to={`/blog/category/${c.slug}`}>{c.label}</Link>);
+}
+```
+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
+
+```jsx
+// Every list helper returns an OBJECT, not a bare array — destructure first, or `.map` throws:
+const { posts, nextCursor } = await queryPosts({ limit: 20 });          // pass nextCursor back as `cursor`
+const { categories, total } = await queryCategories();                  // display c.label · count c.postCount
+const { tags } = await queryTags();                                     // display t.label · count t.publishedPostCount
+const { posts: inCategory } = await queryPostsByCategory(categoryId, { limit: 20 });
+const { posts: withTag }    = await queryPostsByTag(tagId, { limit: 20 });
+
+// Single-item lookups fail soft (null on miss) — show a not-found state, never invent an item:
+const post = await getPostBySlug(slug);         // null → 404 state
+const cat  = await getCategoryBySlug(slug);
+const tag  = await getTagBySlug(slug);
+
+// Cover image: post cover and category cover are DIFFERENT paths.
+const postCover = post.media?.wixMedia?.image?.url;   // post/card cover (ready-to-use https)
+const catCover  = cat.coverImage?.url;                // category landing cover
+// No post cover? fall back to the first richContent IMAGE node, or a text-only card — never a stock image.
+
+// Body: contentText is plain text (split on "\n" for paragraphs — the shipped hook does this).
+// richContent is a Ricos document for a faithful render (images/embeds) — see "Extending".
+```
+
+**No author byline** — the reader helpers don't expose an author (`post.author` is undefined). Omit
+the byline, or resolve it via the **members** vertical. **No engagement UI** — comments/likes/views
+aren't exposed; leave them out.
+
+## Extending the client
+Building something beyond the shipped pages (faithful `richContent`, full-text search, related posts,
+metrics, members-only posts)? Extend with `wixApiRequest`, but look up the exact endpoint/method/body
+in the **official Wix API reference** first — never guess. Each helper in `wix-blog.js` links its
+reference page inline.
 - Blog API reference: https://dev.wix.com/docs/api-reference/business-solutions/blog.md
-- Query Posts (filters/sort: `categoryIds`, `tagIds`, `hashtags`, `title`, dates, `featured`):
-  https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md
-- Rendering `richContent` (Ricos document format):
-  https://dev.wix.com/docs/ricos/api-reference/ricos-document
-- **Members-only posts** → the **members** vertical (`references/members/INSTRUCTIONS.md`): once a
-  member is logged in (custom login on your own UI), the existing read helpers return the content
-  gated to members — no extra code. Note this blog helper is **read-only**: member *writes* (posting
-  a comment, liking a post) aren't included — add them as a beyond-the-snippets `wixApiRequest` call,
-  authenticated as the logged-in member.
-- Each helper in `wix-blog.js` links its exact reference page inline.
-
-Keep the snippets as the default for everything they already do; reach for the API
-reference only for the gap.
+- Rendering `richContent` (Ricos document): https://dev.wix.com/docs/ricos/api-reference/ricos-document
+- **Members-only posts** → the **members** vertical: once a member is logged in, the shipped read
+  helpers return the gated content with no extra code (member *writes* — comments, likes — are not
+  included; add them as an authenticated `wixApiRequest` call).
+
+Fallback only — when you hit an error or need something not shown here: read the relevant shipped file
+under `src/`, or look it up via the **`wix-docs`** skill.
+
+## 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 `Blog`/`PostDetail`/category/tag pages 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 by `slug` through the shipped helpers — never hand-build a post/category/tag URL. Display categories/tags by `.label` (not `.name`).
+- Render live Wix data or the shipped empty state — never mock posts, authors, comments, likes, or view counts; never use a stock/placeholder cover image.
 
 ## Point the user to their dashboard
-In some cases, users need to access the Wix dashboard in order to edit the blog content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For blog data those pages are:
-- **Posts** — `https://manage.wix.com/dashboard/{metaSiteId}/blog/posts` (`Dashboard → Blog → Posts`; write, edit, and publish posts; only published posts appear in the app)
-- **Categories** — `https://manage.wix.com/dashboard/{metaSiteId}/blog/categories` (`Dashboard → Blog → Categories`)
-
-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; same anonymous visitor)
-- [ ] Post feed lists live published posts, newest first, and paginates via `nextCursor`
-- [ ] Post detail loads by `slug` and renders real `contentText` (or rendered `richContent`)
-- [ ] `getPostBySlug` on a bad slug shows a not-found state (no invented post)
-- [ ] Cover images come from `post.media.wixMedia.image.url` (or richContent fallback) — no stock placeholders
-- [ ] Category and tag pages list the right posts via `queryPostsByCategory` / `queryPostsByTag`
-- [ ] Empty state shown when `getTotalPosts()` is 0
-- [ ] No mock posts, authors, comments, likes, or view counts anywhere
-- [ ] Told the user at least once that they can continue setting up their blog in the dashboard and provided deep links.
+Provide deep links so the owner can edit content (substitute the site's `metaSiteId`):
+- **Posts** — `https://manage.wix.com/dashboard/{metaSiteId}/blog/posts` (write, edit, publish; only published posts appear in the app)
+- **Categories** — `https://manage.wix.com/dashboard/{metaSiteId}/blog/categories`
+
+## Seeding
+Seed the blog per `seed/SEED.md` (the build-time module that creates posts/categories over the
+connector) — 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)** (not just the home page) — `/blog` and a post detail page (plus a category/tag 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 `Blog`/`PostDetail`/`CategoryPage`/`TagPage` untouched; content clears the fixed chrome; `<TaxonomyProvider>` wraps the tree.
+- [ ] Feed lists live published posts (newest first) and paginates via `nextCursor`; post detail loads by `slug`; a bad slug shows the not-found state (no invented post).
+- [ ] Category/tag pages list the right posts; chips display `.label` and route by `.slug`; taxonomy fetched once (no re-query per card).
+- [ ] Cover images come from `post.media.wixMedia.image.url` (category cover from `category.coverImage.url`) — no stock placeholders; no author byline / engagement UI invented.
+- [ ] Empty catalog shows the shipped empty state; no mock posts anywhere.

package/skills/wix-vibe-headless/references/blog/app/components/PostCard.jsx

@@ -0,0 +1,43 @@
+// Feed tile. Styled with base44 design tokens (shadcn Tailwind classes) — re-skin via those tokens, not this
+// JSX. The cover-image path (post.media.wixMedia.image.url) and the text-only fallback are
+// load-bearing: never substitute a stock/placeholder image. Routes to the detail page by slug.
+import { Link } from "react-router-dom";
+
+function coverImage(post) {
+  const url = post?.media?.wixMedia?.image?.url;         // ready-to-use https url; //-fix is defensive
+  return url ? (url.startsWith("//") ? `https:${url}` : url) : null;
+}
+
+function formatDate(iso) {
+  if (!iso) return null;
+  try { return new Date(iso).toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" }); }
+  catch { return null; }
+}
+
+export default function PostCard({ post }) {
+  const image = coverImage(post);
+  const date = formatDate(post?.firstPublishedDate);
+
+  return (
+    <Link to={`/blog/${post.slug}`}
+      className="flex flex-col no-underline text-foreground bg-card border border-border rounded-lg overflow-hidden shadow-sm">
+      {image && (
+        <div className="aspect-[16/9] bg-background">
+          <img src={image} alt={post.media?.wixMedia?.image?.altText || post.title} loading="lazy"
+            className="w-full h-full object-cover" />
+        </div>
+      )}
+      <div className="p-4 flex flex-col gap-2">
+        <h3 className="m-0 font-display text-lg font-semibold leading-[1.3]">{post.title}</h3>
+        {post.excerpt && (
+          <p className="m-0 text-muted-foreground text-sm leading-[1.5]">{post.excerpt}</p>
+        )}
+        <div className="flex gap-2 items-center text-muted-foreground text-[12px]">
+          {date && <span>{date}</span>}
+          {date && post.minutesToRead ? <span aria-hidden="true">·</span> : null}
+          {post.minutesToRead ? <span>{post.minutesToRead} min read</span> : null}
+        </div>
+      </div>
+    </Link>
+  );
+}

package/skills/wix-vibe-headless/references/blog/app/components/PostChips.jsx

@@ -0,0 +1,25 @@
+// Category + tag chips for a post. Resolves the post's categoryIds/tagIds against the SHARED
+// taxonomy maps (fetched once by TaxonomyProvider — never re-query here), displays each by .label
+// (NOT .name), and routes by .slug. Styled with base44 design tokens (shadcn Tailwind classes).
+import { Link } from "react-router-dom";
+import { useTaxonomy } from "@/context/TaxonomyContext";
+
+const chip = "inline-flex items-center py-1 px-2.5 text-[12px] no-underline text-foreground bg-card border border-border rounded-full";
+
+export default function PostChips({ post }) {
+  const { catById, tagById } = useTaxonomy();
+  const cats = (post.categoryIds || []).map((id) => catById.get(id)).filter(Boolean);
+  const tags = (post.tagIds || []).map((id) => tagById.get(id)).filter(Boolean);
+  if (!cats.length && !tags.length) return null;
+
+  return (
+    <div className="flex flex-wrap gap-2">
+      {cats.map((c) => (
+        <Link key={c.id} to={`/blog/category/${c.slug}`} className={`${chip} text-primary border-primary`}>{c.label}</Link>
+      ))}
+      {tags.map((t) => (
+        <Link key={t.id} to={`/blog/tag/${t.slug}`} className={chip}>#{t.label}</Link>
+      ))}
+    </div>
+  );
+}

package/skills/wix-vibe-headless/references/blog/app/components/PostGrid.jsx

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

package/skills/wix-vibe-headless/references/blog/app/context/TaxonomyContext.jsx

@@ -0,0 +1,35 @@
+// Taxonomy state — categories + tags fetched ONCE and shared across every page/card. Wrap the app
+// in <TaxonomyProvider>; components read useTaxonomy(). Resolving a post's categoryIds/tagIds to
+// chip labels runs on every post render, so this MUST be a single shared fetch — never re-query per
+// card. Data wiring (destructuring, .label display, id→object maps) is correct as-is; don't re-derive.
+import { createContext, useContext, useState, useEffect, useMemo } from "react";
+import { queryCategories, queryTags } from "@/rest/wix-blog";
+
+const TaxonomyContext = createContext(null);
+
+export function TaxonomyProvider({ children }) {
+  const [categories, setCategories] = useState([]);
+  const [tags, setTags] = useState([]);
+
+  useEffect(() => {
+    // NB: destructure — queryCategories → { categories, total }, queryTags → { tags, total }.
+    queryCategories().then(({ categories }) => setCategories(categories));
+    queryTags().then(({ tags }) => setTags(tags));
+  }, []);
+
+  // display c.label · count c.postCount  /  display t.label · count t.publishedPostCount
+  const catById = useMemo(() => new Map(categories.map((c) => [c.id, c])), [categories]);
+  const tagById = useMemo(() => new Map(tags.map((t) => [t.id, t])), [tags]);
+
+  return (
+    <TaxonomyContext.Provider value={{ categories, tags, catById, tagById }}>
+      {children}
+    </TaxonomyContext.Provider>
+  );
+}
+
+export function useTaxonomy() {
+  const ctx = useContext(TaxonomyContext);
+  if (!ctx) throw new Error("useTaxonomy must be used within <TaxonomyProvider>");
+  return ctx;
+}

package/skills/wix-vibe-headless/references/blog/app/hooks/usePostDetail.js

@@ -0,0 +1,38 @@
+// usePostDetail — all post-detail logic, no markup: load a post by slug, expose a not-found state,
+// resolve its categoryIds/tagIds to full category/tag objects via the shared taxonomy, and split the
+// plain-text body into paragraphs. The field paths (media cover, id→label resolution, contentText
+// split) are the bug-prone part — keep them verbatim; the PostDetail page only renders what this
+// returns. richContent is available on the loaded post for a richer render (see INSTRUCTIONS).
+import { useState, useEffect, useMemo } from "react";
+import { getPostBySlug } from "@/rest/wix-blog";
+import { useTaxonomy } from "@/context/TaxonomyContext";
+
+export function usePostDetail(slug) {
+  const { catById, tagById } = useTaxonomy();
+  const [post, setPost] = useState(null);
+  const [notFound, setNotFound] = useState(false);
+
+  useEffect(() => {
+    setPost(null);
+    setNotFound(false);
+    getPostBySlug(slug).then((p) => (p ? setPost(p) : setNotFound(true)));
+  }, [slug]);
+
+  // Resolve ids → full objects; display .label, route by .slug (drop ids with no match).
+  const cats = useMemo(
+    () => (post?.categoryIds || []).map((id) => catById.get(id)).filter(Boolean),
+    [post, catById],
+  );
+  const tags = useMemo(
+    () => (post?.tagIds || []).map((id) => tagById.get(id)).filter(Boolean),
+    [post, tagById],
+  );
+
+  // contentText is plain text — split on "\n" for simple paragraphs (drop blank lines).
+  const paragraphs = useMemo(
+    () => (post?.contentText || "").split("\n").map((s) => s.trim()).filter(Boolean),
+    [post],
+  );
+
+  return { post, notFound, cats, tags, paragraphs };
+}

package/skills/wix-vibe-headless/references/blog/app/pages/Blog.jsx

@@ -0,0 +1,40 @@
+// Blog feed — lists published posts (newest first, pinned lead), paginates via nextCursor, and
+// shows the shipped empty state when the blog has no posts. Styled with base44 design tokens (shadcn Tailwind classes).
+import { useEffect, useState } from "react";
+import { queryPosts, getTotalPosts } from "@/rest/wix-blog";
+import PostGrid from "@/components/PostGrid";
+
+export default function Blog() {
+  const [posts, setPosts] = useState(null);
+  const [cursor, setCursor] = useState(null);
+  const [total, setTotal] = useState(null);
+
+  useEffect(() => {
+    getTotalPosts().then(setTotal);
+    // NB: destructure — queryPosts returns { posts, nextCursor }, not a bare array.
+    queryPosts({ limit: 20 }).then(({ posts, nextCursor }) => { setPosts(posts); setCursor(nextCursor); });
+  }, []);
+
+  const loadMore = () =>
+    queryPosts({ limit: 20, cursor }).then(({ posts: more, nextCursor }) => {
+      setPosts((p) => [...(p || []), ...more]);
+      setCursor(nextCursor);
+    });
+
+  return (
+    <main className="max-w-[1100px] mx-auto p-4">
+      <h1 className="font-display mb-4">Blog</h1>
+      {posts === null
+        ? <p className="text-muted-foreground">Loading…</p>
+        : <PostGrid posts={posts} empty={total === 0
+            ? "No posts yet — publish posts from your Wix dashboard to see them here."
+            : "No posts to show."} />}
+      {cursor && (
+        <div className="text-center mt-8">
+          <button onClick={loadMore}
+            className="py-3 px-6 cursor-pointer text-[15px] font-semibold bg-primary text-primary-foreground border-none rounded-sm">Load more</button>
+        </div>
+      )}
+    </main>
+  );
+}