@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/blog/app/wix/blog/posts.ts

@@ -0,0 +1,132 @@
+// 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 templates/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
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/get-post-metrics.md
+import { posts as postsModule } from "@wix/blog";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import { fetchAuthorsByIds } from "./authors";
+import {
+  BLOG_APP_ID,
+  CARD_FIELDSETS,
+  DETAIL_FIELDSETS,
+  RELATED_LIMIT,
+  categoryPath,
+  formatCount,
+  isNotFound,
+  pickCurated,
+  postMetaLine,
+  postPath,
+  relativeDateLabel,
+  tagPath,
+  toDetail,
+  toMetrics,
+  toSummary,
+  withAuthors,
+  type FetchPostsOptions,
+  type Raw,
+} from "./posts-core";
+import type { PostDetail, PostMetrics, PostPage, PostSummary } from "./types";
+
+export { BLOG_APP_ID, categoryPath, formatCount, postMetaLine, postPath, relativeDateLabel, tagPath, type FetchPostsOptions };
+
+const posts = wixModule(postsModule);
+
+// Cards carry METRICS (view/like/comment counts); the fieldsets option rides outside the query.
+const cardQuery = () => posts.queryPosts({ fieldsets: [...CARD_FIELDSETS] as any });
+
+// The authors of one page in one batched read, joined onto the DTOs; a failed read leaves "" (no byline).
+async function withPageAuthors<T extends PostSummary>(items: T[]): Promise<T[]> {
+  return withAuthors(items, await fetchAuthorsByIds(items.map((p) => p.authorId)));
+}
+
+/**
+ * One page of published posts: pinned first, then newest first. 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 = cardQuery().limit(limit);
+  if (cursor) {
+    // A cursor encodes the original filter+sort — re-sending them alongside it is rejected.
+    q = q.skipTo(cursor);
+  } else {
+    // queryPosts with an explicit sort does not pin on its own — the pinned key comes first.
+    q = q.descending("pinned").descending("firstPublishedDate");
+    if (categoryId) q = q.hasSome("categoryIds", [categoryId]);
+    if (tagId) q = q.hasSome("tagIds", [tagId]);
+  }
+  const res = await q.find();
+  return {
+    posts: await withPageAuthors((res.items ?? []).map((p: Raw) => toSummary(p, imgSrc))),
+    nextCursor: res.hasNext() ? (res.cursors?.next ?? null) : null,
+  };
+}
+
+/**
+ * One post by its URL slug with the full body and SEO/comments fields (RICH_CONTENT, CONTENT_TEXT,
+ * SEO, REFERENCE_ID, INTERNAL_ID — without them those fields come back undefined; INTERNAL_ID is the
+ * one that actually carries referenceId). Null when the slug resolves
+ * to nothing (404 / NOT_FOUND is an expected miss); any other failure throws. The dedicated
+ * by-slug read, not a slug query: slugs are per translation, so a slug-only query is ambiguous on
+ * a multilingual site.
+ */
+export async function fetchPostBySlug(slug: string): Promise<PostDetail | null> {
+  let raw: Raw | undefined;
+  try {
+    raw = (await posts.getPostBySlug(slug, { fieldsets: [...DETAIL_FIELDSETS] as any })).post as Raw | undefined;
+  } catch (e) {
+    if (isNotFound(e)) return null;
+    throw e;
+  }
+  if (!raw) return null;
+  const [detail] = await withPageAuthors([toDetail(raw, imgSrc)]);
+  return detail;
+}
+
+/** Posts by id, as cards (order is the API's — callers restore their own). Non-fatal: [] on failure. */
+export async function fetchPostsByIds(ids: string[]): Promise<PostSummary[]> {
+  if (!ids.length) return [];
+  try {
+    const res = await cardQuery().in("_id", ids).limit(ids.length).find();
+    return withPageAuthors((res.items ?? []).map((p: Raw) => toSummary(p, imgSrc)));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The post page's related strip: the writer's curated `relatedPostIds` (their order, the current
+ * post dropped) when at least one still resolves; else the newest posts sharing a category with this
+ * one (site-wide recents when it has none). Strictly either/or — never topped up. Non-fatal: [].
+ */
+export async function fetchRelatedPosts(post: Pick<PostDetail, "id" | "categoryIds" | "relatedPostIds">, limit = RELATED_LIMIT): Promise<PostSummary[]> {
+  try {
+    if (post.relatedPostIds.length) {
+      const curated = pickCurated(post.relatedPostIds, await fetchPostsByIds(post.relatedPostIds), post.id, limit);
+      if (curated.length) return curated;
+    }
+    let q = cardQuery().ne("_id", post.id).descending("firstPublishedDate").limit(limit);
+    if (post.categoryIds.length) q = q.hasSome("categoryIds", post.categoryIds);
+    const res = await q.find();
+    return withPageAuthors((res.items ?? []).map((p: Raw) => toSummary(p, imgSrc)));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The post's fresh counters — the API's designated source (the `metrics` field on a post is
+ * deprecated as potentially inconsistent). Null on failure: keep the count you had.
+ */
+export async function fetchPostMetrics(postId: string): Promise<PostMetrics | null> {
+  try {
+    return toMetrics((await posts.getPostMetrics(postId)).metrics as Raw | undefined);
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,80 @@
+// Category + tag rules and DTO mapping — transport-agnostic, imported by both ./taxonomy.ts (SDK)
+// and the REST twin in templates/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;
+/** A post carries at most 30 tag ids (the API's own cap), so one by-id read answers a post in full. */
+export const TAG_BY_IDS_LIMIT = 30;
+/** Server-side "only categories that have posts" — the filter row's rule, applied at the source. */
+export const WITH_POSTS_FILTER = { postCount: { $gt: 0 } } as const;
+
+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 interface FetchCategoriesOptions {
+  /** Only categories with at least one post (the filter row's rule) — applied by Wix. */
+  withPosts?: boolean;
+}
+
+/** The categories query (REST body's `query`); the SDK spells it .ascending("displayPosition").gt("postCount", 0).limit(100). */
+export function categoriesQuery({ withPosts = false }: FetchCategoriesOptions = {}): Raw {
+  return { ...(withPosts ? { filter: WITH_POSTS_FILTER } : {}), sort: CATEGORY_SORT, paging: { limit: TAXONOMY_LIMIT } };
+}
+
+/**
+ * Tags BY ID (REST body's `query`; the SDK spells it .in("_id", ids).limit(30)) — a post's chips are
+ * read this way, not joined off a top-100 catalog: a blog's tags run to hundreds, and a tag past the
+ * first page would silently lose its chip. Categories run to tens, so their catalog is joined in memory.
+ */
+export function tagsByIdsQuery(ids: string[]): Raw {
+  return { filter: { id: { $in: ids } }, paging: { limit: TAG_BY_IDS_LIMIT } };
+}
+
+/**
+ * Items in the order the POST lists them (its `categoryIds`/`tagIds`), ids that resolved to nothing
+ * dropped — the catalog's displayPosition and the query's own order are not the post's order.
+ */
+export function inIdOrder<T extends { id: string }>(ids: readonly string[], items: readonly T[]): T[] {
+  const byId = new Map(items.map((x) => [x.id, x]));
+  return ids.map((id) => byId.get(id)).filter((x): x is T => x !== undefined);
+}
+
+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`
+    title: raw.title ?? "", // the category's SEO title (the dashboard's "title tag"); "" until the owner sets one
+    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-templates/blog/app/wix/blog/taxonomy.ts

@@ -0,0 +1,78 @@
+// 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 templates/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/category/get-category-by-slug.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/query-tags.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/get-tag-by-slug.md
+import { categories as categoriesModule, tags as tagsModule } from "@wix/blog";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import { TAG_BY_IDS_LIMIT, TAXONOMY_LIMIT, inIdOrder, toCategory, toTag, type FetchCategoriesOptions } from "./taxonomy-core";
+import type { Raw } from "./posts-core";
+import type { BlogCategory, BlogTag } from "./types";
+
+export { inIdOrder, type FetchCategoriesOptions };
+
+const categories = wixModule(categoriesModule);
+const tags = wixModule(tagsModule);
+
+/** Categories in menu order (displayPosition); `withPosts` drops empty ones at the source — non-fatal (empty array on failure). */
+export async function fetchBlogCategories({ withPosts = false }: FetchCategoriesOptions = {}): Promise<BlogCategory[]> {
+  try {
+    let q = categories.queryCategories().ascending("displayPosition").limit(TAXONOMY_LIMIT);
+    if (withPosts) q = q.gt("postCount", 0);
+    const res = await q.find();
+    return (res.items ?? []).map((c: Raw) => toCategory(c, imgSrc)).filter((c) => c.id);
+  } catch {
+    return [];
+  }
+}
+
+/** Tags, most-published-posts first — a tag cloud; non-fatal (empty array on failure). */
+export async function fetchBlogTags(): Promise<BlogTag[]> {
+  try {
+    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 [];
+  }
+}
+
+/**
+ * A post's tags by id, in the post's own order (a blog's tags run to hundreds — a catalog page would
+ * silently drop chips). Non-fatal: [] on failure.
+ */
+export async function fetchTagsByIds(ids: readonly string[]): Promise<BlogTag[]> {
+  if (!ids.length) return [];
+  try {
+    const res = await tags.queryTags().in("_id", [...ids]).limit(TAG_BY_IDS_LIMIT).find();
+    return inIdOrder(ids, (res.items ?? []).map((t: Raw) => toTag(t)).filter((t) => t.id));
+  } catch {
+    return [];
+  }
+}
+
+// The two by-slug getters return DIFFERENT envelopes upstream ({ category } vs { tag } here;
+// getTag(id) even returns the tag bare) — the mapping below absorbs that asymmetry once.
+
+/** One category by its URL slug. Null when not found. */
+export async function fetchCategoryBySlug(slug: string): Promise<BlogCategory | null> {
+  try {
+    const res = await categories.getCategoryBySlug(slug);
+    return res.category ? toCategory(res.category as Raw, imgSrc) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One tag by its URL slug. Null when not found. */
+export async function fetchTagBySlug(slug: string): Promise<BlogTag | null> {
+  try {
+    const res = await tags.getTagBySlug(slug);
+    return res.tag ? toTag(res.tag as Raw) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-templates/blog/app/wix/blog/types.ts

@@ -0,0 +1,161 @@
+// Blog DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or across server/client boundaries. Cover images are
+// resolved https URLs; dates are pre-formatted display strings plus an ISO value for <time>.
+// A field that is "" or undefined means "not known" — render nothing for it, never a placeholder.
+
+/** A post as a feed/grid tile needs it. */
+export interface PostSummary {
+  id: string;
+  slug: string;
+  title: string;
+  /** Short summary (≤500 chars) — the card body. May be "". */
+  excerpt: string;
+  /** Display-ready publish date, e.g. "Aug 26, 2026" ("" when missing). */
+  dateLabel: string;
+  /** ISO publish date for <time datetime> ("" when missing). */
+  dateISO: string;
+  /** Estimated reading time in minutes (0 when unknown — render nothing, never "0 min read"). */
+  minutesToRead: number;
+  featured: boolean;
+  /** Pinned posts lead the default feed order. */
+  pinned: boolean;
+  /**
+   * Resolved https cover URL, 16:9 ("" when the post has no cover, or its author hid it). A video
+   * cover resolves to its poster, an external embed (YouTube/Vimeo) to its thumbnail.
+   */
+  coverUrl: string;
+  /** Alt text for the cover: the author's alt text, else the title ("" when there is no cover). */
+  coverAlt: string;
+  categoryIds: string[];
+  tagIds: string[];
+  /** The author's member id ("" when none). */
+  authorId: string;
+  /** The author's display name ("" when unresolved — render no byline then). */
+  authorName: string;
+  /** Resolved https avatar URL ("" when none). */
+  authorAvatarUrl: string;
+  /** Counters (the METRICS fieldset). undefined = unknown → render nothing. */
+  viewCount?: number;
+  likeCount?: number;
+  commentCount?: number;
+}
+
+/** A post as the post page needs it. */
+export interface PostDetail extends PostSummary {
+  /**
+   * Ricos rich-content document (plain JSON) — the real post body. Render it ONLY through
+   * the shipped RichContent component (@wix/ricos viewer); it is not HTML and not text.
+   */
+  richContent: Record<string, unknown> | null;
+  /** Plain-text body split into paragraphs — the honest fallback when richContent is null. */
+  paragraphs: string[];
+  /** Display-ready last-published date ("" when the post was never republished). */
+  updatedLabel: string;
+  updatedISO: string;
+  /** The owner's SEO title override, else the title — the <title> on stacks without the SEO service. */
+  seoTitle: string;
+  /** The owner's meta-description override, else the excerpt, else the body text cut to 500 chars. */
+  seoDescription: string;
+  /** Writer-curated related posts, in the writer's order (may be empty). */
+  relatedPostIds: string[];
+  /** Comments are open on this post (the dashboard's per-post switch). */
+  commentingEnabled: boolean;
+  /** The comments thread id (the REFERENCE_ID fieldset); "" when the API answered without it. */
+  referenceId: string;
+}
+
+/** A post author — a site member's public profile. */
+export interface BlogAuthor {
+  id: string;
+  /** Display name ("" when the member set none). */
+  name: string;
+  /** Resolved https avatar URL ("" when none). */
+  avatarUrl: string;
+}
+
+/** The post's counters as the API's dedicated metrics read answers them. */
+export interface PostMetrics {
+  views?: number;
+  likes?: number;
+  comments?: number;
+}
+
+/** The viewer's like state for one post, plus the fresh counters read alongside it. */
+export interface LikeState {
+  /** Whether THIS viewer (member or anonymous visitor) has liked the post. */
+  liked: boolean;
+  /** null when the metrics read failed — keep the count you had. */
+  metrics: PostMetrics | null;
+}
+
+export interface BlogCategory {
+  id: string;
+  slug: string;
+  /** Display name (the API calls it `label`, never `name`). */
+  label: string;
+  /** The category's SEO title ("" when the owner set none) — the <title> of a category page. */
+  title: string;
+  description: string;
+  /** Number of posts in the category (hide empty categories with it). */
+  postCount: number;
+  /** Resolved https cover URL ("" when none). */
+  coverUrl: string;
+}
+
+export interface BlogTag {
+  id: string;
+  slug: string;
+  label: string;
+  /** Number of PUBLISHED posts with this tag. */
+  postCount: number;
+}
+
+/** One feed page; pass `nextCursor` back to fetch the next (null → no more). */
+export interface PostPage {
+  posts: PostSummary[];
+  nextCursor: string | null;
+}
+
+/** PUBLISHED is the normal state; PENDING awaits the owner's approval; DELETED is a placeholder kept for its replies. */
+export type CommentStatus = "PUBLISHED" | "PENDING" | "DELETED" | "HIDDEN" | "UNKNOWN";
+
+/** One comment — a top-level comment or a reply. Threads are two levels deep (Wix's rule). */
+export interface BlogComment {
+  id: string;
+  /** The top-level comment this reply hangs under; null for a top-level comment. */
+  topLevelId: string | null;
+  /** The comment this one replies to (may itself be a reply — show "replying to"); null for a top-level comment. */
+  parentId: string | null;
+  /** The parent's author name ("" when unknown or a top-level comment). */
+  parentAuthorName: string;
+  /** The author's member id ("" for a guest or a deleted comment). */
+  authorId: string;
+  /** The author's display name ("" when unresolved). */
+  authorName: string;
+  authorAvatarUrl: string;
+  /** True when the current member wrote it — show the delete control only then. */
+  isOwn: boolean;
+  dateLabel: string;
+  dateISO: string;
+  status: CommentStatus;
+  /** Ricos document (plain JSON) — render through RichContent where it deploys; a PENDING comment carries its draft. */
+  content: Record<string, unknown> | null;
+  /** The comment's plain text — the body on stacks without the Ricos viewer ("" for a DELETED placeholder). */
+  text: string;
+  /** Number of replies (any depth) under a top-level comment. */
+  replyCount: number;
+}
+
+/** The replies of one top-level comment; `nextCursor` continues them (null → none or all loaded). */
+export interface CommentThread {
+  comments: BlogComment[];
+  nextCursor: string | null;
+}
+
+/** One page of top-level comments plus the reply seams the API answered for them. */
+export interface CommentPage {
+  comments: BlogComment[];
+  nextCursor: string | null;
+  /** Keyed by top-level comment id — its replies (empty until loaded) and their cursor. */
+  replies: Record<string, CommentThread>;
+}

package/skills/wix-headless-templates/blog/app-astro/layouts/SiteLayout.astro

@@ -0,0 +1,44 @@
+---
+// The site chrome for every blog page — THIS file (header/footer/nav) plus the @theme
+// token block in src/styles/global.css are what you brand. Keep the <slot name="seo-tags" />
+// in <head> and the global.css import. (If another vertical is also deployed, its SiteLayout
+// won; merge a Blog nav link there instead.)
+//
+// One source of head tags per page: a page that renders <SEO.Tags> (the post and category item
+// pages, when the SEO service resolved) passes NO title/description here — the service owns them,
+// including the owner's dashboard overrides. Every other page passes its own.
+import "../styles/global.css";
+
+interface Props {
+  title?: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    {title && <title>{title}</title>}
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <a href="/blog" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Blog</a>
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+  </body>
+</html>

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

@@ -0,0 +1,148 @@
+---
+// Post page.
+//
+// This is a Wix ITEM PAGE: the wixMetadata export + <SEO.Tags> below let the site owner edit
+// this page's title/description/OG in the dashboard and register the route in the sitemap.
+// Keep all three SEO pieces, the [...slug] rest param (a slug may contain "/"), and this
+// frontmatter; restyle the template below freely. The body island is client:only — the ricos
+// viewer breaks under SSR. The like row and the comments are client:load islands: both read as
+// the VIEWER (personal like state, the member's own comments), which SSR cannot do.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import RichContent from "../../components/blog/RichContent";
+import PostLikeButton from "../../components/blog/PostLikeButton";
+import CommentsView from "../../components/blog/CommentsView";
+import { PostCard } from "../../components/blog/BlogFeedView";
+import { categoryPath, fetchPostBySlug, fetchRelatedPosts, postMetaLine, tagPath } from "../../wix/blog/posts";
+import { fetchBlogCategories, fetchTagsByIds, inIdOrder } from "../../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostDetail, PostSummary } from "../../wix/blog/types";
+import { WIX_APPS } from "@wix/essentials";
+import { SEO } from "@wix/seo/components";
+import { loadSEOTagsServiceConfig } from "@wix/seo/services";
+import { seoTags } from "@wix/seo";
+
+export const wixMetadata = {
+  appDefId: WIX_APPS.blogs.id,
+  pageIdentifier: WIX_APPS.blogs.postPageMetadata.pageIdentifier,
+  identifiers: {
+    slug: WIX_APPS.blogs.postPageMetadata.identifiers.slug,
+  },
+};
+
+// The rest param arrives decoded and re-joined ("a/b" for /blog/a/b) — exactly the stored slug.
+const slug = Astro.params.slug;
+if (!slug) {
+  return new Response(null, { status: 404 });
+}
+
+// Behind Wix's proxy the request URL is internal — the real public page URL arrives on
+// x-wix-forwarded-url; the SEO service needs the public one.
+const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
+    ? forwardedUrl
+    : Astro.url.href;
+
+let post: PostDetail | null = null;
+let allCategories: BlogCategory[] = [];
+let postTags: BlogTag[] = [];
+let related: PostSummary[] = [];
+let seoTagsServiceConfig = null;
+try {
+  [post, allCategories, seoTagsServiceConfig] = await Promise.all([
+    fetchPostBySlug(slug),
+    fetchBlogCategories(),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.BLOG_POST,
+      itemData: { slug },
+    }).catch(() => null),
+  ]);
+  if (post) {
+    // Tags are read BY ID (a blog's tags run to hundreds); the related strip needs the post's ids.
+    [postTags, related] = await Promise.all([fetchTagsByIds(post.tagIds), fetchRelatedPosts(post)]);
+  }
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!post) {
+  return new Response(null, { status: 404 });
+}
+
+// Chips in the POST's order (its categoryIds), ids that resolved to nothing dropped.
+const postCategories = inIdOrder(post.categoryIds, allCategories);
+// One source of head tags: the SEO service when it resolved (it carries the owner's overrides);
+// otherwise the DTO's own seoTitle/seoDescription (override → title; override → excerpt → body).
+const head = seoTagsServiceConfig ? {} : { title: post.seoTitle, description: post.seoDescription };
+---
+
+<SiteLayout {...head}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+
+  <article class="mx-auto max-w-3xl">
+    {
+      postCategories.length > 0 && (
+        <p class="eyebrow">
+          {postCategories.map((c, i) => (
+            <>
+              {i > 0 && " · "}
+              <a href={categoryPath(c.slug)} class="no-underline">
+                {c.label}
+              </a>
+            </>
+          ))}
+        </p>
+      )
+    }
+    <h1 class="mt-2 text-3xl font-semibold tracking-tight">{post.title}</h1>
+    <p class="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" class="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>
+    </p>
+    {
+      post.coverUrl && (
+        <div class="mt-6 aspect-[16/9] max-h-[45vh] overflow-hidden rounded-xl bg-secondary">
+          <img src={post.coverUrl} alt={post.coverAlt} class="h-full w-full object-cover" />
+        </div>
+      )
+    }
+    <div class="mt-8">
+      <RichContent client:only="react" content={post.richContent} fallbackParagraphs={post.paragraphs} />
+    </div>
+    <div class="mt-8 border-t border-border pt-4">
+      <PostLikeButton client:load post={post} />
+    </div>
+    {
+      postTags.length > 0 && (
+        <div class="mt-6 flex flex-wrap gap-2">
+          {postTags.map((t) => (
+            <a href={tagPath(t.slug)} class="rounded-control border border-border px-3 py-1 text-xs font-medium text-muted-foreground no-underline">
+              {t.label}
+            </a>
+          ))}
+        </div>
+      )
+    }
+    {
+      related.length > 0 && (
+        <aside class="mt-14">
+          <h2 class="mb-6 text-lg font-semibold">Related posts</h2>
+          <div class="grid grid-cols-1 gap-8 sm:grid-cols-3">
+            {related.map((p) => (
+              <PostCard post={p} />
+            ))}
+          </div>
+        </aside>
+      )
+    }
+    {
+      post.commentingEnabled && post.referenceId && (
+        <div class="mt-14">
+          <CommentsView client:load referenceId={post.referenceId} />
+        </div>
+      )
+    }
+  </article>
+</SiteLayout>