@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/blog/INSTRUCTIONS.md

@@ -0,0 +1,418 @@
+# Blog — playbook
+
+The blog machinery ships as files — post reads (feed paging with pinned-first order, slug lookup
+with the body/SEO fieldsets, related posts, counters), author bylines, category/tag taxonomy, likes,
+comments, the feed/post/comments state machines, and the Ricos body renderer, typed end-to-end.
+**The presentation doesn't ship — you build it** on the shipped hooks/DTOs: the post card, the grid,
+the blog index surface, the category and tag surfaces, the post page surface, the home page, and the
+brand. You never write blog data logic; you never skip designing. Authoring stays in the dashboard;
+visitors read, like, and comment.
+
+## The file map (deployed into `src/`)
+
+**On Astro and React the shipped files are tested and work as they are** — this table and the
+contracts below are everything you need to use them, so don't spend the run reading their source;
+wire them and build your surfaces. Reading them is the right move when something is off (a runtime
+error, a field this playbook doesn't cover) or when the brief wants a behaviour they don't offer —
+then read the file that owns it and change or extend it. On `lib`, `static`, and a port the
+components don't deploy at all, and each wiring section below opens with the files to read before
+writing their equivalents. Files you edit: `SiteLayout.astro`, `styles/global.css`, and the shipped
+pages' templates. Files you **create**: your feed island (skeleton below), your post surface, and
+your home page.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` | shared auth seam (deploy configures it — nothing to set by hand) |
+| `wix/media.ts` · `wix/money.ts` | `imgAttrs(url, sizes, ratio)` — every `<img>` attribute for a DTO image (`src`, `srcSet`, `sizes`, lazy): `<img {...imgAttrs(post.coverUrl, "(min-width: 1024px) 33vw, 100vw", 9 / 16)} alt={post.coverAlt} />`; `imgSrc()` / `imgSrcSet()` underneath |
+| `wix/blog/types.ts` | the DTOs (`PostSummary`, `PostDetail`, `BlogAuthor`, `PostMetrics`, `BlogCategory`, `BlogTag`, `PostPage`, `BlogComment`, `CommentPage`) — contracts inlined below |
+| `wix/blog/posts.ts` | `fetchPosts` (cursor-paged, pinned first, category/tag filtered on Wix, authors joined), `fetchPostBySlug` (full body + SEO + comments fields), `fetchRelatedPosts`, `fetchPostsByIds`, `fetchPostMetrics`; the helpers `postMetaLine`, `relativeDateLabel`, `formatCount`, `postPath`, `categoryPath`, `tagPath` — the transport; the rules and DTO mappers are in `posts-core.ts` beside it (shared with the REST layer) |
+| `wix/blog/taxonomy.ts` | `fetchBlogCategories({ withPosts? })`, `fetchBlogTags`, `fetchTagsByIds`, `fetchCategoryBySlug`, `fetchTagBySlug`, `inIdOrder` — the transport; mappers in `taxonomy-core.ts` |
+| `wix/blog/authors.ts` | `fetchAuthorsByIds` (one batched Members read per page), `fetchCurrentMemberId` — over the SDK's authenticated fetch; mappers in `authors-core.ts` |
+| `wix/blog/post-likes.ts` | `likePost`, `unlikePost`, `fetchLikeState` — the viewer's like, client-only |
+| `wix/blog/comments.ts` | `fetchComments`, `fetchReplies`, `createComment`, `deleteComment` — the post's thread as the viewer; rules in `comments-core.ts` |
+| `wix/blog/blog-feed-store.ts` · `post-store.ts` · `comments-store.ts` | the feed, post, and comments state machines, framework-free (`createBlogFeedStore()`, `createPostStore()`, `createCommentsStore()` — `getState`/`subscribe` + actions, one instance per surface); the hooks below bind them to React, every other stack uses them directly |
+| `hooks/blog/useBlogFeed.ts` | React binding of `blog-feed-store.ts`: feed + taxonomy filter + load-more — contract below |
+| `hooks/blog/usePost.ts` | React binding of `post-store.ts`: post by slug + resolved chips + related + like state — contract below |
+| `hooks/blog/useComments.ts` | React binding of `comments-store.ts`: the thread, replies, create/delete — contract below |
+| `components/blog/RichContent.tsx` | the post-body (and comment-body) renderer — **wire as-is** (machinery, not a reference) |
+| `components/blog/BlogFeedView.tsx` (+ `PostCard`, `PostByline`) · `PostView.tsx` · `PostLikeButton.tsx` (+ `EngagementRow`) · `CommentsView.tsx` | **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). Everything, shipped and yours, styles from these tokens |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `layouts/SiteLayout.astro` | site chrome — **yours to brand** (keep the `seo-tags` slot + global.css import). `title`/`description` are optional: an item page whose `<SEO.Tags>` resolved passes neither (one source of head tags). If another vertical is also deployed, its layout won — add a Blog nav link there |
+| `pages/blog.astro` | SSR feed — **keep the frontmatter**, swap the island import to YOUR component |
+| `pages/blog/[...slug].astro` | SSR post page with owner-editable SEO — **keep the frontmatter, the `[...slug]` rest param, and the SEO pieces** (`wixMetadata`, `loadSEOTagsServiceConfig`, `<SEO.Tags>`) exactly; restyle the template. Chips in the post's order, tags read by id, related strip, the like row and the comments as `client:load` islands, the body island `client:only="react"` (the ricos viewer breaks under SSR). A slug that resolves to nothing returns a real 404 |
+| `pages/blog/category/[slug].astro` | SSR category page (header: cover, label, description; the feed seeded with the category filter) with owner-editable SEO (`wixMetadata` on `categoryPageMetadata`, `BLOG_CATEGORY`) — same rules as the post page. Unknown slug → 404 |
+| `pages/blog/tag/[slug].astro` | SSR tag page (header: label; the feed seeded with the tag filter). No SEO item type exists for tags — the layout's title is the label. Unknown slug → 404 |
+
+## Routes
+
+| path | page | notes |
+|---|---|---|
+| `/blog` | the feed | pinned first, newest first; category pills link to the category pages |
+| `/blog/<slug>` | a post | `postPath(slug)` — a slug may contain `/`; the helper encodes per segment, the `[...slug]` param re-joins |
+| `/blog/category/<slug>` | a category | `categoryPath(slug)`; 404 when the slug matches no category (Wix's own router answers 200 + empty feed; a headless page that exists for no category is a 404) |
+| `/blog/tag/<slug>` | a tag | `tagPath(slug)`; 404 likewise; not in the sitemap (Wix lists no tag pages either) |
+
+Never hand-build these — the three path helpers are the only source; `post.url` (the legacy blog's
+page) is never used.
+
+## What you build — the design job
+
+1. **The post card + grid** — your tile (cover, title, excerpt, `postMetaLine(post)`, the byline and
+   counters when the DTO carries them) and rhythm, with skeletons while `posts === null`, an honest
+   empty state for `[]` when `error` is null, and a visibly different error state when it is not.
+2. **The blog index surface** — the feed island on `useBlogFeed`: category row (only when >1
+   non-empty category; pills as links to the category pages, or client-side filters), the grid, and a
+   load-more control gated on `hasMore`.
+3. **The category and tag surfaces** — the same island seeded with the filtered page, under a header
+   (category: cover, label, description; tag: label) — restyle the two shipped page templates.
+4. **The post page surface** — header (categories eyebrow, title, byline + meta line, cover), the body
+   via the shipped `RichContent`, the engagement row (counters, like), the tag chips, the related strip,
+   and the comments thread — restyle the `[...slug].astro` template around it.
+5. **The home page** — hero, latest posts (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. Dark theme: the ricos CSS hardcodes
+near-black text — add a global override scoping `.ricos-content` to the foreground token
+(in Astro use `<style is:global>`; React islands don't inherit scoped Astro styles).
+
+### What a complete blog shows (recommended defaults)
+
+Defaults for a blog whose brief says nothing about them; the prompt wins where it differs. Look at
+the seeded content before designing (how many posts, categories, covers, body structure) and design
+for this blog, not for a stereotype of one.
+
+- **Home:** what the blog is about and the latest posts (real ones, under a truthful heading) in the
+  first screen; a category link goes to `categoryPath(slug)`, never to an anchor.
+- **Index:** a real card — cover, title, meta line, byline — in the first screen at 390px too; the
+  category row only when more than one category has posts; loading, empty, and error states that look
+  different (the empty message only when `error` is null); load-more, never a raised page size.
+- **Post page:** eyebrow, title, byline + meta line, cover as a bounded band on phones
+  (`max-h-[45vh]`), the body, the engagement row, the tags, the related strip, the comments; a slug
+  that resolves to nothing shows only the not-found state.
+- **Copy:** render only what the DTO carries — a byline only with `authorName`, a counter only when
+  its number is defined, a comments section only when `commentingEnabled && referenceId`; no invented
+  authors, counts, or "trending" labels; no Wix IDs or technical words in visible text. A count that
+  is unknown renders nothing, never "0".
+
+### The contracts your components consume
+
+Tested and working as they are; read the source when something is off or the brief wants more.
+
+```ts
+// PostSummary (tiles) — display-ready:
+// { id, slug, title, excerpt, dateLabel /* "Aug 26, 2026" | "" */, dateISO,
+//   minutesToRead /* 0 = unknown */, featured, pinned,
+//   coverUrl /* "" = no cover (or the author hid it); a video cover → its poster, an embed → its thumbnail */,
+//   coverAlt /* the author's alt text, else the title; "" with no cover */,
+//   categoryIds, tagIds,
+//   authorId, authorName /* "" = unresolved → no byline */, authorAvatarUrl /* "" = none */,
+//   viewCount?, likeCount?, commentCount? /* undefined = unknown → render nothing */ }
+// postMetaLine(post) → "Aug 26, 2026 · 4 min read" (either half alone; "" when neither is known) —
+//   render it inside <time dateTime={post.dateISO}>; don't hand-assemble the separator.
+// relativeDateLabel(post.dateISO, now?) → "3 days ago" under a week, "Aug 5" this year, "Aug 5, 2024"
+//   otherwise — pass the SAME `now` on the server and the client (put it in the island's props).
+// formatCount(n) → "1.2K" (formatCount(n, "full") → "1,234"); "" for undefined.
+// postPath(slug) · categoryPath(slug) · tagPath(slug) → the only hrefs (slugs may contain "/").
+// PostDetail adds: richContent (Ricos JSON | null — render ONLY via RichContent),
+//   paragraphs (plain-text fallback body), updatedLabel/updatedISO ("" unless republished),
+//   seoTitle /* owner's override, else title */, seoDescription /* override → excerpt → body, 500 chars */,
+//   relatedPostIds, commentingEnabled, referenceId /* the comments thread; "" = none */.
+// BlogAuthor:   { id, name, avatarUrl }
+// PostMetrics:  { views?, likes?, comments? }
+// BlogCategory: { id, slug, label, title /* SEO title, "" when unset */, description, postCount, coverUrl }   // display .label
+// BlogTag:      { id, slug, label, postCount /* published posts */ }
+// BlogComment:  { id, topLevelId /* null = top-level */, parentId, parentAuthorName /* "replying to" */,
+//   authorId, authorName, authorAvatarUrl, isOwn /* the current member's → show delete */,
+//   dateLabel, dateISO, status /* PUBLISHED | PENDING (awaiting approval) | DELETED (placeholder) | HIDDEN */,
+//   content /* Ricos JSON | null → RichContent */, text /* plain text, for stacks without the viewer */, replyCount }
+
+// useBlogFeed({ initialPage?, initialCategoryId?, initialTagId?, initialCategories?, initialTags?, pageSize? /* 20 */ }) →
+// { posts: PostSummary[]|null /* null = loading → skeletons */,
+//   categories, tags,
+//   activeCategoryId, setActiveCategoryId(id|null),   // server-side filter
+//   activeTagId, setActiveTagId(id|null),             // mutually exclusive with category
+//   hasMore, loadMore(), loadingMore,
+//   error /* set → posts may be [] and that is NOT an empty blog: render the error, not the empty state */ }
+// Filters and paging run on Wix (a changed filter restarts the list; a late response is dropped).
+// A category/tag page seeds a FILTERED first page: pass initialCategoryId/initialTagId with initialPage.
+
+// usePost({ slug, initialPost?, initialCategories?, initialTags?, initialRelated?, engagement? /* true */ }) →
+// { post: PostDetail|null, notFound /* true = render a 404 state, never invent a post */,
+//   categories, tags /* THIS post's, in ITS order, resolved — display .label */,
+//   related: PostSummary[]|null /* curated, else same-category recents; max 3 */,
+//   isLiked, likeCount /* fresh count + this viewer's change; undefined = unknown */, likeCountLoaded,
+//   viewCount, commentCount, liking, toggleLike() /* optimistic, rolls back */, error }
+// The like state is personal and read in the browser only; on the server it stays false/unloaded.
+
+// useComments({ referenceId, pageSize? /* 10 */, sort? /* "NEWEST_FIRST" */ }) →
+// { comments: BlogComment[]|null /* top-level; null = loading */,
+//   replies: { [topLevelId]: { comments, nextCursor, loading } } /* replies load on demand */,
+//   hasMore, loadMore(), loadingMore, loadReplies(topLevelId),
+//   sort, setSort("NEWEST_FIRST" | "OLDEST_FIRST"),
+//   create(text, { parentId?, topLevelId? }) → BlogComment|null, remove(id),
+//   saving, needsSignIn /* the server refused this identity → "sign in to comment" */,
+//   currentMemberId, error }
+// Mount only when post.commentingEnabled && post.referenceId. Replies to replies keep parentId
+// (render "replying to parentAuthorName") but sit in their top-level comment's thread (two levels).
+
+// <RichContent content={post.richContent} fallbackParagraphs={post.paragraphs} />
+//   — the ONLY post-body render path; comments render their plain `text` (no viewer: their island is SSR'd). In Astro: client:only="react".
+```
+
+### The island you create — skeleton
+
+The Astro pages ship; their frontmatter is machinery (SSR fetch → DTO props → island; the item
+pages' SEO blocks) and stays as shipped. What you create is the feed island `blog.astro` and the
+category/tag pages mount (and, in a SPA, the post surface — `PostView.tsx` shows its shape). Hooks
+first, branches after (an early return above a hook changes hook order and React throws). Islands
+render on the server too, after the 200 is sent — nothing in a render path may throw.
+
+```tsx
+// src/components/blog/<YourFeed>.tsx — YOU build it; blog.astro and the category/tag pages mount it.
+import { useBlogFeed } from "../../hooks/blog/useBlogFeed";
+import { categoryPath, formatCount, postMetaLine, postPath } from "../../wix/blog/posts";
+import { imgAttrs } from "../../wix/media";
+import type { BlogCategory, BlogTag, PostPage } from "../../wix/blog/types";
+
+export default function YourFeed(props: {
+  initialPage?: PostPage;              // SSR props — pass straight to useBlogFeed; omitted in a SPA
+  initialCategoryId?: string | null;   // the filter initialPage was fetched with (category page)
+  initialTagId?: string | null;        // (tag page)
+  initialCategories?: BlogCategory[];
+  initialTags?: BlogTag[];
+}) {
+  const feed = useBlogFeed(props);
+  const { posts, categories, activeCategoryId, hasMore, loadMore, loadingMore, error } = feed;
+  // …you implement the render:
+  //   • a category row when more than one category has posts (categories.filter(c => c.postCount > 0)):
+  //     "All" (href "/blog") first, then <a href={categoryPath(c.slug)}> per category, the active one
+  //     marked by activeCategoryId (or buttons calling setActiveCategoryId for client-side filtering)
+  //   • error → a short inline message; the empty state ONLY when !error
+  //   • posts === null → skeleton tiles; [] → your honest empty state
+  //   • else YOUR grid of YOUR tiles: cover via
+  //     <img {...imgAttrs(p.coverUrl, "(min-width: 1024px) 33vw, 100vw", 9 / 16)} alt={p.coverAlt} /> — {} when
+  //     there is no cover, render your placeholder then; title WRAPS (no truncate); excerpt clamped;
+  //     <time dateTime={p.dateISO}>{postMetaLine(p)}</time>; byline only when p.authorName; counters only
+  //     when defined (`${formatCount(p.viewCount)} views`); the tile links to postPath(p.slug)
+  //   • hasMore → your "load more" control calling loadMore() (disabled while loadingMore)
+}
+```
+
+### The reference files for stacks where the components don't deploy
+
+On `lib`, `static`, and a port, nothing under `components/` or `hooks/` arrives. The state
+machines behind the hooks do arrive — `wix/blog/blog-feed-store.ts`, `post-store.ts`,
+`comments-store.ts` — so you never rewrite them: create a store per surface, `subscribe`, render
+from `getState()`, call its actions. Their `*State` interfaces are the render contract; read those.
+What you write is the rendering — card, grid, filter row, post header, comment list — and for that
+read these first; they are tested code for exactly that behaviour:
+
+1. `components/blog/BlogFeedView.tsx` — the filter row (only categories with posts, "All" first,
+   one active pill, pills as links or buttons), the skeleton grid while `posts === null`, the empty
+   state only without an error, load-more disabled while loading; `PostCard` inside it is the tile:
+   16:9 cover with the DTO's alt, wrapping title, clamped excerpt, the meta line in a `<time>`, the
+   byline/counters only when present.
+2. `components/blog/PostView.tsx` — the states in order (not found → error → loading → article),
+   the categories eyebrow by `.label` in the post's order, the byline, the engagement row, the tag
+   chips, the related strip, the comments gate.
+3. `components/blog/PostLikeButton.tsx` — the like control: `aria-pressed`, disabled while `liking`,
+   a skeleton for the count until `likeCountLoaded`, counters only when defined.
+4. `components/blog/CommentsView.tsx` — the thread: two levels, "replying to", PENDING badge,
+   DELETED placeholder, delete on `isOwn`, "Show N replies" on the seam, the sign-in prompt on
+   `needsSignIn`, the form disabled while `saving`.
+5. `components/blog/RichContent.tsx` — what the body renderer is: the `@wix/ricos` viewer, a React
+   component that needs a bundler. On these stacks it doesn't run; the body renders from
+   `post.paragraphs` (one `<p>` per entry) and a comment from `comment.text`, and headings, lists,
+   quotes, and inline images flatten to text — say so in the closing message. A blog whose posts
+   carry structure stays on Astro.
+
+All under `templates/blog/app/`.
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the
+   other vertical's layout instead if both are deployed).
+2. Write your feed island under `src/components/blog/` (a new name — don't overwrite the
+   references), swap the island import in `pages/blog.astro`, `pages/blog/category/[slug].astro`,
+   and `pages/blog/tag/[slug].astro`, and restyle the `pages/blog/[...slug].astro` template (keep its
+   frontmatter + SEO pieces + the `client:only="react"` RichContent island; the like row and
+   comments stay `client:load` islands — they read as the viewer). **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 — another JS framework (`--stack lib`: Vue, Svelte, Solid, plain Vite)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs blog --stack lib` put the data layer in `src/wix/` and nothing else: `sdk.ts` (the
+visitor client, configured with the public client id), `media.ts`, `money.ts`, and `wix/blog/` —
+`posts.ts`, `taxonomy.ts`, `authors.ts`, `post-likes.ts`, `comments.ts`, `types.ts`, the `*-core.ts`
+rules, and the three stores `blog-feed-store.ts`, `post-store.ts`, `comments-store.ts`. None of it is
+React. The hooks and components don't ship on this stack; the stores replace the hooks, and you write
+the components in your framework to the contracts on this page:
+
+- bind the stores with your framework's external-store primitive (Vue: `shallowRef` updated in
+  `subscribe`; Svelte: `readable(store.getState(), (set) => store.subscribe(() => set(store.getState())))`;
+  Solid: a signal set in `subscribe`). `createBlogFeedStore(options)` per feed (`start()` when
+  mounted, `stop()` when unmounted), `createPostStore({ slug, initialPost? })` per post surface,
+  `createCommentsStore({ referenceId })` per thread (only when `commentingEnabled && referenceId`).
+  State in, actions out — exactly the hooks' contracts above;
+- the body: `@wix/ricos` is a React component — without React it doesn't render; use
+  `post.paragraphs` (and `comment.text`) and say so in the closing message.
+
+Routes `/blog`, `/blog/:slug` (null → your 404 view), `/blog/category/:slug`, `/blog/tag/:slug`
+(`fetchCategoryBySlug`/`fetchTagBySlug` → `createBlogFeedStore({ initialCategoryId })` or a plain
+`setActiveCategoryId`); dev server on 4321; a static build goes through `npx @wix/cli@latest release`
+with `site.outputDirectory` pointing at the build folder, an SSR build is hosted by you. Post-page
+tags from `post.seoTitle` and `post.seoDescription`.
+
+### Wiring — static site (`--stack static`, no bundler)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs blog --stack static --out site` put the REST layer in `site/js/wix/` (browser ESM,
+the `.ts` beside each `.js` for reading). Everything the visitor loads lives under `site/` —
+pages, styles, `js/` — and `wix.config.json`'s `site.outputDirectory` is `"./site"`; the project
+root (config, plan, seed output) is never the upload. Same function names and DTOs as the table
+above, so the contracts on this page hold unchanged: `fetchPosts`, `fetchPostBySlug`,
+`fetchRelatedPosts`, `postMetaLine`, `postPath`, `categoryPath`, `tagPath`, `formatCount` from
+`./js/wix/posts.js`; `fetchBlogCategories`, `fetchBlogTags`, `fetchTagsByIds`, `fetchCategoryBySlug`,
+`fetchTagBySlug` from `./js/wix/taxonomy.js`; `likePost`/`unlikePost`/`fetchLikeState` from
+`./js/wix/post-likes.js`; the comments from `./js/wix/comments.js`; `imgAttrs` from
+`./js/wix/media.js`. The state machines ship too: `createBlogFeedStore` from
+`./js/wix/blog-feed-store.js` (the feed — filters, cursor paging; `start()` once the page is up),
+`createPostStore` from `./js/wix/post-store.js` (the post, its resolved chips, related, the like
+toggle), and `createCommentsStore` from `./js/wix/comments-store.js`. No components ship — you write
+the rendering in plain JS: one render function per surface that reads `getState()`, called from
+`subscribe`, with the surface's controls calling the store's actions. Pages are `blog.html`,
+`post.html?slug=…`, `category.html?slug=…`, `tag.html?slug=…` (Wix static hosting serves files, not
+directories — name the file and link to it; on this stack pass your own `postHref`-style helpers to
+your renderers, the path helpers describe the Astro routes). The body renders from
+`post.paragraphs` and a comment from `comment.text` (no Ricos viewer without a bundler — see the
+reference files note). Set `document.title` and the meta description from `post.seoTitle` and
+`post.seoDescription` once the post loads, as the Astro page does. The visitor token persists in
+`localStorage` on its own; never mint per page. `npx @wix/cli@latest release` uploads `site/`.
+
+### Wiring — server-rendered, another language (Flask, Laravel, Rails, …)
+
+Read the reference files listed above before writing any surface.
+
+Run `deploy.mjs blog --stack static` in the project folder anyway: `js/wix/` is both the
+browser-side code and the readable spec. Reads render on the server: port `js/wix/posts.ts`,
+`taxonomy.ts`, `authors.ts` and their `*-core.ts` to your language — the same functions returning
+the same DTO shapes as dicts, one anonymous visitor token per process for these public reads (mint
+and refresh per `client.ts`) — and render the feed, the category/tag pages, and the post page in your
+templates to the contracts above, so titles and excerpts are in the HTML; post-page tags from
+`post.seoTitle` and `post.seoDescription`. The body is `paragraphs` server-side too (the Ricos
+viewer is React). Likes and comments run on the visitor's behalf — they are browser-side only, on
+`./js/wix/post-store.js` and `./js/wix/comments-store.js` exactly as the static wiring above (never
+through the process-wide token: a like or a comment would be attributed to it). The feed's category
+filter and load-more can run client-side on `./js/wix/blog-feed-store.js` the same way, or as plain
+server routes (`/blog/category/<slug>` via `fetchCategoryBySlug`, paging by cursor). Routes stay
+`/blog`, `/blog/<slug>`, `/blog/category/<slug>`, `/blog/tag/<slug>`.
+
+**Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted.** Same port for
+the reads, run at build time with one anonymous token; the generator must emit a page for every
+post and every category — walk `fetchPosts` by `nextCursor` until it is null, never only the first
+page. Run `deploy.mjs blog --stack static --out <build dir>` so `js/wix/` is inside the output the
+pages import from, point `site.outputDirectory` at that folder, `wix release`. Pages sit at
+different depths (`/`, `/blog/…`): give the templates one base path to `js/wix/` (a template
+variable, or root-relative `/js/wix/…`), never a relative `./js/wix/`. The frozen grid is the first
+paint; the category filter, load-more, likes, and comments still run client-side on the stores
+from `./js/wix/`. Close with the live URL, the rebuild + release command, and one line for the owner:
+posts published in the dashboard reach the site when that command runs.
+
+### 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: `/blog` → your feed on `useBlogFeed`;
+`/blog/category/:slug` and `/blog/tag/:slug` → the same feed with `initialCategoryId`/`initialTagId`
+(resolve the slug with `fetchCategoryBySlug`/`fetchTagBySlug`); `/blog/:slug` → your post surface on
+`usePost({ slug })` (the `PostView` reference shows the shape; `notFound` → your 404 view). Deploy
+wrote the public client id into `wix/config.ts`; nothing else to configure.
+
+Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1).
+
+## Likes, views, comments — what the shipped layer can and cannot do
+
+- **Likes** run as the current identity (a member, or the anonymous visitor the token stands for):
+  optimistic toggle, rolled back on failure, in the browser only. The count shown is the fresh
+  metrics read (else the card's) plus this viewer's change.
+- **View counting is not shipped**: `@wix/blog` in this template (1.0.645) has no `viewPost`; the
+  installed SDK has to expose it before a page can count a view. Views still display from METRICS.
+- **Comments** address the thread by `referenceId` as both contextId and resourceId, with the Blog
+  app id — the public-SDK shape Wix's own headless blog uses. Verified live: the REFERENCE_ID
+  fieldset returns the post without that field, the INTERNAL_ID fieldset carries it, and it equalled
+  the post id on every post read — so the detail read asks for both and `posts-core.ts` falls back
+  to the post id (what Wix's classic Blog widget addresses the thread by). A post page that shows no
+  comments section therefore means `commentingEnabled` is off, not a missing id.
+- Who may comment (members only, or guests too) is the dashboard's "Who can comment" setting,
+  decided by the server: submit as the current session; a refusal sets `needsSignIn`. Comments may
+  come back PENDING when the owner moderates — show "awaiting approval", never drop them.
+- The site-wide comments master switch (Blog settings) has no public read: a post says
+  `commentingEnabled` even when the owner turned comments off for the whole blog. Say so in the
+  closing message when you ship comments.
+- Members and comments go over the SDK's authenticated fetch (`wixFetch`) with literal REST paths —
+  the template does not depend on `@wix/members` or `@wix/comments`; the REST twins use the same paths.
+
+## Hard rules
+
+- **The body renders only through `RichContent`** where it deploys (Astro, React) — a post body
+  is a Ricos document, not HTML and not text: never `set:html`/innerHTML it, never stringify its
+  nodes, never write your own node walker. Where it doesn't deploy, `paragraphs` is the honest
+  body, and the closing message says so.
+- **Data logic only through the shipped exports** — never rewrite their internals or re-derive a
+  request shape; extend by adding a function in `wix/blog/` (API contracts: the `wix-docs` skill).
+- **Route by `slug` through the shipped path helpers** — `postPath`, `categoryPath`, `tagPath`;
+  never hand-build a post/category/tag URL from ids or from `post.url`; display taxonomy by `.label`
+  (the API has no `.name`).
+- **`notFound` means not found** — render your 404 state; never invent a post. Only published
+  posts come back, so a "missing" post is usually an unseeded/unpublished one.
+- **Filter and page at the source** — `useBlogFeed`'s filters and `fetchPosts` run on Wix before
+  cursor paging; never filter a loaded page client-side, never raise the page limit instead of
+  paging (`hasMore`/`loadMore`).
+- **Never hand-build a wixstatic image URL** — `coverUrl` and `authorAvatarUrl` are already
+  resolved; anything else goes through `wix/media.ts`.
+- **Error is not empty** — render the empty state only when `error` is null; a failed read shows the
+  error state.
+- Where the shipped components deploy: theme via the `@theme` tokens, your markup in Tailwind
+  utilities on the same tokens; no parallel theme files, no hardcoded palettes. Where they don't
+  (`lib`, `static`, a port): style with what your stack does well, on one token set of your own.
+- Live data or an honest empty state — never mock posts, authors, dates, counts, or read times; no
+  stock placeholder covers. **Render only what the DTO carries**: a byline needs `authorName`, a
+  counter needs a defined number, a like control needs the post, a comments section needs
+  `commentingEnabled && referenceId`.
+- Keep the post and category pages' SEO pieces and the `[...slug]` rest param exactly as shipped;
+  an item page whose `<SEO.Tags>` resolved passes no title/description to the layout.
+- Likes and comments are the viewer's — client-side only, never during SSR or through a shared
+  server token.
+- **Call every hook before any conditional return.** Hooks first, branches after.
+
+## Point the user to their dashboard
+
+Hand the owner these links — `{siteId}` is `siteId` in `wix.config.json` (the deploy JSON prints it as
+`dashboardUrl`).
+
+| page | `https://manage.wix.com/dashboard/{siteId}/` + |
+|---|---|
+| Posts (published and drafts) | `blog/posts` |
+| Categories | `blog/categories` |
+| Tags | `blog/tags` |
+| Writers | `blog/writers` |
+| Comments | `blog/comments` |
+| Blog settings | `blog/settings` |
+
+Only published posts appear on the site. Pinned posts lead the feed; a post's related posts, cover
+visibility, alt text, SEO title/description, and per-post comments switch are set on the post.
+
+## Seeding
+
+Per `seed/SEED.md` — plain-data `plan.json` into `seed-blog.mjs` from the project root.
+Seed posts that exercise the UI (~3 posts, 2 categories when the brief has sections, varied
+content blocks, a cover image per post). Authors resolve to the site owner's member profile — set a
+nickname and photo in the dashboard for a real byline.

package/skills/wix-headless-templates/blog/app/components/blog/BlogFeedView.tsx

@@ -0,0 +1,191 @@
+// REFERENCE feed surface: taxonomy filter chips + post grid + load-more on the @theme tokens.
+// Correct and complete; per the skill's model you design and build your own on useBlogFeed.
+// What it gets right that yours must too: the empty state renders only when there is NO error; a
+// byline, a counter, or a cover appears only when the DTO carries one; hrefs come from the path
+// helpers (slugs may contain "/"); the cover's alt is the DTO's.
+import type { ComponentType, ReactNode } from "react";
+import { useBlogFeed } from "../../hooks/blog/useBlogFeed";
+import { formatCount, postMetaLine, postPath } from "../../wix/blog/posts";
+import type { BlogCategory, BlogTag, PostPage, PostSummary } from "../../wix/blog/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+  "aria-current"?: "page";
+}
+
+const PlainLink = ({ href, className, children, ...rest }: LinkLikeProps) => (
+  <a href={href} className={className} {...rest}>
+    {children}
+  </a>
+);
+
+export interface PostCardProps {
+  post: PostSummary;
+  postHref?: (slug: string) => string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+/** "By <author> · 1.2K views · 3 comments" — only the parts the post carries. */
+export function PostByline({ post }: { post: PostSummary }) {
+  const parts = [
+    post.authorName,
+    post.viewCount !== undefined ? `${formatCount(post.viewCount)} views` : "",
+    post.commentCount !== undefined ? `${formatCount(post.commentCount)} comments` : "",
+    post.likeCount !== undefined ? `${formatCount(post.likeCount)} likes` : "",
+  ].filter(Boolean);
+  if (!parts.length) return null;
+  return (
+    <p className="mt-2 flex items-center gap-2 text-xs text-muted-foreground">
+      {post.authorAvatarUrl && <img src={post.authorAvatarUrl} alt="" width={20} height={20} loading="lazy" className="h-5 w-5 rounded-full object-cover" />}
+      <span>{parts.join(" · ")}</span>
+    </p>
+  );
+}
+
+export function PostCard({ post, postHref = postPath, LinkComponent = PlainLink }: PostCardProps) {
+  return (
+    <LinkComponent href={postHref(post.slug)} className="group block no-underline">
+      {post.coverUrl && (
+        <div className="aspect-[16/9] overflow-hidden rounded-lg bg-secondary">
+          <img
+            src={post.coverUrl}
+            alt={post.coverAlt}
+            loading="lazy"
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
+          />
+        </div>
+      )}
+      <h3 className="mt-3 text-base font-semibold leading-snug text-foreground">{post.title}</h3>
+      {post.excerpt && <p className="mt-1 line-clamp-2 text-sm text-muted-foreground">{post.excerpt}</p>}
+      <p className="mt-2 text-xs text-muted-foreground">
+        <time dateTime={post.dateISO}>{postMetaLine(post)}</time>
+      </p>
+      <PostByline post={post} />
+    </LinkComponent>
+  );
+}
+
+export interface BlogFeedViewProps {
+  initialPage?: PostPage;
+  /** The filter `initialPage` was fetched with (a category/tag page). */
+  initialCategoryId?: string | null;
+  initialTagId?: string | null;
+  initialCategories?: BlogCategory[];
+  initialTags?: BlogTag[];
+  emptyMessage?: string;
+  postHref?: PostCardProps["postHref"];
+  /**
+   * When given, category pills are LINKS to category pages (and "All" to `allHref`) instead of
+   * client-side filters — the choice for a site with category pages, so every filter has a URL.
+   */
+  categoryHref?: (slug: string) => string;
+  allHref?: string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+  CardComponent?: ComponentType<PostCardProps>;
+}
+
+const pill = (active: boolean) =>
+  `rounded-control border px-4 py-1.5 text-sm font-medium no-underline transition-colors ${
+    active
+      ? "border-primary bg-primary text-primary-foreground"
+      : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function BlogFeedView({
+  initialPage,
+  initialCategoryId,
+  initialTagId,
+  initialCategories,
+  initialTags,
+  emptyMessage = "No posts yet — check back soon.",
+  postHref,
+  categoryHref,
+  allHref = "/blog",
+  LinkComponent = PlainLink,
+  CardComponent = PostCard,
+}: BlogFeedViewProps) {
+  const {
+    posts,
+    categories,
+    activeCategoryId,
+    setActiveCategoryId,
+    hasMore,
+    loadMore,
+    loadingMore,
+    error,
+  } = useBlogFeed({ initialPage, initialCategoryId, initialTagId, initialCategories, initialTags });
+
+  const visibleCategories = categories.filter((c) => c.postCount > 0);
+
+  return (
+    <div>
+      {visibleCategories.length > 1 && (
+        <div className="mb-8 flex flex-wrap gap-2" role="group" aria-label="Categories">
+          {categoryHref ? (
+            <>
+              <LinkComponent href={allHref} className={pill(activeCategoryId === null)} aria-current={activeCategoryId === null ? "page" : undefined}>
+                All
+              </LinkComponent>
+              {visibleCategories.map((c) => (
+                <LinkComponent key={c.id} href={categoryHref(c.slug)} className={pill(activeCategoryId === c.id)} aria-current={activeCategoryId === c.id ? "page" : undefined}>
+                  {c.label}
+                </LinkComponent>
+              ))}
+            </>
+          ) : (
+            <>
+              <button type="button" className={pill(activeCategoryId === null)} onClick={() => setActiveCategoryId(null)}>
+                All
+              </button>
+              {visibleCategories.map((c) => (
+                <button key={c.id} type="button" className={pill(activeCategoryId === c.id)} onClick={() => setActiveCategoryId(c.id)}>
+                  {c.label}
+                </button>
+              ))}
+            </>
+          )}
+        </div>
+      )}
+      {error && (
+        <p className="py-16 text-center text-sm text-destructive" role="alert">
+          The posts could not be loaded. {error}
+        </p>
+      )}
+      {posts === 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-[16/9] animate-pulse rounded-lg bg-secondary" />
+              <div className="mt-3 h-3.5 w-2/3 animate-pulse rounded bg-secondary" />
+            </div>
+          ))}
+        </div>
+      ) : posts.length === 0 ? (
+        // An empty list over a failed read is not an empty blog — the error above is the state then.
+        !error && <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">
+            {posts.map((p) => (
+              <CardComponent key={p.id} post={p} postHref={postHref} LinkComponent={LinkComponent} />
+            ))}
+          </div>
+          {hasMore && (
+            <div className="mt-10 text-center">
+              <button
+                type="button"
+                onClick={loadMore}
+                disabled={loadingMore}
+                className="rounded-lg border border-border px-6 py-2.5 text-sm font-medium text-foreground transition-colors hover:bg-secondary disabled:opacity-50"
+              >
+                {loadingMore ? "Loading…" : "Load more"}
+              </button>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  );
+}