@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-headless-templates/blog/project/src/pages/blog/tag/[slug].astro

@@ -0,0 +1,51 @@
+---
+// Tag page — the feed filtered to one tag, with the tag's label as its header (a tag carries no
+// description or cover). No SEO item type exists for tags (the enum has BLOG_POST and BLOG_CATEGORY
+// only) and Wix's own sitemap lists no tag pages, so this page is a plain page: the layout's
+// title comes from the tag's label. Keep the frontmatter; restyle the template. The first page is
+// fetched SERVER-SIDE with the tag filter and seeded together with the filter id. An unknown slug is
+// a real 404 (Wix's router answers 200 + empty feed; on a headless site that page does not exist).
+import SiteLayout from "../../../layouts/SiteLayout.astro";
+import BlogFeedView from "../../../components/blog/BlogFeedView";
+import { categoryPath, fetchPosts } from "../../../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags, fetchTagBySlug } from "../../../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostPage } from "../../../wix/blog/types";
+
+const slug = Astro.params.slug;
+if (!slug) {
+  return new Response(null, { status: 404 });
+}
+
+let tag: BlogTag | null = null;
+let page: PostPage | undefined;
+let categories: BlogCategory[] = [];
+let tags: BlogTag[] = [];
+try {
+  [tag, categories, tags] = await Promise.all([fetchTagBySlug(slug), fetchBlogCategories(), fetchBlogTags()]);
+  if (tag) page = await fetchPosts({ tagId: tag.id });
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream. With no seed the island
+  // fetches the filtered page client-side and shows its own error state.
+}
+
+if (!tag) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={tag.label}>
+  <header class="mb-10">
+    <p class="eyebrow">Tag</p>
+    <h1 class="mt-2 text-2xl font-semibold tracking-tight">{tag.label}</h1>
+  </header>
+
+  <BlogFeedView
+    client:load
+    initialPage={page}
+    initialTagId={tag.id}
+    initialCategories={categories}
+    initialTags={tags}
+    categoryHref={categoryPath}
+    emptyMessage="No posts with this tag yet."
+  />
+</SiteLayout>

package/skills/wix-headless-templates/blog/project/src/pages/blog.astro

@@ -0,0 +1,34 @@
+---
+// Blog index — data fetched SERVER-SIDE (SEO) and handed to the island as DTO props.
+// Keep this frontmatter; swap the island import to YOUR feed component. The category pills link
+// to the category pages (/blog/category/<slug>) so every filter has a URL; pass no `categoryHref`
+// for client-side filtering instead.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import BlogFeedView from "../components/blog/BlogFeedView";
+import { categoryPath, fetchPosts } from "../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags } from "../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostPage } from "../wix/blog/types";
+
+let page: PostPage | undefined;
+let categories: BlogCategory[] = [];
+let tags: BlogTag[] = [];
+let failed = false;
+try {
+  [page, categories, tags] = await Promise.all([fetchPosts(), fetchBlogCategories(), fetchBlogTags()]);
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream. With no seed the island fetches
+  // client-side and shows its own error state — never "No posts yet" for a failed read.
+  failed = true;
+}
+---
+
+<SiteLayout title="Blog">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Blog</h1>
+  <BlogFeedView
+    client:load
+    initialPage={failed ? undefined : page}
+    initialCategories={categories}
+    initialTags={tags}
+    categoryHref={categoryPath}
+  />
+</SiteLayout>

package/skills/wix-headless-templates/blog/project/src/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import Hero from '../components/Hero.astro';
+import Layout from '../layouts/Layout.astro';
+---
+
+<Layout>
+	<Hero />
+</Layout>

package/skills/wix-headless-templates/blog/project/src/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

package/skills/wix-headless-templates/blog/project/src/wix/blog/authors-core.ts

@@ -0,0 +1,51 @@
+// Author rules and DTO mapping — transport-agnostic, imported by both ./authors.ts and the REST
+// twin in templates/blog/rest/authors.ts. A post's author is a site member: `post.memberId` →
+// the Members API's PUBLIC fieldset (nickname + photo), looked up in ONE batched query per page.
+// Authors are decoration on a card: every failure degrades to "no byline", never to a placeholder
+// name. Imports are type-only so a strip to JS emits no imports.
+import type { BlogAuthor } from "./types";
+import type { ImgSrc, Raw } from "./posts-core";
+
+/** The PUBLIC fieldset covers everything a byline needs: `profile.nickname` and `profile.photo`. */
+export const AUTHOR_FIELDSETS = ["PUBLIC"] as const;
+
+/** Avatar size every byline gets — one scaled square URL per author. */
+export const AVATAR_SIZE = 96;
+
+/** Distinct, non-empty ids in first-seen order — one query per page, never one per card. */
+export function uniqueIds(ids: readonly (string | null | undefined)[]): string[] {
+  return [...new Set(ids.filter((id): id is string => Boolean(id)))];
+}
+
+/**
+ * The members query as the REST body — the SDK spells it queryMembers({ fieldsets }).in("_id", ids)
+ * .limit(n). Members page by OFFSET (`paging`), unlike posts.
+ */
+export function authorsQuery(ids: string[]): Raw {
+  return { fieldsets: AUTHOR_FIELDSETS, query: { filter: { id: { $in: ids } }, paging: { limit: ids.length } } };
+}
+
+/**
+ * A member photo in the form imgSrc scales. A Wix-hosted photo carries a media id (`_id` on the
+ * SDK, `id` on REST) → the wix:image form; an avatar imported from a social login is an external
+ * URL with an EMPTY id → passed through as-is (imgSrc leaves non-Wix URLs alone).
+ */
+export function photoValue(photo: Raw | undefined | null): string {
+  if (!photo) return "";
+  const id = photo._id ?? photo.id;
+  if (id) return `wix:image://v1/${id}/${id}${photo.width && photo.height ? `#originWidth=${photo.width}&originHeight=${photo.height}` : ""}`;
+  return photo.url ?? "";
+}
+
+export function toAuthor(raw: Raw, imgSrc: ImgSrc): BlogAuthor {
+  return {
+    id: raw._id ?? raw.id ?? "",
+    name: raw.profile?.nickname ?? "",
+    avatarUrl: imgSrc(photoValue(raw.profile?.photo), AVATAR_SIZE, AVATAR_SIZE),
+  };
+}
+
+/** Authors keyed by id — a plain object, not a Map, so it survives serialization into island props. */
+export function indexAuthors(authors: BlogAuthor[]): Record<string, BlogAuthor> {
+  return Object.fromEntries(authors.filter((a) => a.id).map((a) => [a.id, a]));
+}

package/skills/wix-headless-templates/blog/project/src/wix/blog/authors.ts

@@ -0,0 +1,50 @@
+// Author reads (Wix Members) — the only file that touches raw member entities on this transport.
+// Goes over `wixFetch` (the SDK's own authenticated fetch, same identity as every module call)
+// rather than the `@wix/members` module: the blog template does not depend on that package, and
+// two small reads don't warrant it. The mappers live in ./authors-core (shared with the REST twin
+// in templates/blog/rest/authors.ts). Both reads are non-fatal: authors are decoration.
+// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/query-members.md
+// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/get-my-member.md
+import { wixFetch } from "../sdk";
+import { imgSrc } from "../media";
+import { authorsQuery, indexAuthors, toAuthor, uniqueIds } from "./authors-core";
+import type { Raw } from "./posts-core";
+import type { BlogAuthor } from "./types";
+
+/**
+ * Every distinct author of one page in ONE request, keyed by member id. {} on failure or when the
+ * visitor may not read members — the cards render without a byline then.
+ * POST /members/v1/members/query  { fieldsets: ["PUBLIC"], query: { filter: { id: { $in } }, paging: { limit } } }
+ */
+export async function fetchAuthorsByIds(ids: readonly (string | null | undefined)[]): Promise<Record<string, BlogAuthor>> {
+  const unique = uniqueIds(ids);
+  if (!unique.length) return {};
+  try {
+    const res = await wixFetch("/members/v1/members/query", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(authorsQuery(unique)),
+    });
+    if (!res.ok) return {};
+    const json = (await res.json()) as Raw;
+    return indexAuthors(((json?.members ?? []) as Raw[]).map((m) => toAuthor(m, imgSrc)));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The current member's id, or null for an anonymous visitor (the read answers 401/403 then). Used
+ * to mark a member's own comments; never a login gate — the server decides who may comment.
+ * GET /members/v1/members/my
+ */
+export async function fetchCurrentMemberId(): Promise<string | null> {
+  try {
+    const res = await wixFetch("/members/v1/members/my", { method: "GET" });
+    if (!res.ok) return null;
+    const json = (await res.json()) as Raw;
+    return json?.member?.id ?? json?.member?._id ?? null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-templates/blog/project/src/wix/blog/blog-feed-store.ts

@@ -0,0 +1,156 @@
+// The blog feed as a framework-free store — the logic behind useBlogFeed, usable from React
+// (useBlogFeed wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. State, actions, subscribe/getState, emit after every
+// change — the same shape as storefront's shop-store.
+//
+// Category and tag filters are applied by Wix (fetchPosts), never to a page already in hand; the
+// two are mutually exclusive — setting one clears the other. A changed filter starts a fresh cursor
+// chain; a late response from a superseded query is dropped. Paging appends by cursor. Author
+// bylines and counters ride on the posts themselves (fetchPosts joins them per page).
+//
+// SSR-friendly: seed with `initialPage` (and `initialCategories`/`initialTags`) and the first page
+// renders at once with no client fetch. A category or tag page seeds a FILTERED first page: pass the
+// filter it was fetched with as `initialCategoryId`/`initialTagId`, and the seed is trusted for
+// exactly that filter. A SPA passes nothing and `start()` fetches. One store per mounted feed (a
+// page can hold a feed and a "latest posts" rail): createBlogFeedStore().
+//
+// Error vs empty: a failed read leaves `posts: []` AND sets `error`. Render the empty state only
+// when `error` is null — "No posts yet" over a network failure is a lie.
+import { fetchPosts } from "./posts";
+import { fetchBlogCategories, fetchBlogTags } from "./taxonomy";
+import type { BlogCategory, BlogTag, PostPage, PostSummary } from "./types";
+
+export interface BlogFeedStoreOptions {
+  initialPage?: PostPage;
+  /** The filter `initialPage` was fetched with (a category page); omit for the unfiltered feed. */
+  initialCategoryId?: string | null;
+  initialTagId?: string | null;
+  initialCategories?: BlogCategory[];
+  initialTags?: BlogTag[];
+  pageSize?: number;
+}
+
+/** Everything a feed surface renders from. Read it with getState() or through a subscription. */
+export interface BlogFeedState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  posts: PostSummary[] | null;
+  categories: BlogCategory[];
+  tags: BlogTag[];
+  activeCategoryId: string | null;
+  activeTagId: string | null;
+  /** True when another page exists — render a "load more" control on it. */
+  hasMore: boolean;
+  loadingMore: boolean;
+  /** A failed read. While set, `posts` may be [] — that is not an empty blog. */
+  error: string | null;
+}
+
+export interface BlogFeedStore {
+  getState(): BlogFeedState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the taxonomy (unless seeded) and the first page (unless seeded for the active filter). Call once when mounted. */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  /** Server-side filter; clears the tag filter. */
+  setActiveCategoryId(id: string | null): void;
+  /** Server-side filter; clears the category filter. */
+  setActiveTagId(id: string | null): void;
+  loadMore(): Promise<void>;
+}
+
+export function createBlogFeedStore({
+  initialPage,
+  initialCategoryId = null,
+  initialTagId = null,
+  initialCategories,
+  initialTags,
+  pageSize = 20,
+}: BlogFeedStoreOptions = {}): BlogFeedStore {
+  let posts: PostSummary[] | null = initialPage?.posts ?? null;
+  let cursor: string | null = initialPage?.nextCursor ?? null;
+  let categories: BlogCategory[] = initialCategories ?? [];
+  let tags: BlogTag[] = initialTags ?? [];
+  let activeCategoryId: string | null = initialCategoryId;
+  let activeTagId: string | null = initialTagId;
+  let loadingMore = false;
+  let error: string | null = null;
+  let started = false;
+  let generation = 0; // bumped by every filter change and stop(); a response from an older generation is dropped
+  const listeners = new Set<() => void>();
+  let snapshot: BlogFeedState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function getState(): BlogFeedState {
+    if (snapshot) return snapshot;
+    snapshot = { posts, categories, tags, activeCategoryId, activeTagId, hasMore: cursor !== null, loadingMore, error };
+    return snapshot;
+  }
+
+  // The seeded page answers exactly the filter it was fetched with — nothing else.
+  const seedMatches = () => Boolean(initialPage) && activeCategoryId === initialCategoryId && activeTagId === initialTagId;
+
+  // The first page for the current filter: the seed when it matches, a fetch otherwise.
+  function query(): void {
+    if (!started) return;
+    const id = ++generation;
+    loadingMore = false;
+    if (seedMatches()) {
+      posts = initialPage!.posts; cursor = initialPage!.nextCursor; error = null;
+      emit();
+      return;
+    }
+    posts = null; cursor = null; error = null;
+    emit();
+    fetchPosts({ limit: pageSize, categoryId: activeCategoryId, tagId: activeTagId })
+      .then((page) => {
+        if (generation !== id) return; // superseded — drop it
+        posts = page.posts; cursor = page.nextCursor;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id) return;
+        posts = []; cursor = null;
+        error = e instanceof Error ? e.message : String(e);
+        emit();
+      });
+  }
+
+  return {
+    getState,
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (!initialCategories) fetchBlogCategories().then((c) => { if (started) { categories = c; emit(); } });
+      if (!initialTags) fetchBlogTags().then((t) => { if (started) { tags = t; emit(); } });
+      query();
+    },
+    stop() { started = false; generation++; },
+    setActiveCategoryId(id) {
+      if (id === activeCategoryId && activeTagId === null) return;
+      activeCategoryId = id; activeTagId = null;
+      query();
+    },
+    setActiveTagId(id) {
+      if (id === activeTagId && activeCategoryId === null) return;
+      activeTagId = id; activeCategoryId = null;
+      query();
+    },
+    async loadMore() {
+      if (!cursor || loadingMore) return;
+      const id = generation;
+      loadingMore = true; error = null; emit();
+      try {
+        const page = await fetchPosts({ limit: pageSize, cursor });
+        if (generation !== id) return;
+        posts = [...(posts ?? []), ...page.posts]; cursor = page.nextCursor;
+      } catch (e) {
+        if (generation !== id) return;
+        error = e instanceof Error ? e.message : String(e);
+      } finally {
+        if (generation === id) { loadingMore = false; emit(); }
+      }
+    },
+  };
+}

package/skills/wix-headless-templates/blog/project/src/wix/blog/comments-core.ts

@@ -0,0 +1,189 @@
+// Comment rules and DTO mapping — transport-agnostic, imported by both ./comments.ts and the REST
+// twin in templates/blog/rest/comments.ts. Wix Comments is one service for every app; a blog post's
+// thread is addressed by the Blog app id plus the post's REFERENCE ID as both contextId and
+// resourceId (the public-SDK shape Wix's own headless blog uses; the classic Blog widget uses the
+// post id through an internal client instead — verify on a live site that the dashboard's threads
+// come back). Threads are two levels deep: a reply is stored under its TOP-level comment, and its
+// `parentComment` may itself be a reply ("replying to"). Imports are type-only.
+import type { BlogAuthor, BlogComment, CommentPage, CommentStatus, CommentThread } from "./types";
+import type { Raw } from "./posts-core";
+
+// A copy of posts-core's BLOG_APP_ID and dateParts, so this file stands alone when stripped.
+const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
+function dateParts(value: unknown): { dateLabel: string; dateISO: string } {
+  if (!value) return { dateLabel: "", dateISO: "" };
+  const d = value instanceof Date ? value : new Date(String(value));
+  if (Number.isNaN(d.getTime())) return { dateLabel: "", dateISO: "" };
+  return { dateLabel: d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" }), dateISO: d.toISOString() };
+}
+
+/** Top-level comments per page (Wix's default) and replies per "show more replies". */
+export const COMMENTS_PAGE_SIZE = 10;
+export const REPLIES_PAGE_SIZE = 10;
+
+/** The two orders a blog thread offers; replies are always oldest first. */
+export type CommentSort = "NEWEST_FIRST" | "OLDEST_FIRST";
+export const DEFAULT_COMMENT_SORT: CommentSort = "NEWEST_FIRST";
+
+export interface ListCommentsOptions {
+  /** `PostDetail.referenceId` — the thread. */
+  referenceId: string;
+  cursor?: string | null;
+  limit?: number;
+  sort?: CommentSort;
+}
+
+/**
+ * The list-by-resource request as flat query-string params (the endpoint is a GET; nested fields
+ * travel as dotted keys, the SDK flattens them the same way). `repliesLimit: 0` asks for the reply
+ * SEAMS only — each top-level comment's reply cursor comes back without its replies, which load on
+ * demand with `listRepliesParams`.
+ */
+export function listCommentsParams({ referenceId, cursor, limit = COMMENTS_PAGE_SIZE, sort = DEFAULT_COMMENT_SORT }: ListCommentsOptions): Record<string, string> {
+  return {
+    appId: BLOG_APP_ID,
+    contextId: referenceId,
+    resourceId: referenceId,
+    "commentSort.order": sort,
+    "replySort.order": "OLDEST_FIRST",
+    "cursorPaging.limit": String(limit),
+    "cursorPaging.repliesLimit": "0",
+    ...(cursor ? { "cursorPaging.cursor": cursor } : {}),
+  };
+}
+
+/** The same GET, continuing ONE top-level comment's replies from the cursor the list handed back. */
+export function listRepliesParams({ referenceId, cursor, limit = REPLIES_PAGE_SIZE }: { referenceId: string; cursor: string; limit?: number }): Record<string, string> {
+  return {
+    appId: BLOG_APP_ID,
+    contextId: referenceId,
+    resourceId: referenceId,
+    "replySort.order": "OLDEST_FIRST",
+    "cursorPaging.limit": String(limit),
+    "cursorPaging.cursor": cursor,
+  };
+}
+
+export interface CreateCommentOptions {
+  referenceId: string;
+  /** Plain text — wrapped into a one-paragraph Ricos document. */
+  text?: string;
+  /** Or a ready Ricos document (from a rich editor). */
+  richContent?: Record<string, unknown>;
+  /** Reply to this comment (a top-level comment or a reply). */
+  parentId?: string | null;
+}
+
+/** A one-paragraph Ricos document: TEXT is always a leaf inside a PARAGRAPH; the leaf's id is "". */
+export function textToRichContent(text: string): Record<string, unknown> {
+  return {
+    nodes: [
+      { type: "PARAGRAPH", id: "c1", nodes: [{ type: "TEXT", id: "", nodes: [], textData: { text, decorations: [] } }], paragraphData: {} },
+    ],
+  };
+}
+
+/** The create body: `{ comment }`, the reply's parent as `parentComment.id`. */
+export function createCommentBody({ referenceId, text, richContent, parentId }: CreateCommentOptions): Raw {
+  return {
+    comment: {
+      appId: BLOG_APP_ID,
+      contextId: referenceId,
+      resourceId: referenceId,
+      content: { richContent: richContent ?? textToRichContent(text ?? "") },
+      ...(parentId ? { parentComment: { id: parentId } } : {}),
+    },
+  };
+}
+
+/** The plain text of a Ricos document — every TEXT leaf, paragraphs joined by newlines. */
+export function richContentText(rc: Raw | null | undefined): string {
+  const walk = (node: Raw): string =>
+    node.type === "TEXT" ? (node.textData?.text ?? "") : ((node.nodes ?? []) as Raw[]).map(walk).join("");
+  return ((rc?.nodes ?? []) as Raw[]).map(walk).map((s) => s.trim()).filter(Boolean).join("\n");
+}
+
+const STATUSES: readonly CommentStatus[] = ["PUBLISHED", "PENDING", "DELETED", "HIDDEN"];
+
+export interface CommentContext {
+  authors: Record<string, BlogAuthor>;
+  currentMemberId: string | null;
+  /** The top-level comment a reply hangs under; null for top-level comments. */
+  topLevelId: string | null;
+}
+
+export function toComment(raw: Raw, { authors, currentMemberId, topLevelId }: CommentContext): BlogComment {
+  const status: CommentStatus = STATUSES.includes(raw.status) ? raw.status : "UNKNOWN";
+  // A PENDING comment (awaiting the owner's approval) carries its text as draftContent, not content.
+  const content: Raw | null = raw.content?.richContent ?? (status === "PENDING" ? raw.draftContent?.richContent : null) ?? null;
+  const authorId: string = raw.author?.memberId ?? "";
+  const author = authors[authorId];
+  const parentAuthor = authors[raw.parentComment?.author?.memberId ?? ""];
+  return {
+    id: raw._id ?? raw.id ?? "",
+    topLevelId,
+    parentId: raw.parentComment?._id ?? raw.parentComment?.id ?? null,
+    parentAuthorName: parentAuthor?.name ?? "",
+    authorId,
+    authorName: author?.name ?? "",
+    authorAvatarUrl: author?.avatarUrl ?? "",
+    isOwn: Boolean(currentMemberId) && authorId === currentMemberId,
+    ...dateParts(raw.commentDate ?? raw._createdDate ?? raw.createdDate),
+    status,
+    content,
+    text: richContentText(content),
+    replyCount: typeof raw.replyCount === "number" ? raw.replyCount : 0,
+  };
+}
+
+/** Every member id a raw comment list references (authors and reply-to authors), for one batched lookup. */
+export function commentAuthorIds(raws: readonly Raw[]): string[] {
+  return [...new Set(raws.flatMap((c) => [c.author?.memberId, c.parentComment?.author?.memberId]).filter((id): id is string => Boolean(id)))];
+}
+
+/** All raw comments a list response carries — the top-level ones and every seam's replies. */
+export function rawCommentsOf(res: Raw | null | undefined): Raw[] {
+  const replies = Object.values((res?.commentReplies ?? {}) as Record<string, Raw>).flatMap((r) => (r.replies ?? []) as Raw[]);
+  return [...((res?.comments ?? []) as Raw[]), ...replies];
+}
+
+export function toCommentPage(res: Raw | null | undefined, ctx: Omit<CommentContext, "topLevelId">): CommentPage {
+  const replies: Record<string, CommentThread> = {};
+  for (const [topLevelId, r] of Object.entries((res?.commentReplies ?? {}) as Record<string, Raw>)) {
+    replies[topLevelId] = {
+      comments: ((r.replies ?? []) as Raw[]).map((c) => toComment(c, { ...ctx, topLevelId })),
+      nextCursor: r.pagingMetadata?.cursors?.next ?? null,
+    };
+  }
+  return {
+    comments: ((res?.comments ?? []) as Raw[]).map((c) => toComment(c, { ...ctx, topLevelId: null })),
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+    replies,
+  };
+}
+
+/** A replies page: the same response shape, its `comments` being the replies of one top-level comment. */
+export function toCommentThread(res: Raw | null | undefined, ctx: CommentContext): CommentThread {
+  return {
+    comments: ((res?.comments ?? []) as Raw[]).map((c) => toComment(c, ctx)),
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/** Re-mark ownership once the current member is known (the list and the member read run in parallel). */
+export function markOwn<T extends Pick<BlogComment, "authorId" | "isOwn">>(items: T[], currentMemberId: string | null): T[] {
+  return items.map((c) => ({ ...c, isOwn: Boolean(currentMemberId) && c.authorId === currentMemberId }));
+}
+
+/** A deleted comment that still has replies stays as a placeholder: no author, no body. */
+export function toDeletedPlaceholder(c: BlogComment): BlogComment {
+  return { ...c, status: "DELETED", content: null, text: "", authorId: "", authorName: "", authorAvatarUrl: "", isOwn: false };
+}
+
+/** Merge a page into a list by id, keeping the existing order and appending what is new. */
+export function mergeById<T extends { id: string }>(existing: readonly T[], incoming: readonly T[]): T[] {
+  const byId = new Map(existing.map((c) => [c.id, c]));
+  for (const c of incoming) byId.set(c.id, c);
+  const seen = new Set(existing.map((c) => c.id));
+  return [...existing.map((c) => byId.get(c.id)!), ...incoming.filter((c) => !seen.has(c.id))];
+}