@wix/agent-skills 1.26.0 → 1.27.0

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

@@ -0,0 +1,206 @@
+// REFERENCE comments surface: the thread (two levels — replies under their top-level comment), a
+// form, reply forms, delete on the member's own comments, PENDING and DELETED states, load-more for
+// comments and for replies, and the sign-in prompt when the server refuses a guest. Correct and
+// complete; per the skill's model you design and build your own on useComments. Mount it only when
+// `post.commentingEnabled && post.referenceId` — in Astro as a `client:load` island.
+import { useState, type FormEvent } from "react";
+import { useComments } from "../../hooks/blog/useComments";
+import type { BlogComment } from "../../wix/blog/types";
+
+export interface CommentsViewProps {
+  /** `PostDetail.referenceId`. */
+  referenceId: string;
+  /** Where "sign in" points when the server refuses a guest's comment (omit to show text only). */
+  signInHref?: string;
+}
+
+function CommentForm({
+  onSubmit,
+  disabled,
+  placeholder,
+  submitLabel = "Post",
+  onCancel,
+}: {
+  onSubmit: (text: string) => Promise<unknown>;
+  disabled: boolean;
+  placeholder: string;
+  submitLabel?: string;
+  onCancel?: () => void;
+}) {
+  const [text, setText] = useState("");
+  const submit = async (e: FormEvent) => {
+    e.preventDefault();
+    if (!text.trim()) return;
+    const ok = await onSubmit(text);
+    if (ok) setText("");
+  };
+  return (
+    <form onSubmit={submit} className="space-y-2">
+      <textarea
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        placeholder={placeholder}
+        rows={3}
+        disabled={disabled}
+        className="w-full rounded-lg border border-border bg-background p-3 text-sm text-foreground"
+      />
+      <div className="flex justify-end gap-2">
+        {onCancel && (
+          <button type="button" onClick={onCancel} className="rounded-lg px-4 py-2 text-sm text-muted-foreground hover:bg-secondary">
+            Cancel
+          </button>
+        )}
+        <button type="submit" disabled={disabled || !text.trim()} className="rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground disabled:opacity-50">
+          {submitLabel}
+        </button>
+      </div>
+    </form>
+  );
+}
+
+function CommentBody({ comment }: { comment: BlogComment }) {
+  if (comment.status === "DELETED") return <p className="text-sm italic text-muted-foreground">This comment was deleted.</p>;
+  return (
+    <div className="text-sm">
+      {/* Plain text, one <p> per line — never the Ricos viewer here: this island is client:load (SSR'd), and the
+          viewer breaks under SSR and drags 2 MB into the server bundle (the post body renders it client:only). */}
+      {comment.text.split("\n").filter(Boolean).map((line, i) => (
+        <p key={i} className="whitespace-pre-wrap">{line}</p>
+      ))}
+    </div>
+  );
+}
+
+function CommentHeader({ comment }: { comment: BlogComment }) {
+  return (
+    <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+      {comment.authorAvatarUrl && <img src={comment.authorAvatarUrl} alt="" width={24} height={24} className="h-6 w-6 rounded-full object-cover" />}
+      {comment.authorName && <span className="font-medium text-foreground">{comment.authorName}</span>}
+      {comment.parentAuthorName && <span>replying to {comment.parentAuthorName}</span>}
+      {comment.dateLabel && <time dateTime={comment.dateISO}>{comment.dateLabel}</time>}
+      {comment.status === "PENDING" && <span className="rounded bg-secondary px-1.5 py-0.5">Awaiting approval</span>}
+    </div>
+  );
+}
+
+export default function CommentsView({ referenceId, signInHref }: CommentsViewProps) {
+  const { comments, replies, hasMore, loadingMore, saving, needsSignIn, sort, error, loadMore, loadReplies, setSort, create, remove } =
+    useComments({ referenceId });
+  const [replyTo, setReplyTo] = useState<{ parentId: string; topLevelId: string } | null>(null);
+
+  const signIn = needsSignIn && (
+    <p className="rounded-lg border border-border bg-secondary p-3 text-sm" role="status">
+      {signInHref ? (
+        <>
+          <a href={signInHref} className="font-medium underline">Sign in</a> to comment on this post.
+        </>
+      ) : (
+        "Sign in to comment on this post."
+      )}
+    </p>
+  );
+
+  return (
+    <section aria-label="Comments" className="space-y-6">
+      <div className="flex items-center justify-between">
+        <h2 className="text-lg font-semibold">Comments</h2>
+        <label className="text-xs text-muted-foreground">
+          Sort{" "}
+          <select value={sort} onChange={(e) => setSort(e.target.value as typeof sort)} className="rounded border border-border bg-background px-2 py-1 text-xs">
+            <option value="NEWEST_FIRST">Newest first</option>
+            <option value="OLDEST_FIRST">Oldest first</option>
+          </select>
+        </label>
+      </div>
+
+      <CommentForm onSubmit={(t) => create(t)} disabled={saving} placeholder="Write a comment…" />
+      {signIn}
+      {error && <p className="text-sm text-destructive" role="alert">{error}</p>}
+
+      {comments === null ? (
+        <div aria-busy="true" className="space-y-3">
+          <div className="h-4 w-1/3 animate-pulse rounded bg-secondary" />
+          <div className="h-12 animate-pulse rounded bg-secondary" />
+        </div>
+      ) : comments.length === 0 ? (
+        !error && <p className="text-sm text-muted-foreground">Be the first to comment.</p>
+      ) : (
+        <ul className="space-y-6">
+          {comments.map((c) => {
+            const thread = replies[c.id];
+            const loaded = thread?.comments ?? [];
+            const remaining = Math.max(0, c.replyCount - loaded.length);
+            return (
+              <li key={c.id} className="space-y-3">
+                <CommentHeader comment={c} />
+                <CommentBody comment={c} />
+                <div className="flex gap-3 text-xs">
+                  {c.status !== "DELETED" && (
+                    <button type="button" onClick={() => setReplyTo({ parentId: c.id, topLevelId: c.id })} className="text-muted-foreground hover:text-foreground">
+                      Reply
+                    </button>
+                  )}
+                  {c.isOwn && (
+                    <button type="button" onClick={() => remove(c.id)} disabled={saving} className="text-muted-foreground hover:text-destructive disabled:opacity-50">
+                      Delete
+                    </button>
+                  )}
+                </div>
+                {(loaded.length > 0 || replyTo?.topLevelId === c.id) && (
+                  <ul className="ml-6 space-y-4 border-l border-border pl-4">
+                    {loaded.map((r) => (
+                      <li key={r.id} className="space-y-2">
+                        <CommentHeader comment={r} />
+                        <CommentBody comment={r} />
+                        <div className="flex gap-3 text-xs">
+                          {r.status !== "DELETED" && (
+                            <button type="button" onClick={() => setReplyTo({ parentId: r.id, topLevelId: c.id })} className="text-muted-foreground hover:text-foreground">
+                              Reply
+                            </button>
+                          )}
+                          {r.isOwn && (
+                            <button type="button" onClick={() => remove(r.id)} disabled={saving} className="text-muted-foreground hover:text-destructive disabled:opacity-50">
+                              Delete
+                            </button>
+                          )}
+                        </div>
+                      </li>
+                    ))}
+                    {replyTo?.topLevelId === c.id && (
+                      <li>
+                        <CommentForm
+                          onSubmit={async (t) => {
+                            const created = await create(t, { parentId: replyTo.parentId, topLevelId: c.id });
+                            if (created) setReplyTo(null);
+                            return created;
+                          }}
+                          disabled={saving}
+                          placeholder="Write a reply…"
+                          submitLabel="Reply"
+                          onCancel={() => setReplyTo(null)}
+                        />
+                      </li>
+                    )}
+                  </ul>
+                )}
+                {(remaining > 0 || thread?.nextCursor) && (
+                  <button type="button" onClick={() => loadReplies(c.id)} disabled={thread?.loading} className="ml-6 text-xs text-muted-foreground hover:text-foreground disabled:opacity-50">
+                    {thread?.loading ? "Loading…" : remaining > 0 ? `Show ${remaining} ${remaining === 1 ? "reply" : "replies"}` : "Show more replies"}
+                  </button>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+
+      {hasMore && (
+        <div className="text-center">
+          <button type="button" onClick={loadMore} disabled={loadingMore} className="rounded-lg border border-border px-6 py-2.5 text-sm font-medium hover:bg-secondary disabled:opacity-50">
+            {loadingMore ? "Loading…" : "Load more comments"}
+          </button>
+        </div>
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,62 @@
+// REFERENCE like control + counters — the post page's engagement row. On Astro this is the island
+// the statically rendered header mounts (`client:load`): it re-creates the post store from the
+// server-fetched post and reads only the viewer's like state (personal, client-only), so nothing
+// else is fetched twice. In a SPA, PostView renders the same row from its own usePost.
+import { usePost } from "../../hooks/blog/usePost";
+import { formatCount } from "../../wix/blog/posts";
+import type { PostDetail } from "../../wix/blog/types";
+
+export interface PostLikeButtonProps {
+  /** The server-fetched post (SSR) — the store starts from it and skips every read but the like state. */
+  post: PostDetail;
+}
+
+/** The row itself, for a surface that already holds a usePost result. */
+export function EngagementRow({
+  isLiked,
+  likeCount,
+  likeCountLoaded,
+  viewCount,
+  commentCount,
+  liking,
+  toggleLike,
+}: {
+  isLiked: boolean;
+  likeCount: number | undefined;
+  likeCountLoaded: boolean;
+  viewCount: number | undefined;
+  commentCount: number | undefined;
+  liking: boolean;
+  toggleLike: () => void;
+}) {
+  return (
+    <div className="flex flex-wrap items-center gap-4 text-sm text-muted-foreground">
+      {viewCount !== undefined && <span>{formatCount(viewCount)} views</span>}
+      {commentCount !== undefined && <span>{formatCount(commentCount)} comments</span>}
+      <button
+        type="button"
+        onClick={toggleLike}
+        disabled={liking}
+        aria-pressed={isLiked}
+        className={`ml-auto inline-flex items-center gap-1.5 rounded-control border px-3 py-1 transition-colors disabled:opacity-50 ${
+          isLiked ? "border-primary text-primary" : "border-border text-foreground hover:bg-secondary"
+        }`}
+      >
+        <span aria-hidden="true">{isLiked ? "♥" : "♡"}</span>
+        <span>{isLiked ? "Liked" : "Like"}</span>
+        {/* The count waits for the fresh read; a skeleton beats a stale number that jumps. */}
+        {likeCountLoaded || likeCount !== undefined ? (
+          likeCount !== undefined && <span className="tabular-nums">{formatCount(likeCount)}</span>
+        ) : (
+          <span className="inline-block h-3 w-5 animate-pulse rounded bg-secondary" aria-hidden="true" />
+        )}
+      </button>
+    </div>
+  );
+}
+
+export default function PostLikeButton({ post }: PostLikeButtonProps) {
+  // Seeded with everything the page already rendered, so start() reads only the viewer's like state.
+  const state = usePost({ slug: post.slug, initialPost: post, initialCategories: [], initialTags: [], initialRelated: [] });
+  return <EngagementRow {...state} />;
+}

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

@@ -0,0 +1,139 @@
+// REFERENCE post surface (SPA use — Astro renders the header statically and mounts RichContent,
+// PostLikeButton, and CommentsView as islands). Correct and complete; per the skill's model you
+// design and build your own on usePost. Chips display .label in the post's order; the body renders
+// ONLY via RichContent; the byline, counters, related strip, and comments appear only when the
+// DTO carries them.
+import type { ComponentType } from "react";
+import { usePost } from "../../hooks/blog/usePost";
+import { categoryPath, postMetaLine, postPath, tagPath } from "../../wix/blog/posts";
+import type { BlogCategory, BlogTag, PostDetail, PostSummary } from "../../wix/blog/types";
+import RichContent from "./RichContent";
+import CommentsView from "./CommentsView";
+import { EngagementRow } from "./PostLikeButton";
+import { PostCard, type LinkLikeProps } from "./BlogFeedView";
+
+export interface PostViewProps {
+  slug: string;
+  initialPost?: PostDetail;
+  initialCategories?: BlogCategory[];
+  initialTags?: BlogTag[];
+  initialRelated?: PostSummary[];
+  /** Where a chip routes (defaults to the category/tag pages). */
+  categoryHref?: (slug: string) => string;
+  tagHref?: (slug: string) => string;
+  postHref?: (slug: string) => string;
+  /** Where "sign in" points when a guest's comment is refused. */
+  signInHref?: string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+const chipClass = "rounded-control border border-border px-3 py-1 text-xs font-medium text-muted-foreground no-underline";
+
+export default function PostView({
+  slug,
+  initialPost,
+  initialCategories,
+  initialTags,
+  initialRelated,
+  categoryHref = categoryPath,
+  tagHref = tagPath,
+  postHref = postPath,
+  signInHref,
+  LinkComponent = PlainLink,
+}: PostViewProps) {
+  const { post, notFound, categories, tags, related, error, ...engagement } = usePost({
+    slug,
+    initialPost,
+    initialCategories,
+    initialTags,
+    initialRelated,
+  });
+
+  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-destructive">{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 && " · "}
+              <LinkComponent href={categoryHref(c.slug)} className="no-underline">
+                {c.label}
+              </LinkComponent>
+            </span>
+          ))}
+        </p>
+      )}
+      <h1 className="mt-2 text-3xl font-semibold tracking-tight">{post.title}</h1>
+      <p className="mt-3 flex flex-wrap items-center gap-2 text-sm text-muted-foreground">
+        {post.authorAvatarUrl && <img src={post.authorAvatarUrl} alt="" width={24} height={24} className="h-6 w-6 rounded-full object-cover" />}
+        {post.authorName && <span>{post.authorName}</span>}
+        {post.authorName && postMetaLine(post) && <span aria-hidden="true">·</span>}
+        <time dateTime={post.dateISO}>{postMetaLine(post)}</time>
+        {post.updatedLabel && post.updatedISO !== post.dateISO && (
+          <span>
+            · Updated <time dateTime={post.updatedISO}>{post.updatedLabel}</time>
+          </span>
+        )}
+      </p>
+      {post.coverUrl && (
+        <div className="mt-6 aspect-[16/9] overflow-hidden rounded-xl bg-secondary">
+          <img src={post.coverUrl} alt={post.coverAlt} className="h-full w-full object-cover" />
+        </div>
+      )}
+      <div className="mt-8">
+        <RichContent content={post.richContent} fallbackParagraphs={post.paragraphs} />
+      </div>
+      <div className="mt-8 border-t border-border pt-4">
+        <EngagementRow {...engagement} />
+      </div>
+      {tags.length > 0 && (
+        <div className="mt-6 flex flex-wrap gap-2">
+          {tags.map((t) => (
+            <LinkComponent key={t.id} href={tagHref(t.slug)} className={chipClass}>
+              {t.label}
+            </LinkComponent>
+          ))}
+        </div>
+      )}
+      {related && related.length > 0 && (
+        <aside className="mt-14">
+          <h2 className="mb-6 text-lg font-semibold">Related posts</h2>
+          <div className="grid grid-cols-1 gap-8 sm:grid-cols-3">
+            {related.map((p) => (
+              <PostCard key={p.id} post={p} postHref={postHref} LinkComponent={LinkComponent} />
+            ))}
+          </div>
+        </aside>
+      )}
+      {post.commentingEnabled && post.referenceId && (
+        <div className="mt-14">
+          <CommentsView referenceId={post.referenceId} signInHref={signInHref} />
+        </div>
+      )}
+    </article>
+  );
+}

package/skills/wix-headless-templates/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-templates/blog/app/hooks/blog/useBlogFeed.ts

@@ -0,0 +1,31 @@
+// 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-templates/blog/app/hooks/blog/useComments.ts

@@ -0,0 +1,26 @@
+// React binding of the comments store (wix/blog/comments-store.ts) — the thread state machine
+// (cursor paging, replies on demand, create/delete as the current identity) lives there,
+// framework-free; this hook subscribes to one instance per thread and exposes its state and actions.
+//
+// Mount the surface only when `post.commentingEnabled && post.referenceId`; pass the referenceId.
+// Client-side by nature (the thread is read as the viewer) — in Astro, a `client:load` island.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createCommentsStore, type CommentsState, type CommentsStore, type CommentsStoreOptions } from "../../wix/blog/comments-store";
+
+export type UseCommentsOptions = CommentsStoreOptions;
+
+export type UseComments = CommentsState & Pick<CommentsStore, "loadMore" | "loadReplies" | "setSort" | "create" | "remove">;
+
+export function useComments(options: UseCommentsOptions): UseComments {
+  const ref = useRef<{ referenceId: string; store: CommentsStore } | null>(null);
+  if (!ref.current || ref.current.referenceId !== options.referenceId) {
+    ref.current = { referenceId: options.referenceId, store: createCommentsStore(options) };
+  }
+  const store = ref.current.store;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { ...state, loadMore: store.loadMore, loadReplies: store.loadReplies, setSort: store.setSort, create: store.create, remove: store.remove };
+}

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

@@ -0,0 +1,25 @@
+// React binding of the post store (wix/blog/post-store.ts) — post-by-slug loading, the resolved
+// category/tag chips, the related strip, and the viewer's like state live there, framework-free;
+// this hook subscribes to one instance per slug and exposes its state and the like action.
+//
+// SSR-friendly: pass the server-fetched post (and taxonomy, related) as `initial*` and no client
+// read happens except the personal like state; 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 & Pick<PostStore, "toggleLike">;
+
+export function usePost(options: UsePostOptions): UsePost {
+  const ref = useRef<{ slug: string; store: PostStore } | null>(null);
+  if (!ref.current || ref.current.slug !== options.slug) ref.current = { slug: options.slug, store: createPostStore(options) };
+  const store = ref.current.store;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { ...state, toggleLike: store.toggleLike };
+}

package/skills/wix-headless-templates/blog/app/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/app/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;
+  }
+}