@wix/agent-skills 1.19.2 → 1.20.1

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 } };
+}

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

@@ -1,71 +1,24 @@
-// Post reads (Wix Blog V3) — the only file that touches raw post entities. Everything it
-// returns is a plain DTO from ./types. Copy as-is; extend by adding functions, not by editing
-// these. Blog posts are NOT CMS collections — always @wix/blog, never @wix/data.
+// Post reads (Wix Blog V3) over the SDK — the only file that touches raw post entities on this
+// transport. Everything it returns is a plain DTO from ./types. The rules and mappers live in
+// ./posts-core (shared with the REST twin in references/blog/rest/); this file is the transport
+// only. Copy as-is; extend by adding functions, not by editing these. Blog posts are NOT CMS
+// collections — always @wix/blog, never @wix/data.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/get-post-by-slug.md
 import { posts as postsModule } from "@wix/blog";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
-import type { PostDetail, PostPage, PostSummary } from "./types";
+import { BLOG_APP_ID, DETAIL_FIELDSETS, postMetaLine, toDetail, toSummary, type FetchPostsOptions, type Raw } from "./posts-core";
+import type { PostDetail, PostPage } from "./types";
 
-const posts = wixModule(postsModule);
-
-/** The Wix Blog app id (Astro item-page routing; comments use it as appId). */
-export const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
-
-type Raw = Record<string, any>;
+export { BLOG_APP_ID, postMetaLine, type FetchPostsOptions };
 
-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(),
-  };
-}
-
-function toSummary(raw: Raw): PostSummary {
-  return {
-    id: raw._id ?? "",
-    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 is a media STRING (wix:image:// or https) at media.wixMedia.image.
-    coverUrl: imgSrc(raw.media?.wixMedia?.image, 1200, 675),
-    categoryIds: raw.categoryIds ?? [],
-    tagIds: raw.tagIds ?? [],
-  };
-}
-
-function toDetail(raw: Raw): PostDetail {
-  return {
-    ...toSummary(raw),
-    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;
-}
+const posts = wixModule(postsModule);
 
 /**
  * One page of published posts, newest first (pinned posts lead). Only published posts come
  * back to a visitor token — a "missing" post usually wasn't published, not a query bug.
+ * The builder below spells posts-core's feedQuery: sort + filters on the first page, the cursor alone after.
  */
 export async function fetchPosts({ limit = 20, cursor, categoryId, tagId }: FetchPostsOptions = {}): Promise<PostPage> {
   let q = posts.queryPosts().limit(limit);
@@ -79,7 +32,7 @@ export async function fetchPosts({ limit = 20, cursor, categoryId, tagId }: Fetc
   }
   const res = await q.find();
   return {
-    posts: (res.items ?? []).map((p: Raw) => toSummary(p)),
+    posts: (res.items ?? []).map((p: Raw) => toSummary(p, imgSrc)),
     nextCursor: res.hasNext() ? (res.cursors?.next ?? null) : null,
   };
 }
@@ -90,10 +43,10 @@ export async function fetchPosts({ limit = 20, cursor, categoryId, tagId }: Fetc
  */
 export async function fetchPostBySlug(slug: string): Promise<PostDetail | null> {
   const res = await posts
-    .queryPosts({ fieldsets: ["RICH_CONTENT", "CONTENT_TEXT"] })
+    .queryPosts({ fieldsets: [...DETAIL_FIELDSETS] as any })
     .eq("slug", slug)
     .limit(1)
     .find();
   const raw = res.items?.[0];
-  return raw ? toDetail(raw as Raw) : null;
+  return raw ? toDetail(raw as Raw, imgSrc) : null;
 }

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

@@ -0,0 +1,47 @@
+// Category + tag rules and DTO mapping — transport-agnostic, imported by both ./taxonomy.ts (SDK)
+// and the REST twin in references/blog/rest/taxonomy.ts (fetch). Raw entities may carry `_id`
+// (SDK) or `id` (REST). Has its own rawId/mediaValue (copies of posts-core's) so it stands alone
+// when stripped; imports are type-only.
+import type { BlogCategory, BlogTag } from "./types";
+import type { ImgSrc, Raw } from "./posts-core";
+
+/** Menu order — displayPosition ascending; -1 (unplaced) sorts first, which is also what the SDK path shows. */
+export const CATEGORY_SORT = [{ fieldName: "displayPosition", order: "ASC" }] as const;
+/** Most-published-posts first. */
+export const TAG_SORT = [{ fieldName: "publishedPostCount", order: "DESC" }] as const;
+/** Blog taxonomies are small — one read of up to 100 is the whole list. */
+export const TAXONOMY_LIMIT = 100;
+
+const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+// A copy of posts-core's mediaValue: the REST Image object → the wix:image form imgSrc scales.
+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 ?? "";
+}
+
+export function toCategory(raw: Raw, imgSrc: ImgSrc): BlogCategory {
+  return {
+    id: rawId(raw),
+    slug: raw.slug ?? "",
+    label: raw.label ?? "", // the API's display name is `label`, never `name`
+    description: raw.description ?? "",
+    postCount: raw.postCount ?? 0,
+    coverUrl: imgSrc(mediaValue(raw.coverImage), 1200, 675),
+  };
+}
+
+export function toTag(raw: Raw): BlogTag {
+  return {
+    id: rawId(raw),
+    slug: raw.slug ?? "",
+    label: raw.label ?? "",
+    postCount: raw.publishedPostCount ?? 0, // PUBLISHED posts — postCount also counts drafts
+  };
+}

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

@@ -1,42 +1,24 @@
-// Category + tag reads (Wix Blog V3) — the only file that touches raw taxonomy entities.
-// Everything it returns is a plain DTO from ./types. Copy as-is; extend by adding functions.
+// Category + tag reads (Wix Blog V3) over the SDK — the only file that touches raw taxonomy
+// entities on this transport. Everything it returns is a plain DTO from ./types. The mappers live
+// in ./taxonomy-core (shared with the REST twin in references/blog/rest/); this file is the
+// transport only. Copy as-is; extend by adding functions.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/query-categories.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/query-tags.md
 import { categories as categoriesModule, tags as tagsModule } from "@wix/blog";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
+import { TAXONOMY_LIMIT, toCategory, toTag } from "./taxonomy-core";
+import type { Raw } from "./posts-core";
 import type { BlogCategory, BlogTag } from "./types";
 
 const categories = wixModule(categoriesModule);
 const tags = wixModule(tagsModule);
 
-type Raw = Record<string, any>;
-
-function toCategory(raw: Raw): BlogCategory {
-  return {
-    id: raw._id ?? "",
-    slug: raw.slug ?? "",
-    label: raw.label ?? "",
-    description: raw.description ?? "",
-    postCount: raw.postCount ?? 0,
-    coverUrl: imgSrc(raw.coverImage, 1200, 675),
-  };
-}
-
-function toTag(raw: Raw): BlogTag {
-  return {
-    id: raw._id ?? "",
-    slug: raw.slug ?? "",
-    label: raw.label ?? "",
-    postCount: raw.publishedPostCount ?? 0,
-  };
-}
-
 /** Categories in menu order (displayPosition) — non-fatal (empty array on failure). */
 export async function fetchBlogCategories(): Promise<BlogCategory[]> {
   try {
-    const res = await categories.queryCategories().ascending("displayPosition").limit(100).find();
-    return (res.items ?? []).map((c: Raw) => toCategory(c)).filter((c) => c.id);
+    const res = await categories.queryCategories().ascending("displayPosition").limit(TAXONOMY_LIMIT).find();
+    return (res.items ?? []).map((c: Raw) => toCategory(c, imgSrc)).filter((c) => c.id);
   } catch {
     return [];
   }
@@ -45,7 +27,7 @@ export async function fetchBlogCategories(): Promise<BlogCategory[]> {
 /** Tags, most-published-posts first — non-fatal (empty array on failure). */
 export async function fetchBlogTags(): Promise<BlogTag[]> {
   try {
-    const res = await tags.queryTags().descending("publishedPostCount").limit(100).find();
+    const res = await tags.queryTags().descending("publishedPostCount").limit(TAXONOMY_LIMIT).find();
     return (res.items ?? []).map((t: Raw) => toTag(t)).filter((t) => t.id);
   } catch {
     return [];
@@ -59,7 +41,7 @@ export async function fetchBlogTags(): Promise<BlogTag[]> {
 export async function fetchCategoryBySlug(slug: string): Promise<BlogCategory | null> {
   try {
     const res = await categories.getCategoryBySlug(slug);
-    return res.category ? toCategory(res.category as Raw) : null;
+    return res.category ? toCategory(res.category as Raw, imgSrc) : null;
   } catch {
     return null;
   }

package/skills/wix-headless-fast/references/blog/app-astro/pages/blog/[...slug].astro

@@ -7,7 +7,7 @@
 // template below freely. The body island is client:only — the ricos viewer breaks under SSR.
 import SiteLayout from "../../layouts/SiteLayout.astro";
 import RichContent from "../../components/blog/RichContent";
-import { fetchPostBySlug } from "../../wix/blog/posts";
+import { fetchPostBySlug, postMetaLine } from "../../wix/blog/posts";
 import { fetchBlogCategories, fetchBlogTags } from "../../wix/blog/taxonomy";
 import type { BlogCategory, BlogTag } from "../../wix/blog/types";
 import { WIX_APPS } from "@wix/essentials";
@@ -70,9 +70,7 @@ const postTags = allTags.filter((t) => post!.tagIds.includes(t.id));
     {postCategories.length > 0 && <p class="eyebrow">{postCategories.map((c) => c.label).join(" · ")}</p>}
     <h1 class="mt-2 text-3xl font-semibold tracking-tight">{post.title}</h1>
     <p class="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 && (