@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/blog/project/src/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/project/src/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/project/src/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/project/src/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/project/src/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/project/src/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/project/src/layouts/Layout.astro

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Wix Astro Basics</title>
+	</head>
+	<body>
+		<slot />
+	</body>
+</html>
+
+<style>
+	html,
+	body {
+		margin: 0;
+		width: 100%;
+		height: 100%;
+	}
+</style>

package/skills/wix-headless-templates/blog/project/src/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/project/src/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>

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

@@ -0,0 +1,97 @@
+---
+// Category page — the feed filtered to one category, with the category's header.
+//
+// This is a Wix ITEM PAGE too: the wixMetadata export + <SEO.Tags> (BLOG_CATEGORY) let the site
+// owner edit its title/description in the dashboard and register the route in the sitemap. Keep
+// the SEO pieces and this frontmatter; restyle the template. The first page is fetched
+// SERVER-SIDE with the category filter and seeded into the island together with the filter id, so
+// the island trusts it and fetches nothing on load. An unknown slug is a real 404 (Wix's own router
+// answers 200 with an empty feed; on a headless site a page that exists for no category is a 404).
+import SiteLayout from "../../../layouts/SiteLayout.astro";
+import BlogFeedView from "../../../components/blog/BlogFeedView";
+import { categoryPath, fetchPosts } from "../../../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags, fetchCategoryBySlug } from "../../../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostPage } 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.categoryPageMetadata.pageIdentifier,
+  identifiers: {
+    slug: WIX_APPS.blogs.categoryPageMetadata.identifiers.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 category: BlogCategory | null = null;
+let page: PostPage | undefined;
+let categories: BlogCategory[] = [];
+let tags: BlogTag[] = [];
+let seoTagsServiceConfig = null;
+try {
+  [category, categories, tags, seoTagsServiceConfig] = await Promise.all([
+    fetchCategoryBySlug(slug),
+    fetchBlogCategories(),
+    fetchBlogTags(),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.BLOG_CATEGORY,
+      itemData: { slug },
+    }).catch(() => null),
+  ]);
+  if (category) page = await fetchPosts({ categoryId: category.id });
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream. With no seed the island
+  // fetches the filtered page client-side and shows its own error state.
+}
+
+if (!category) {
+  return new Response(null, { status: 404 });
+}
+
+// One source of head tags: the SEO service when it resolved; else the category's own SEO title
+// (the dashboard's title tag) → its label, and its description.
+const head = seoTagsServiceConfig ? {} : { title: category.title || category.label, description: category.description || undefined };
+---
+
+<SiteLayout {...head}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+
+  <header class="mb-10">
+    {
+      category.coverUrl && (
+        <div class="mb-6 aspect-[16/9] max-h-[40vh] overflow-hidden rounded-xl bg-secondary">
+          <img src={category.coverUrl} alt={category.label} class="h-full w-full object-cover" />
+        </div>
+      )
+    }
+    <p class="eyebrow">Category</p>
+    <h1 class="mt-2 text-2xl font-semibold tracking-tight">{category.label}</h1>
+    {category.description && <p class="mt-3 max-w-2xl text-muted-foreground">{category.description}</p>}
+  </header>
+
+  <BlogFeedView
+    client:load
+    initialPage={page}
+    initialCategoryId={category.id}
+    initialCategories={categories}
+    initialTags={tags}
+    categoryHref={categoryPath}
+    emptyMessage="No posts in this category yet."
+  />
+</SiteLayout>