@wix/agent-skills 1.21.0 → 1.22.0

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

@@ -1,303 +0,0 @@
-# Blog — playbook
-
-The blog machinery ships as files — post reads (feed paging, slug lookup with the body
-fieldsets), category/tag taxonomy, the feed and post 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 post page surface, the home page, and the brand.
-You never write blog data logic; you never skip designing. The vertical is **read-only** —
-visitors read posts; authoring stays in the dashboard.
-
-## 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 two
-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.title} />`; `imgSrc()` / `imgSrcSet()` underneath |
-| `wix/blog/types.ts` | the DTOs (`PostSummary`, `PostDetail`, `BlogCategory`, `BlogTag`, `PostPage`) — contracts inlined below |
-| `wix/blog/posts.ts` | `fetchPosts` (cursor-paged, category/tag filtered on Wix), `fetchPostBySlug` (full body), `postMetaLine(post)` ("Aug 27, 2026 · 4 min read") — the transport; the rules and DTO mappers are in `posts-core.ts` beside it (shared with the REST layer) |
-| `wix/blog/taxonomy.ts` | `fetchBlogCategories`, `fetchBlogTags`, `fetchCategoryBySlug`, `fetchTagBySlug` — the transport; mappers in `taxonomy-core.ts` |
-| `wix/blog/blog-feed-store.ts` · `post-store.ts` | the feed and post state machines, framework-free (`createBlogFeedStore()`, `createPostStore()` — `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 — contract below |
-| `components/blog/RichContent.tsx` | the post-body renderer — **wire as-is** (machinery, not a reference) |
-| `components/blog/BlogFeedView.tsx` (+ `PostCard`) · `PostView.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). 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. The body island stays `client:only="react"` (the ricos viewer breaks under SSR). A slug that resolves to nothing returns a real 404 |
-
-## What you build — the design job
-
-1. **The post card + grid** — your tile (cover, title, excerpt, `postMetaLine(post)`) and rhythm,
-   with skeletons while `posts === null` and an honest empty state for `[]`.
-2. **The blog index surface** — the feed island on `useBlogFeed`: category filter (only when >1
-   non-empty category), the grid, and a load-more control gated on `hasMore`.
-3. **The post page surface** — header (categories eyebrow, title, meta line, cover), the body via
-   the shipped `RichContent`, and the tag chips — restyle the `[...slug].astro` template around it.
-4. **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 the feed filtered to it, never to an anchor.
-- **Index:** a real card — cover, title, meta line — 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; load-more, never a raised page size.
-- **Post page:** eyebrow, title, meta line, cover as a bounded band on phones (`max-h-[45vh]`), the
-  body, then the tags; a slug that resolves to nothing shows only the not-found state.
-- **Copy:** nothing the author didn't write — no invented bylines, comment counts, likes, or
-  "trending" labels; no Wix IDs or technical words in visible text.
-
-### 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, 16:9 */,
-//   categoryIds, tagIds }
-// 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.
-// PostDetail adds: richContent (Ricos JSON | null — render ONLY via RichContent),
-//   paragraphs (plain-text fallback body).
-// BlogCategory: { id, slug, label, description, postCount, coverUrl }   // display .label
-// BlogTag:      { id, slug, label, postCount /* published posts */ }
-
-// useBlogFeed({ initialPage?, 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 }
-// Filters and paging run on Wix (a changed filter restarts the list; a late response is dropped).
-
-// usePost({ slug, initialPost?, initialCategories?, initialTags? }) →
-// { post: PostDetail|null, notFound /* true = render a 404 state, never invent a post */,
-//   categories, tags /* THIS post's, resolved — display .label */, error }
-
-// <RichContent content={post.richContent} fallbackParagraphs={post.paragraphs} />
-//   — the ONLY body render path. In Astro: client:only="react".
-```
-
-### The island you create — skeleton
-
-The two Astro pages ship; their frontmatter is machinery (SSR fetch → DTO props → island; the
-post page's SEO block) and stays as shipped. What you create is the feed island `blog.astro` mounts
-(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 mounts it (swap the import there).
-import { useBlogFeed } from "../../hooks/blog/useBlogFeed";
-import { postMetaLine } 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 from blog.astro — pass straight to useBlogFeed;
-  initialCategories?: BlogCategory[];  // omitted in a SPA (client fetch)
-  initialTags?: BlogTag[];
-}) {
-  const feed = useBlogFeed(props);
-  const { posts, categories, activeCategoryId, setActiveCategoryId, 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" (null) first, the active one marked by activeCategoryId, each calling setActiveCategoryId
-  //   • error → a short inline message
-  //   • 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.title} /> — {} when
-  //     there is no cover, render your placeholder then; title WRAPS (no truncate); excerpt clamped;
-  //     <time dateTime={p.dateISO}>{postMetaLine(p)}</time>; the tile links to `/blog/${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` — 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 — 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), the skeleton grid while `posts === null`, the empty state, load-more disabled
-   while loading; `PostCard` inside it is the tile: 16:9 cover, wrapping title, clamped excerpt,
-   the meta line in a `<time>`.
-2. `components/blog/PostView.tsx` — the states in order (not found → error → loading → article),
-   the categories eyebrow by `.label`, the tag chips, the body slot.
-3. `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 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 `references/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`, and restyle the
-   `pages/blog/[...slug].astro` template (keep its frontmatter + SEO pieces + the
-   `client:only="react"` RichContent island). **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`, `types.ts`, the `*-core.ts` rules, and the two stores
-`blog-feed-store.ts`, `post-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.
-  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 say so in the closing message.
-
-Routes `/blog`, `/blog/:slug` (null → your 404 view); 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.title` and `post.excerpt`.
-
-### 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`,
-`postMetaLine` from `./js/wix/posts.js`; `fetchBlogCategories`, `fetchBlogTags`,
-`fetchCategoryBySlug`, `fetchTagBySlug` from `./js/wix/taxonomy.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)
-and `createPostStore` from `./js/wix/post-store.js` (the post and its resolved chips). 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` and `post.html?slug=…` (Wix static hosting serves files, not directories —
-name the file and link to it). The body renders from `post.paragraphs` (no Ricos viewer without a
-bundler — see the reference files note). Set `document.title` and the meta description from
-`post.title` and `post.excerpt` 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` and their `*-core.ts` to your language — the same six 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 and the post page in your templates to the
-contracts above, so titles and excerpts are in the HTML; post-page tags from `post.title` and
-`post.excerpt`. The body is `paragraphs` server-side too (the Ricos viewer is React). Nothing in
-this vertical runs on the visitor's behalf, so the browser side is optional: the feed's category
-filter and load-more can run client-side on `./js/wix/blog-feed-store.js` exactly as the static
-wiring above, or as plain server routes (`/blog?category=<slug>` via `fetchCategoryBySlug`,
-paging by cursor). Routes stay `/blog`, `/blog/<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 — 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 and load-more still run client-side on it through `createBlogFeedStore()` from
-`./js/wix/blog-feed-store.js`. 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/: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).
-
-## 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 functions** — never hand-build a post/category/tag URL
-  from ids; 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` is already resolved; anything else goes
-  through `wix/media.ts`.
-- 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, or read times; no stock
-  placeholder covers. No author bylines or comment/like UI — the DTOs don't carry them.
-- Keep the post page's SEO pieces and `[...slug]` rest param exactly as shipped.
-- **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.
-
-## 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).

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

@@ -1,136 +0,0 @@
-// 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.
-import type { ComponentType, ReactNode } from "react";
-import { useBlogFeed } from "../../hooks/blog/useBlogFeed";
-import { postMetaLine } from "../../wix/blog/posts";
-import type { BlogCategory, BlogTag, PostPage, PostSummary } from "../../wix/blog/types";
-
-export interface LinkLikeProps {
-  href: string;
-  className?: string;
-  children?: ReactNode;
-}
-
-const PlainLink = ({ href, className, children }: LinkLikeProps) => (
-  <a href={href} className={className}>
-    {children}
-  </a>
-);
-
-export interface PostCardProps {
-  post: PostSummary;
-  postHref?: (slug: string) => string;
-  LinkComponent?: ComponentType<LinkLikeProps>;
-}
-
-export function PostCard({ post, postHref = (slug) => `/blog/${slug}`, 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.title}
-            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>
-    </LinkComponent>
-  );
-}
-
-export interface BlogFeedViewProps {
-  initialPage?: PostPage;
-  initialCategories?: BlogCategory[];
-  initialTags?: BlogTag[];
-  emptyMessage?: string;
-  postHref?: PostCardProps["postHref"];
-  LinkComponent?: ComponentType<LinkLikeProps>;
-  CardComponent?: ComponentType<PostCardProps>;
-}
-
-const pill = (active: boolean) =>
-  `rounded-full border px-4 py-1.5 text-sm font-medium transition-colors ${
-    active
-      ? "border-primary bg-primary text-primary-foreground"
-      : "border-border text-foreground hover:bg-secondary"
-  }`;
-
-export default function BlogFeedView({
-  initialPage,
-  initialCategories,
-  initialTags,
-  emptyMessage = "No posts yet — check back soon.",
-  postHref,
-  LinkComponent,
-  CardComponent = PostCard,
-}: BlogFeedViewProps) {
-  const {
-    posts,
-    categories,
-    activeCategoryId,
-    setActiveCategoryId,
-    hasMore,
-    loadMore,
-    loadingMore,
-    error,
-  } = useBlogFeed({ initialPage, 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">
-          <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="mb-4 text-sm text-red-600">{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 ? (
-        <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>
-  );
-}

package/skills/wix-headless-fast/references/blog/app/components/blog/PostView.tsx

@@ -1,112 +0,0 @@
-// REFERENCE post surface (SPA use — Astro renders the header statically and mounts only
-// RichContent as an island). Correct and complete; per the skill's model you design and
-// build your own on usePost. Chips display .label; the body renders ONLY via RichContent.
-import type { ComponentType } from "react";
-import { usePost } from "../../hooks/blog/usePost";
-import { postMetaLine } from "../../wix/blog/posts";
-import type { BlogCategory, BlogTag, PostDetail } from "../../wix/blog/types";
-import RichContent from "./RichContent";
-import type { LinkLikeProps } from "./BlogFeedView";
-
-export interface PostViewProps {
-  slug: string;
-  initialPost?: PostDetail;
-  initialCategories?: BlogCategory[];
-  initialTags?: BlogTag[];
-  /** Where a chip routes; omit to render chips as plain labels. */
-  categoryHref?: (slug: string) => string;
-  tagHref?: (slug: string) => string;
-  LinkComponent?: ComponentType<LinkLikeProps>;
-}
-
-const PlainLink = ({ href, className, children }: LinkLikeProps) => (
-  <a href={href} className={className}>
-    {children}
-  </a>
-);
-
-const chipClass =
-  "rounded-full border border-border px-3 py-1 text-xs font-medium text-muted-foreground no-underline";
-
-export default function PostView({
-  slug,
-  initialPost,
-  initialCategories,
-  initialTags,
-  categoryHref,
-  tagHref,
-  LinkComponent = PlainLink,
-}: PostViewProps) {
-  const { post, notFound, categories, tags, error } = usePost({
-    slug,
-    initialPost,
-    initialCategories,
-    initialTags,
-  });
-
-  if (notFound) {
-    return (
-      <div className="py-24 text-center">
-        <p className="text-lg font-medium">Post not found</p>
-        <p className="mt-2 text-sm text-muted-foreground">It may have been unpublished or moved.</p>
-      </div>
-    );
-  }
-  if (error) return <p className="py-8 text-sm text-red-600">{error}</p>;
-  if (post === null) {
-    return (
-      <div aria-busy="true">
-        <div className="h-8 w-2/3 animate-pulse rounded bg-secondary" />
-        <div className="mt-6 aspect-[16/9] animate-pulse rounded-lg bg-secondary" />
-      </div>
-    );
-  }
-
-  return (
-    <article className="mx-auto max-w-3xl">
-      {categories.length > 0 && (
-        <p className="eyebrow">
-          {categories.map((c, i) => (
-            <span key={c.id}>
-              {i > 0 && " · "}
-              {categoryHref ? (
-                <LinkComponent href={categoryHref(c.slug)} className="no-underline">
-                  {c.label}
-                </LinkComponent>
-              ) : (
-                c.label
-              )}
-            </span>
-          ))}
-        </p>
-      )}
-      <h1 className="mt-2 text-3xl font-semibold tracking-tight">{post.title}</h1>
-      <p className="mt-3 text-sm text-muted-foreground">
-        <time dateTime={post.dateISO}>{postMetaLine(post)}</time>
-      </p>
-      {post.coverUrl && (
-        <div className="mt-6 aspect-[16/9] overflow-hidden rounded-xl bg-secondary">
-          <img src={post.coverUrl} alt={post.title} className="h-full w-full object-cover" />
-        </div>
-      )}
-      <div className="mt-8">
-        <RichContent content={post.richContent} fallbackParagraphs={post.paragraphs} />
-      </div>
-      {tags.length > 0 && (
-        <div className="mt-10 flex flex-wrap gap-2">
-          {tags.map((t) =>
-            tagHref ? (
-              <LinkComponent key={t.id} href={tagHref(t.slug)} className={chipClass}>
-                {t.label}
-              </LinkComponent>
-            ) : (
-              <span key={t.id} className={chipClass}>
-                {t.label}
-              </span>
-            ),
-          )}
-        </div>
-      )}
-    </article>
-  );
-}

package/skills/wix-headless-fast/references/blog/app/components/blog/RichContent.tsx

@@ -1,42 +0,0 @@
-// The post-body renderer — wire AS-IS (machinery, not a reference). A post body is a Ricos
-// document, not HTML and not text: never innerHTML it, never String() its nodes. This is the
-// documented render path (@wix/ricos viewer + quick-start plugins).
-//
-// In Astro this component MUST be a `client:only="react"` island — the ricos viewer breaks
-// under SSR. Dark theme: the ricos CSS hardcodes near-black text; scope an override on
-// `.ricos-content` forcing the foreground token (in Astro use <style is:global> — React
-// islands don't inherit scoped Astro styles).
-import { quickStartViewerPlugins, RicosViewer } from "@wix/ricos";
-import "@wix/ricos/css/all-plugins-viewer.css";
-
-// Module-level, once — never rebuild the plugin list per render.
-const plugins = quickStartViewerPlugins();
-
-export interface RichContentProps {
-  /** PostDetail.richContent — the Ricos document (plain JSON). */
-  content: Record<string, unknown> | null;
-  /** PostDetail.paragraphs — the honest fallback body when richContent is null. */
-  fallbackParagraphs?: string[];
-}
-
-export default function RichContent({ content, fallbackParagraphs = [] }: RichContentProps) {
-  if (content) {
-    return (
-      <div className="ricos-content">
-        <RicosViewer content={content as any} plugins={plugins} />
-      </div>
-    );
-  }
-  if (fallbackParagraphs.length > 0) {
-    return (
-      <div className="space-y-4">
-        {fallbackParagraphs.map((p, i) => (
-          <p key={i} className="leading-relaxed">
-            {p}
-          </p>
-        ))}
-      </div>
-    );
-  }
-  return null;
-}

package/skills/wix-headless-fast/references/blog/app/hooks/blog/useBlogFeed.ts

@@ -1,31 +0,0 @@
-// React binding of the blog feed store (wix/blog/blog-feed-store.ts) — the feed state machine
-// (taxonomy filter, cursor paging) lives there, framework-free; this hook subscribes to one
-// instance per mounted feed and exposes its state and actions under one name. Astro islands and
-// React SPAs use this; a static page, Vue, or Svelte uses the store directly.
-//
-// SSR-friendly: pass server-fetched data as `initial*` (Astro frontmatter / server component) and
-// no client fetch happens; a SPA passes nothing. Category/tag filtering fetches live
-// (server-side-filtered); the two filters are mutually exclusive — setting one clears the other.
-import { useEffect, useRef, useSyncExternalStore } from "react";
-import { createBlogFeedStore, type BlogFeedState, type BlogFeedStore, type BlogFeedStoreOptions } from "../../wix/blog/blog-feed-store";
-
-export type UseBlogFeedOptions = BlogFeedStoreOptions;
-
-export type UseBlogFeed = BlogFeedState & Pick<BlogFeedStore, "setActiveCategoryId" | "setActiveTagId" | "loadMore">;
-
-export function useBlogFeed(options: UseBlogFeedOptions = {}): UseBlogFeed {
-  const ref = useRef<BlogFeedStore | null>(null);
-  if (!ref.current) ref.current = createBlogFeedStore(options);
-  const store = ref.current;
-  useEffect(() => {
-    store.start();
-    return () => store.stop();
-  }, [store]);
-  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
-  return {
-    ...state,
-    setActiveCategoryId: store.setActiveCategoryId,
-    setActiveTagId: store.setActiveTagId,
-    loadMore: store.loadMore,
-  };
-}

package/skills/wix-headless-fast/references/blog/app/hooks/blog/usePost.ts

@@ -1,22 +0,0 @@
-// React binding of the post store (wix/blog/post-store.ts) — post-by-slug loading and the resolved
-// category/tag chips live there, framework-free; this hook subscribes to one instance per slug.
-//
-// SSR-friendly: pass the server-fetched post (and taxonomy) as `initial*` and no client fetch
-// happens; a SPA passes only the slug. A slug change creates a fresh store and refetches.
-import { useEffect, useRef, useSyncExternalStore } from "react";
-import { createPostStore, type PostState, type PostStore, type PostStoreOptions } from "../../wix/blog/post-store";
-
-export type UsePostOptions = PostStoreOptions;
-
-export type UsePost = PostState;
-
-export function usePost({ slug, initialPost, initialCategories, initialTags }: UsePostOptions): UsePost {
-  const ref = useRef<{ slug: string; store: PostStore } | null>(null);
-  if (!ref.current || ref.current.slug !== slug) ref.current = { slug, store: createPostStore({ slug, initialPost, initialCategories, initialTags }) };
-  const store = ref.current.store;
-  useEffect(() => {
-    store.start();
-    return () => store.stop();
-  }, [store]);
-  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
-}