@wix/agent-skills 1.20.0 → 1.21.0

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

@@ -3,6 +3,7 @@
 // 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";
@@ -81,9 +82,7 @@ export default function PostView({
       )}
       <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` : ""}
+        <time dateTime={post.dateISO}>{postMetaLine(post)}</time>
       </p>
       {post.coverUrl && (
         <div className="mt-6 aspect-[16/9] overflow-hidden rounded-xl bg-secondary">

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

@@ -1,123 +1,31 @@
-// 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";
+// 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 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 type UseBlogFeedOptions = BlogFeedStoreOptions;
 
-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);
+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(() => {
-    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));
-  }
-
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
   return {
-    posts,
-    categories,
-    tags,
-    activeCategoryId,
-    setActiveCategoryId: (id) => {
-      setCategoryId(id);
-      setTagId(null);
-    },
-    activeTagId,
-    setActiveTagId: (id) => {
-      setTagId(id);
-      setCategoryId(null);
-    },
-    hasMore: nextCursor !== null,
-    loadMore,
-    loadingMore,
-    error,
+    ...state,
+    setActiveCategoryId: store.setActiveCategoryId,
+    setActiveTagId: store.setActiveTagId,
+    loadMore: store.loadMore,
   };
 }

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

@@ -1,70 +1,22 @@
-// 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";
+// 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 interface UsePostOptions {
-  slug: string;
-  initialPost?: PostDetail;
-  initialCategories?: BlogCategory[];
-  initialTags?: BlogTag[];
-}
+export type UsePostOptions = PostStoreOptions;
 
-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 type UsePost = PostState;
 
 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);
-
+  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(() => {
-    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 };
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
 }

package/skills/wix-headless-fast/references/blog/app/wix/blog/blog-feed-store.ts

@@ -0,0 +1,137 @@
+// 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.
+//
+// SSR-friendly: seed with `initialPage` (and `initialCategories`/`initialTags`) and the first,
+// unfiltered page renders at once with no client fetch; a SPA passes nothing and `start()` fetches.
+// One store per mounted feed (a page can hold a feed and a "latest posts" rail): createBlogFeedStore().
+import { fetchPosts } from "./posts";
+import { fetchBlogCategories, fetchBlogTags } from "./taxonomy";
+import type { BlogCategory, BlogTag, PostPage, PostSummary } from "./types";
+
+export interface BlogFeedStoreOptions {
+  initialPage?: PostPage;
+  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;
+  error: string | null;
+}
+
+export interface BlogFeedStore {
+  getState(): BlogFeedState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the taxonomy (unless seeded) and the first page (unless seeded and unfiltered). 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, 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 = null;
+  let activeTagId: string | null = null;
+  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 first page for the current filter. The unfiltered page may have come from the server —
+  // fetch only when it didn't, or when a filter is active (filters are server-side).
+  function query(): void {
+    if (!started) return;
+    const id = ++generation;
+    loadingMore = false;
+    if (activeCategoryId === null && activeTagId === null && initialPage) {
+      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-fast/references/blog/app/wix/blog/post-store.ts

@@ -0,0 +1,78 @@
+// One post as a framework-free store — the logic behind usePost, usable from React (usePost wraps
+// it), from a static page's post view, from Vue/Svelte, or as the specification for a port. Loads
+// the post by slug (unless seeded) and the FULL taxonomy lists (blog taxonomies are small, fetched
+// once), and resolves the post's category/tag chips from them — never per-id lookups in a render.
+//
+// SSR-friendly: pass the server-fetched PostDetail as `initialPost` (and the taxonomy) and no client
+// fetch happens; a SPA passes only the slug. One store per post surface: createPostStore().
+import { fetchPostBySlug } from "./posts";
+import { fetchBlogCategories, fetchBlogTags } from "./taxonomy";
+import type { BlogCategory, BlogTag, PostDetail } from "./types";
+
+export interface PostStoreOptions {
+  slug: string;
+  initialPost?: PostDetail;
+  initialCategories?: BlogCategory[];
+  initialTags?: BlogTag[];
+}
+
+export interface PostState {
+  /** 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 interface PostStore {
+  getState(): PostState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the post (unless `initialPost` matches the slug) and the taxonomy (unless seeded). Call once when mounted. */
+  start(): void;
+  stop(): void;
+}
+
+export function createPostStore({ slug, initialPost, initialCategories, initialTags }: PostStoreOptions): PostStore {
+  let post: PostDetail | null = initialPost ?? null;
+  let notFound = false;
+  let allCategories: BlogCategory[] = initialCategories ?? [];
+  let allTags: BlogTag[] = initialTags ?? [];
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: PostState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function getState(): PostState {
+    if (snapshot) return snapshot;
+    snapshot = {
+      post,
+      notFound,
+      categories: post ? allCategories.filter((c) => post!.categoryIds.includes(c.id)) : [],
+      tags: post ? allTags.filter((t) => post!.tagIds.includes(t.id)) : [],
+      error,
+    };
+    return snapshot;
+  }
+
+  return {
+    getState,
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (!initialPost || initialPost.slug !== slug) {
+        post = null; notFound = false; emit();
+        fetchPostBySlug(slug)
+          .then((p) => { if (!started) return; if (p) post = p; else notFound = true; emit(); })
+          .catch((e) => { if (started) { error = e instanceof Error ? e.message : String(e); emit(); } });
+      }
+      if (!initialCategories) fetchBlogCategories().then((c) => { if (started) { allCategories = c; emit(); } });
+      if (!initialTags) fetchBlogTags().then((t) => { if (started) { allTags = t; emit(); } });
+    },
+    stop() { started = false; },
+  };
+}

package/skills/wix-headless-fast/references/blog/app/wix/blog/posts-core.ts

@@ -0,0 +1,117 @@
+// Post rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./posts.ts (the
+// SDK, managed Astro and React) and the REST twin in references/blog/rest/posts.ts (fetch, a static
+// site or a port to another language). Every rule about dates, covers, the feed's sort and filters,
+// and the body fieldsets lives HERE, once. A raw post may come from the SDK (`_id`, media as a
+// `wix:image://` string, dates as Date) or from REST (`id`, media as an { id, url } object, dates
+// as ISO strings); the mappers accept both and produce the same DTO. Imports are type-only so a
+// strip to JS emits no imports.
+import type { PostDetail, PostSummary } from "./types";
+
+/** A raw Blog V3 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** The Wix Blog app id (Astro item-page routing; comments use it as appId). */
+export const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
+
+/** The body fieldsets — without them richContent and contentText come back undefined. */
+export const DETAIL_FIELDSETS = ["RICH_CONTENT", "CONTENT_TEXT"] as const;
+
+/** The feed's order: newest first; Wix places pinned posts first on its own. */
+export const FEED_SORT = [{ fieldName: "firstPublishedDate", order: "DESC" }] as const;
+
+/** Cover size every card and post header gets — 16:9, one scaled URL per post. */
+export const COVER_WIDTH = 1200;
+export const COVER_HEIGHT = 675;
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+/**
+ * A media value in the form imgSrc scales. The SDK hands over the `wix:image://v1/<file>/<name>#…`
+ * string; REST hands over the Image object { id, url, width, height, filename }. Rebuilding the
+ * wix:image form from the object makes both transports scale to the SAME URL — passing the object's
+ * `url` through would skip scaling and the two paths would disagree on coverUrl.
+ */
+export function mediaValue(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  const o = value as Raw;
+  if (o.id && !String(o.id).startsWith("http")) {
+    const size = o.width && o.height ? `#originWidth=${o.width}&originHeight=${o.height}` : "";
+    return `wix:image://v1/${o.id}/${o.filename ?? ""}${size}`;
+  }
+  return o.url ?? o.image ?? "";
+}
+
+/** Display date + ISO date from either a Date (SDK) or an ISO string (REST); both "" when missing or invalid. */
+export 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(),
+  };
+}
+
+/** "Aug 27, 2026 · 4 min read" — the card's and header's meta line; either half alone, "" when neither is known. */
+export function postMetaLine(post: Pick<PostSummary, "dateLabel" | "minutesToRead">): string {
+  return [post.dateLabel, post.minutesToRead > 0 ? `${post.minutesToRead} min read` : ""].filter(Boolean).join(" · ");
+}
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc): PostSummary {
+  return {
+    id: rawId(raw),
+    slug: raw.slug ?? "",
+    title: raw.title ?? "",
+    excerpt: raw.excerpt ?? "",
+    ...dateParts(raw.firstPublishedDate),
+    minutesToRead: raw.minutesToRead ?? 0,
+    featured: raw.featured === true,
+    pinned: raw.pinned === true,
+    // The cover lives at media.wixMedia.image — a media string (SDK) or an Image object (REST).
+    coverUrl: imgSrc(mediaValue(raw.media?.wixMedia?.image), COVER_WIDTH, COVER_HEIGHT),
+    categoryIds: raw.categoryIds ?? [],
+    tagIds: raw.tagIds ?? [],
+  };
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): PostDetail {
+  return {
+    ...toSummary(raw, imgSrc),
+    richContent: raw.richContent ?? null,
+    // contentText is plain text — split on newlines for the fallback body.
+    paragraphs: String(raw.contentText ?? "")
+      .split("\n")
+      .map((s: string) => s.trim())
+      .filter(Boolean),
+  };
+}
+
+export interface FetchPostsOptions {
+  limit?: number;
+  /** `nextCursor` from a previous page. */
+  cursor?: string | null;
+  /** Server-side filters (first page only — the cursor carries them on later pages). */
+  categoryId?: string | null;
+  tagId?: string | null;
+}
+
+/**
+ * The feed query as one object — the REST body's `query`, and the rule the SDK builder in ./posts.ts
+ * spells with .descending()/.hasSome()/.skipTo(). A cursor encodes the original filter+sort, so a
+ * cursor request carries ONLY cursorPaging; the first page carries the sort and the filters.
+ */
+export function feedQuery({ limit = 20, cursor, categoryId, tagId }: FetchPostsOptions = {}): Raw {
+  if (cursor) return { cursorPaging: { limit, cursor } };
+  const filter: Raw = {};
+  if (categoryId) filter.categoryIds = { $hasSome: [categoryId] };
+  if (tagId) filter.tagIds = { $hasSome: [tagId] };
+  return { ...(Object.keys(filter).length ? { filter } : {}), sort: FEED_SORT, cursorPaging: { limit } };
+}
+
+/** The by-slug query (REST body's `query`): exact slug, one row. */
+export function slugQuery(slug: string): Raw {
+  return { filter: { slug: { $eq: slug } }, cursorPaging: { limit: 1 } };
+}