@wix/agent-skills 1.17.0 → 1.18.1

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

@@ -0,0 +1,137 @@
+# Blog — playbook
+
+The blog machinery ships as files — post reads (feed paging, slug lookup with the body
+fieldsets), category/tag taxonomy, and the Ricos body renderer, typed end-to-end. **The
+presentation is yours**: you design and implement the post card, the grid, the blog index
+surface, and the post page surface on the shipped hooks/DTOs, plus 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/`)
+
+**Don't read the shipped files** — this table and the contracts below are everything you
+need. Open a shipped file's source only on a real fallback (runtime error / uncovered field),
+or to read a reference component's pattern.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` · `wix/media.ts` · `wix/money.ts` | shared auth seam + helpers (deploy configures; nothing to set) |
+| `wix/blog/types.ts` | the DTOs (`PostSummary`, `PostDetail`, `BlogCategory`, `BlogTag`, `PostPage`) — contracts below |
+| `wix/blog/posts.ts` | `fetchPosts` (paged, filterable), `fetchPostBySlug` (full body) |
+| `wix/blog/taxonomy.ts` | `fetchBlogCategories`, `fetchBlogTags`, `fetchCategoryBySlug`, `fetchTagBySlug` |
+| `hooks/blog/useBlogFeed.ts` | feed + taxonomy filter + load-more — contract below |
+| `hooks/blog/usePost.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) |
+
+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) |
+
+## What you build — the design job
+
+1. **The post card + grid** — your tile (cover, title, excerpt, date · min-read presentation)
+   and rhythm, with skeletons while loading and an honest empty state.
+2. **The blog index surface** — the feed 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, date, 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).
+
+### The contracts your components consume
+
+```ts
+// PostSummary (tiles) — display-ready:
+// { id, slug, title, excerpt, dateLabel /* "Aug 26, 2026" | "" */, dateISO,
+//   minutesToRead /* 0 = unknown */, featured, pinned, coverUrl /* "" = no cover */,
+//   categoryIds, tagIds }
+// 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 }
+
+// useBlogFeed({ initialPage?, initialCategories?, initialTags?, pageSize? }) →
+// { 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 }
+
+// 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".
+```
+
+### 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 components under `src/components/blog/` (new names — 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 — 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` (the `PostView` reference shows the shape).
+
+## Hard rules
+
+- **The body renders only through `RichContent`** — 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. `paragraphs` is the honest fallback it already handles.
+- **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.
+- **Never hand-build a wixstatic image URL** — `coverUrl` is already resolved; anything else
+  goes through `wix/media.ts`.
+- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+- 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; don't fabricate engagement.
+- Keep the post page's SEO pieces and `[...slug]` rest param exactly as shipped.
+
+## Point the user to their dashboard
+
+Give the owner the dashboard link plus the Blog pages — the deploy step's JSON printed
+`dashboardUrl`; append `/blog/posts` for writing/editing posts and `/blog/categories` for
+the category menu. 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).
+
+## Verify (before declaring done)
+
+- [ ] `/blog` renders live posts SSR (view-source shows titles) through YOUR components;
+      empty blog shows your honest empty state.
+- [ ] A post page renders the full body via `RichContent` (headings/quotes/lists show, not
+      raw text), with your header design; a bad slug returns 404/not-found.
+- [ ] Category filter narrows the feed (server-side — check the network tab, not a hidden
+      client filter); load-more appends the next page.
+- [ ] Post page view-source carries the SEO tags (Astro).
+- [ ] Card/grid/index/post surfaces/home are YOUR designs on the tokens; data-layer/hook
+      files unedited; `RichContent` wired as-is.
+- [ ] Dashboard links handed to the owner.

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

@@ -0,0 +1,137 @@
+// 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 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">
+        {post.dateLabel && <time dateTime={post.dateISO}>{post.dateLabel}</time>}
+        {post.dateLabel && post.minutesToRead > 0 ? " · " : ""}
+        {post.minutesToRead > 0 ? `${post.minutesToRead} min read` : ""}
+      </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

@@ -0,0 +1,113 @@
+// 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 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">
+        {post.dateLabel && <time dateTime={post.dateISO}>{post.dateLabel}</time>}
+        {post.dateLabel && post.minutesToRead > 0 ? " · " : ""}
+        {post.minutesToRead > 0 ? `${post.minutesToRead} min read` : ""}
+      </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

@@ -0,0 +1,42 @@
+// 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

@@ -0,0 +1,123 @@
+// Blog feed + taxonomy filter + cursor paging. 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, useState } from "react";
+import { fetchPosts } from "../../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags } from "../../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostPage, PostSummary } from "../../wix/blog/types";
+
+export interface UseBlogFeedOptions {
+  initialPage?: PostPage;
+  initialCategories?: BlogCategory[];
+  initialTags?: BlogTag[];
+  pageSize?: number;
+}
+
+export interface UseBlogFeed {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  posts: PostSummary[] | null;
+  categories: BlogCategory[];
+  tags: BlogTag[];
+  activeCategoryId: string | null;
+  setActiveCategoryId: (id: string | null) => void;
+  activeTagId: string | null;
+  setActiveTagId: (id: string | null) => void;
+  /** True when another page exists — render a "load more" control on it. */
+  hasMore: boolean;
+  loadMore: () => void;
+  loadingMore: boolean;
+  error: string | null;
+}
+
+export function useBlogFeed({
+  initialPage,
+  initialCategories,
+  initialTags,
+  pageSize = 20,
+}: UseBlogFeedOptions = {}): UseBlogFeed {
+  const [posts, setPosts] = useState<PostSummary[] | null>(initialPage?.posts ?? null);
+  const [nextCursor, setNextCursor] = useState<string | null>(initialPage?.nextCursor ?? null);
+  const [categories, setCategories] = useState<BlogCategory[]>(initialCategories ?? []);
+  const [tags, setTags] = useState<BlogTag[]>(initialTags ?? []);
+  const [activeCategoryId, setCategoryId] = useState<string | null>(null);
+  const [activeTagId, setTagId] = useState<string | null>(null);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    if (!initialCategories) {
+      fetchBlogCategories().then((c) => alive && setCategories(c));
+    }
+    if (!initialTags) {
+      fetchBlogTags().then((t) => alive && setTags(t));
+    }
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    // The unfiltered first page may have come from the server; only fetch when it didn't,
+    // or when a filter is active (filters are server-side).
+    if (activeCategoryId === null && activeTagId === null && initialPage) {
+      setPosts(initialPage.posts);
+      setNextCursor(initialPage.nextCursor);
+      return;
+    }
+    let alive = true;
+    setPosts(null);
+    setError(null);
+    fetchPosts({ limit: pageSize, categoryId: activeCategoryId, tagId: activeTagId })
+      .then((page) => {
+        if (!alive) return;
+        setPosts(page.posts);
+        setNextCursor(page.nextCursor);
+      })
+      .catch((e) => {
+        if (!alive) return;
+        setPosts([]);
+        setNextCursor(null);
+        setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [activeCategoryId, activeTagId, pageSize]);
+
+  function loadMore(): void {
+    if (!nextCursor || loadingMore) return;
+    setLoadingMore(true);
+    setError(null);
+    fetchPosts({ limit: pageSize, cursor: nextCursor })
+      .then((page) => {
+        setPosts((prev) => [...(prev ?? []), ...page.posts]);
+        setNextCursor(page.nextCursor);
+      })
+      .catch((e) => setError(e instanceof Error ? e.message : String(e)))
+      .finally(() => setLoadingMore(false));
+  }
+
+  return {
+    posts,
+    categories,
+    tags,
+    activeCategoryId,
+    setActiveCategoryId: (id) => {
+      setCategoryId(id);
+      setTagId(null);
+    },
+    activeTagId,
+    setActiveTagId: (id) => {
+      setTagId(id);
+      setCategoryId(null);
+    },
+    hasMore: nextCursor !== null,
+    loadMore,
+    loadingMore,
+    error,
+  };
+}

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

@@ -0,0 +1,70 @@
+// One post by slug + its resolved category/tag chips. SSR-friendly: pass the server-fetched
+// post (and taxonomy) as `initial*` and no client fetch happens; a SPA passes only the slug.
+// Chips resolve from the FULL taxonomy lists (blog taxonomies are small, fetched once) —
+// never per-id lookups in a render loop.
+import { useEffect, useMemo, useState } from "react";
+import { fetchPostBySlug } from "../../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags } from "../../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostDetail } from "../../wix/blog/types";
+
+export interface UsePostOptions {
+  slug: string;
+  initialPost?: PostDetail;
+  initialCategories?: BlogCategory[];
+  initialTags?: BlogTag[];
+}
+
+export interface UsePost {
+  /** null while loading (render a skeleton) AND when not found — disambiguate via notFound. */
+  post: PostDetail | null;
+  /** True once the slug definitively resolved to nothing — render a not-found state. */
+  notFound: boolean;
+  /** This post's categories/tags, resolved to full objects (display .label, route by .slug). */
+  categories: BlogCategory[];
+  tags: BlogTag[];
+  error: string | null;
+}
+
+export function usePost({ slug, initialPost, initialCategories, initialTags }: UsePostOptions): UsePost {
+  const [post, setPost] = useState<PostDetail | null>(initialPost ?? null);
+  const [notFound, setNotFound] = useState(false);
+  const [allCategories, setAllCategories] = useState<BlogCategory[]>(initialCategories ?? []);
+  const [allTags, setAllTags] = useState<BlogTag[]>(initialTags ?? []);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    if (!initialPost || initialPost.slug !== slug) {
+      setPost(null);
+      setNotFound(false);
+      fetchPostBySlug(slug)
+        .then((p) => {
+          if (!alive) return;
+          if (p) setPost(p);
+          else setNotFound(true);
+        })
+        .catch((e) => alive && setError(e instanceof Error ? e.message : String(e)));
+    }
+    if (!initialCategories) {
+      fetchBlogCategories().then((c) => alive && setAllCategories(c));
+    }
+    if (!initialTags) {
+      fetchBlogTags().then((t) => alive && setAllTags(t));
+    }
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [slug]);
+
+  const categories = useMemo(
+    () => (post ? allCategories.filter((c) => post.categoryIds.includes(c.id)) : []),
+    [post, allCategories],
+  );
+  const tags = useMemo(
+    () => (post ? allTags.filter((t) => post.tagIds.includes(t.id)) : []),
+    [post, allTags],
+  );
+
+  return { post, notFound, categories, tags, error };
+}