@zlooks.cn/cli 1.0.5 → 1.0.6

package/templates/blog-theme/src/plugin/page.tsx

@@ -0,0 +1,174 @@
+import { RscLink } from '@hile/rsc/client/navigation';
+import type { BlogPostSummary } from '@zlooks.cn/blog-schema';
+import type { BlogThemeDataLoader, BlogThemeFrameModel, BlogThemeRouteProps } from '@zlooks.cn/blog-theme';
+import { createServiceBackedBlogThemeDataLoader } from '@zlooks.cn/blog-theme/rsc';
+import { ZlooksSeo, type ZlooksSeoModel } from '@zlooks.cn/ui/seo';
+import type { ReactNode } from 'react';
+import { BLOG_THEME } from '../identity.js';
+import BlogFrame from './blog-frame.js';
+import ArchiveFilter from './archive-filter.js';
+import { ArticleEngagement, CommentSection, MarkdownContent } from './blog-interactions.js';
+
+const data = createServiceBackedBlogThemeDataLoader({ definition: BLOG_THEME });
+
+export async function BlogHomePage(props: BlogThemeRouteProps) {
+  const model = await data.home(props);
+  return (
+    <Frame model={model.frame} seo={model.seo}>
+      <section className="theme-hero"><p>{__DISPLAY_NAME_JSON__}</p><h1>{model.frame.site.value.identity.name}</h1></section>
+      <div className="theme-layout">
+        <section>
+          <h2>最新文章</h2>
+          <PostGrid posts={model.posts.items} />
+          <Pagination current={model.page} pageSize={model.pageSize} path="/blog" total={model.posts.total} />
+        </section>
+        <aside className="theme-sidebar">
+          {model.sidebarPages.map((page) => <section key={page.id}><h2><RscLink href={`/blog/pages/${page.slug}`}>{page.title}</RscLink></h2><p>{page.summary}</p></section>)}
+          <section><h2>最新发布</h2>{model.latestPosts.map((post) => <RscLink href={`/blog/posts/${post.slug}`} key={post.id}>{post.title}</RscLink>)}</section>
+          <section><h2>分类</h2>{model.categories.map((category) => <RscLink href={`/blog/categories/${category.slug}`} key={category.id}>{category.name} · {category.postCount}</RscLink>)}</section>
+          <section><h2>标签</h2>{model.tags.map((tag) => <RscLink href={`/blog/tags/${tag.slug}`} key={tag.id}>#{tag.name}</RscLink>)}</section>
+          <section><h2>归档</h2>{model.archive.months.map((month) => <RscLink href={`/blog/archives?year=${month.year}&month=${month.month}`} key={`${month.year}-${month.month}`}>{month.year}-{month.month} · {month.count}</RscLink>)}</section>
+          <section><h2>最新评论</h2>{model.recentComments.map(({ comment, post }) => <RscLink href={`/blog/posts/${post.slug}#comments`} key={comment.id}>{comment.user.displayName ?? '读者'}：{comment.content}</RscLink>)}</section>
+        </aside>
+      </div>
+    </Frame>
+  );
+}
+
+export async function BlogPostPage(props: BlogThemeRouteProps) {
+  const model = await data.post(props);
+  if (model.kind === 'not-found') return renderMissing(model, props, 'post', '文章不存在');
+  return (
+    <Frame model={model.frame} seo={model.seo}>
+      <article className="theme-article">
+        <header>
+          <RscLink href={`/blog/categories/${model.post.category.slug}`}>{model.post.category.name}</RscLink>
+          <h1>{model.post.title}</h1>
+          {model.post.summary ? <p>{model.post.summary}</p> : null}
+          <time dateTime={model.post.publishedAt}>{formatDate(model.post.publishedAt)}</time>
+          <ArticleEngagement key={`${model.post.slug}:${JSON.stringify(model.engagement)}`} engagement={model.engagement} postSlug={model.post.slug} />
+        </header>
+        {model.post.coverUrl ? <img alt="" className="theme-cover" src={model.post.coverUrl} /> : null}
+        <div className="theme-prose"><MarkdownContent>{model.post.content}</MarkdownContent></div>
+        <nav aria-label="文章标签">{model.post.tags.map((tag) => <RscLink href={`/blog/tags/${tag.slug}`} key={tag.id}>#{tag.name}</RscLink>)}</nav>
+        <nav className="theme-connections" aria-label="相邻文章">
+          {model.connections.previousPost ? <RscLink href={`/blog/posts/${model.connections.previousPost.slug}`}>← {model.connections.previousPost.title}</RscLink> : <span />}
+          {model.connections.nextPost ? <RscLink href={`/blog/posts/${model.connections.nextPost.slug}`}>{model.connections.nextPost.title} →</RscLink> : null}
+        </nav>
+        {model.connections.relatedPosts.length ? <section><h2>相关文章</h2><PostGrid posts={model.connections.relatedPosts} /></section> : null}
+        <CommentSection key={`${model.post.slug}:${model.viewerStatus}:${JSON.stringify(model.comments)}`} comments={model.comments} nextCursor={model.nextCommentCursor} postSlug={model.post.slug} viewerStatus={model.viewerStatus} />
+      </article>
+      <aside className="theme-post-sidebar">
+        <h2>最新文章</h2>{model.sidebar.latestPosts.map((post) => <RscLink href={`/blog/posts/${post.slug}`} key={post.id}>{post.title}</RscLink>)}
+        <h2>分类</h2>{model.sidebar.categories.map((category) => <RscLink href={`/blog/categories/${category.slug}`} key={category.id}>{category.name}</RscLink>)}
+        <h2>最新评论</h2>{model.sidebar.recentComments.map(({ comment, post }) => <RscLink href={`/blog/posts/${post.slug}#comments`} key={comment.id}>{comment.content}</RscLink>)}
+      </aside>
+    </Frame>
+  );
+}
+
+export async function BlogArchivePage(props: BlogThemeRouteProps) {
+  const model = await data.archive(props);
+  return (
+    <Frame model={model.frame} seo={model.seo}>
+      <section><header className="theme-page-heading"><h1>文章归档</h1><p>共 {model.archive.total} 篇文章</p></header>
+        <ArchiveFilter filter={model.filter} />
+        <PostGrid posts={model.archive.items} />
+        <Pagination current={model.page} pageSize={model.pageSize} path={archivePath(model.filter)} total={model.archive.total} />
+      </section>
+    </Frame>
+  );
+}
+
+export async function BlogSinglePagePage(props: BlogThemeRouteProps) {
+  const model = await data.page(props);
+  if (!('frame' in model)) return <DeferredFrame props={props} resource="page"><Missing title="页面不存在" /></DeferredFrame>;
+  return (
+    <Frame model={model.frame} seo={model.seo}>
+      {model.kind === 'page' ? <article className="theme-article"><header><h1>{model.page.title}</h1><p>{model.page.summary}</p></header><div className="theme-prose"><MarkdownContent>{model.page.content}</MarkdownContent></div></article> : <Missing title="页面不存在" />}
+    </Frame>
+  );
+}
+
+export async function BlogCategoryPage(props: BlogThemeRouteProps) {
+  return renderTaxonomy(await data.category(props), props, 'category');
+}
+
+export async function BlogTagPage(props: BlogThemeRouteProps) {
+  return renderTaxonomy(await data.tag(props), props, 'tag');
+}
+
+export async function BlogFriendLinksPage(props: BlogThemeRouteProps) {
+  const model = await data.friends(props);
+  return (
+    <Frame model={model.frame} seo={model.seo}>
+      <section><header className="theme-page-heading"><h1>友情链接</h1><p>值得持续访问的站点。</p></header>
+        <div className="theme-friends">{model.links.map((link) => <a href={link.url} key={link.id} rel="noopener noreferrer" target="_blank">{link.logoUrl ? <img alt="" src={link.logoUrl} width={48} height={48} /> : null}<strong>{link.name}</strong>{link.description ? <p>{link.description}</p> : null}</a>)}</div>
+        {model.links.length === 0 ? <Missing title="暂无友情链接" /> : null}
+      </section>
+    </Frame>
+  );
+}
+
+function renderTaxonomy(
+  model: Awaited<ReturnType<BlogThemeDataLoader['category']>>,
+  props: BlogThemeRouteProps,
+  kind: 'category' | 'tag',
+) {
+  if (model.kind === 'not-found') return renderMissing(model, props, kind, `${kind === 'category' ? '分类' : '标签'}不存在`);
+  return (
+    <Frame model={model.frame} seo={model.seo}>
+      <section><header className="theme-page-heading"><h1>{kind === 'tag' ? '# ' : ''}{model.taxonomy.name}</h1><p>共 {model.total} 篇文章</p></header>
+        <PostGrid posts={model.posts} />
+        <Pagination current={model.page} pageSize={model.pageSize} path={model.path} total={model.total} />
+      </section>
+    </Frame>
+  );
+}
+
+function PostGrid({ posts }: { readonly posts: readonly BlogPostSummary[] }) {
+  if (posts.length === 0) return <Missing title="这里还没有文章" />;
+  return <div className="theme-post-grid">{posts.map((post) => <article key={post.id}>{post.coverUrl ? <img alt="" src={post.coverUrl} /> : null}<RscLink href={`/blog/categories/${post.category.slug}`}>{post.category.name}</RscLink><h3><RscLink href={`/blog/posts/${post.slug}`}>{post.title}</RscLink></h3>{post.summary ? <p>{post.summary}</p> : null}<time dateTime={post.publishedAt}>{formatDate(post.publishedAt)}</time></article>)}</div>;
+}
+
+function Pagination({ current, pageSize, path, total }: { readonly current: number; readonly pageSize: number; readonly path: string; readonly total: number }) {
+  const pages = Math.max(1, Math.ceil(total / pageSize));
+  if (pages <= 1) return null;
+  const separator = path.includes('?') ? '&' : '?';
+  const visiblePages = [...new Set([1, ...Array.from({ length: 5 }, (_, index) => current + index - 2), pages])].filter((page) => page >= 1 && page <= pages);
+  return <nav className="theme-pagination" aria-label="分页">{current > 1 ? <RscLink href={`${path}${separator}page=${current - 1}`}>上一页</RscLink> : null}{visiblePages.map((page, index) => <span key={page}>{index > 0 && page - visiblePages[index - 1]! > 1 ? <span aria-hidden="true">… </span> : null}<RscLink aria-current={current === page ? 'page' : undefined} href={`${path}${separator}page=${page}`}>{page}</RscLink></span>)}{current < pages ? <RscLink href={`${path}${separator}page=${current + 1}`}>下一页</RscLink> : null}</nav>;
+}
+
+function Frame({ children, model, seo }: { readonly children: ReactNode; readonly model: BlogThemeFrameModel; readonly seo: ZlooksSeoModel }) {
+  return <><ZlooksSeo seo={seo} /><BlogFrame navigationPages={model.navigationPages} shell={model.shell} site={model.site}>{children}</BlogFrame></>;
+}
+
+function renderMissing(model: object, props: BlogThemeRouteProps, resource: 'post' | 'category' | 'tag', title: string) {
+  return hasFrameAndSeo(model)
+    ? <Frame model={model.frame} seo={model.seo}><Missing title={title} /></Frame>
+    : <DeferredFrame props={props} resource={resource}><Missing title={title} /></DeferredFrame>;
+}
+
+function hasFrameAndSeo(value: object): value is { readonly frame: BlogThemeFrameModel; readonly seo: ZlooksSeoModel } {
+  return 'frame' in value && 'seo' in value;
+}
+
+async function DeferredFrame({ children, props, resource }: { readonly children: ReactNode; readonly props: BlogThemeRouteProps; readonly resource: 'post' | 'page' | 'category' | 'tag' }) {
+  const model = await data.notFound(props, resource);
+  return <Frame model={model.frame} seo={model.seo}>{children}</Frame>;
+}
+
+function Missing({ title }: { readonly title: string }) { return <p className="theme-empty">{title}</p>; }
+function formatDate(value: string) { return new Intl.DateTimeFormat('zh-CN', { dateStyle: 'medium', timeZone: 'Asia/Shanghai' }).format(new Date(value)); }
+function archivePath(filter: {
+  readonly year?: number;
+  readonly month?: number;
+  readonly startYear?: number;
+  readonly startMonth?: number;
+  readonly endYear?: number;
+  readonly endMonth?: number;
+}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(filter)) if (value !== undefined) query.set(key, String(value));
+  return query.size ? `/blog/archives?${query}` : '/blog/archives';
+}

package/templates/blog-theme/src/plugin/styles.d.ts

@@ -0,0 +1 @@
+declare module '*.css';

package/templates/blog-theme/src/plugin/theme.css

@@ -0,0 +1,59 @@
+.theme-shell {
+  --theme-paper: var(--ant-color-bg-layout);
+  --theme-ink: var(--ant-color-text);
+  --theme-muted: var(--ant-color-text-secondary);
+  --theme-line: var(--ant-color-border);
+  --theme-accent: var(--ant-color-primary);
+  color: var(--theme-ink);
+  background: var(--theme-paper);
+}
+
+.theme-shell, .theme-shell * { box-sizing: border-box; }
+.theme-shell a { color: inherit; text-decoration: none; }
+.theme-shell a:focus-visible { outline: 2px solid var(--theme-accent); outline-offset: 3px; }
+.theme-shell { min-height: 100vh; font-family: ui-serif, Georgia, serif; }
+.theme-header { position: sticky; top: 0; z-index: 10; display: flex; gap: 1.25rem; align-items: center; padding: 1rem max(1rem, calc((100vw - 1180px) / 2)); border-bottom: 1px solid var(--theme-line); background: color-mix(in srgb, var(--theme-paper) 92%, transparent); backdrop-filter: blur(12px); }
+.theme-brand { display: flex; gap: .6rem; align-items: center; margin-right: auto; font-size: 1.1rem; }
+.theme-brand img { width: 2rem; height: 2rem; object-fit: contain; }
+.theme-header nav { display: flex; gap: 1rem; align-items: center; }
+.theme-header nav a:hover, .theme-sidebar a:hover { color: var(--theme-accent); }
+.theme-main { width: min(1180px, calc(100% - 2rem)); margin: 0 auto; padding: 3rem 0 5rem; }
+.theme-footer { padding: 2rem; border-top: 1px solid var(--theme-line); color: var(--theme-muted); text-align: center; }
+.theme-hero, .theme-page-heading { margin-bottom: 2.5rem; padding: 4rem 0; border-bottom: 1px solid var(--theme-line); }
+.theme-hero h1, .theme-page-heading h1, .theme-article h1 { margin: .25rem 0; font-size: clamp(2.5rem, 7vw, 5.5rem); line-height: .95; }
+.theme-hero p, .theme-page-heading p, .theme-article header p { color: var(--theme-muted); }
+.theme-layout { display: grid; grid-template-columns: minmax(0, 1fr) 18rem; gap: 4rem; }
+.theme-post-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 1.25rem; }
+.theme-post-grid article, .theme-friends a, .theme-comment-list article { padding: 1.25rem; border: 1px solid var(--theme-line); background: var(--ant-color-bg-container); overflow-wrap: anywhere; }
+.theme-post-grid img { width: 100%; aspect-ratio: 16/9; object-fit: cover; }
+.theme-post-grid h3 { margin: .5rem 0; font-size: 1.45rem; }
+.theme-post-grid p, .theme-post-grid time { color: var(--theme-muted); }
+.theme-sidebar section { margin-bottom: 2rem; }
+.theme-sidebar a, .theme-post-sidebar a { display: block; padding: .35rem 0; }
+.theme-article { width: min(760px, 100%); margin: 0 auto; }
+.theme-article > header { margin-bottom: 2rem; }
+.theme-cover { width: 100%; max-height: 34rem; object-fit: cover; }
+.theme-prose { font-size: 1.08rem; line-height: 1.8; overflow-wrap: anywhere; }
+.theme-prose img { max-width: 100%; height: auto; }
+.theme-prose pre { overflow-x: auto; padding: 1rem; background: #1d1b18; color: #f7f2e8; }
+.theme-engagement { display: flex; gap: 1rem; align-items: center; margin-top: 1rem; }
+.theme-connections, .theme-pagination { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 1rem; margin: 2rem 0; }
+.theme-comments { margin-top: 4rem; padding-top: 2rem; border-top: 1px solid var(--theme-line); }
+.theme-comments form { display: grid; gap: 1rem; margin-bottom: 2rem; }
+.theme-comment-order { display: flex; gap: .5rem; }
+.theme-comment-list { display: grid; gap: 1rem; margin: 1rem 0; }
+.theme-comment-list header { display: flex; justify-content: space-between; gap: 1rem; }
+.theme-comment-list aside { margin-top: 1rem; padding: 1rem; border-left: 3px solid var(--theme-accent); }
+.theme-friends { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 1rem; }
+.theme-search { position: relative; display: flex; gap: .4rem; width: min(18rem, 100%); }
+.theme-search-results { position: absolute; top: calc(100% + .5rem); right: 0; width: min(24rem, 80vw); padding: .5rem; border: 1px solid var(--theme-line); background: var(--theme-paper); box-shadow: 0 1rem 2rem #0002; }
+.theme-search-results a { display: block; padding: .6rem; }
+.theme-empty { padding: 4rem 1rem; color: var(--theme-muted); text-align: center; }
+
+@media (max-width: 820px) {
+  .theme-header { flex-wrap: wrap; }
+  .theme-header nav { order: 3; width: 100%; overflow-x: auto; }
+  .theme-layout { grid-template-columns: 1fr; }
+  .theme-post-grid, .theme-friends { grid-template-columns: 1fr; }
+  .theme-main { padding-top: 1.5rem; }
+}

package/templates/blog-theme/src/services/blog-theme.boot.ts

@@ -0,0 +1,17 @@
+import { fileURLToPath } from 'node:url';
+import type { ServiceRegisterProps } from '@hile/core';
+import { createBlogThemeBootService } from '@zlooks.cn/blog-theme/runtime';
+import { BLOG_THEME } from '../identity.js';
+
+const boot: ServiceRegisterProps<unknown> = createBlogThemeBootService({
+  definition: BLOG_THEME,
+  artifactBuildRoot: fileURLToPath(new URL('../../.hile-rsc', import.meta.url)),
+  registryBootstrap: {
+    REGISTRY_HOST: process.env.REGISTRY_HOST,
+    REGISTRY_PORT: process.env.REGISTRY_PORT,
+  },
+  advertiseHost: process.env.HILE_ADVERTISE_HOST,
+  development: process.env.NODE_ENV === 'development',
+});
+
+export default boot;

package/templates/blog-theme/test/interactions.test.tsx.template

@@ -0,0 +1,177 @@
+// @vitest-environment happy-dom
+import { act, StrictMode, type ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ZlooksUiProvider } from '@zlooks.cn/ui';
+import { ArticleEngagement, BlogSearch, CommentSection } from '../src/plugin/blog-interactions.js';
+import ArchiveFilter from '../src/plugin/archive-filter.js';
+
+const api = vi.hoisted(() => ({
+  searchPosts: vi.fn(), likePost: vi.fn(), unlikePost: vi.fn(), listComments: vi.fn(), createComment: vi.fn(),
+}));
+const navigation = vi.hoisted(() => ({ push: vi.fn() }));
+vi.mock('@zlooks.cn/blog-theme/client', () => ({ createBlogThemeClient: () => api }));
+vi.mock('@hile/rsc/client/navigation', () => ({ RscLink: (props: object) => <a {...props} />, useRscNavigation: () => navigation }));
+
+let root: Root;
+let host: HTMLDivElement;
+beforeEach(() => {
+  vi.resetAllMocks();
+  Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+  host = document.createElement('div');
+  document.body.append(host);
+  root = createRoot(host);
+});
+afterEach(async () => { await act(() => root.unmount()); host.remove(); });
+
+async function render(node: ReactNode) {
+  await act(() => root.render(<StrictMode><ZlooksUiProvider theme="light">{node}</ZlooksUiProvider></StrictMode>));
+}
+async function input(selector: string, value: string) {
+  const element = host.querySelector<HTMLInputElement | HTMLTextAreaElement>(selector)!;
+  const prototype = element.tagName === 'TEXTAREA' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+  await act(() => {
+    Object.getOwnPropertyDescriptor(prototype, 'value')!.set!.call(element, value);
+    element.dispatchEvent(new Event('input', { bubbles: true }));
+  });
+}
+function button(label: string) {
+  return [...host.querySelectorAll('button')].find((item) => item.textContent?.replaceAll(' ', '').includes(label))!;
+}
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (cause: Error) => void;
+  const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no; });
+  return { promise, resolve, reject };
+}
+const comment = { id: 'comment-1', content: '已提交正文', createdAt: '2026-09-01T00:00:00.000Z', user: { displayName: '读者' }, replyContent: null, pendingReview: true };
+const comments = (viewerStatus: 'authenticated' | 'anonymous' | 'unavailable' = 'authenticated') => (
+  <CommentSection comments={[]} nextCursor={null} postSlug="post" viewerStatus={viewerStatus} />
+);
+
+describe('theme interactions', () => {
+  it.each([
+    [{}, '/blog/archives'],
+    [{ year: 2026 }, '/blog/archives?year=2026'],
+    [{ year: 2026, month: 9 }, '/blog/archives?year=2026&month=9'],
+    [{ startYear: 2025, startMonth: 1, endYear: 2026, endMonth: 9 }, '/blog/archives?startYear=2025&startMonth=1&endYear=2026&endMonth=9'],
+  ] as const)('restores and applies archive filters without preserving the previous page: %j', async (filter, path) => {
+    await render(<ArchiveFilter filter={filter} />);
+    await act(() => { host.querySelector('form')!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })); });
+    expect(navigation.push).toHaveBeenCalledWith(path);
+  });
+
+  it('rejects reversed archive ranges and resets the form on navigation', async () => {
+    await render(<ArchiveFilter filter={{ startYear: 2026, startMonth: 1, endYear: 2026, endMonth: 9 }} />);
+    await input('input[aria-label="起始月份"]', '2027-01');
+    await act(() => { host.querySelector('form')!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })); });
+    expect(navigation.push).not.toHaveBeenCalled();
+    expect(host.querySelector('[role="alert"]')).not.toBeNull();
+    await render(<ArchiveFilter filter={{ year: 2024 }} />);
+    expect(host.querySelector<HTMLInputElement>('input[aria-label="年份"]')!.value).toBe('2024');
+    expect(host.querySelector('[role="alert"]')).toBeNull();
+  });
+
+  it('rejects synchronous duplicate submits and preserves newly typed text after success', async () => {
+    const pending = deferred<typeof comment>();
+    api.createComment.mockReturnValue(pending.promise);
+    await render(comments());
+    await input('textarea', '原始正文');
+    const form = host.querySelector('form')!;
+    await act(() => {
+      form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+      form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+    });
+    expect(api.createComment).toHaveBeenCalledTimes(1);
+    await input('textarea', '下一条正文');
+    await act(() => pending.resolve(comment));
+    expect(host.querySelector('textarea')!.value).toBe('下一条正文');
+    expect(host.textContent).toContain('待审核');
+  });
+
+  it.each(['anonymous', 'unavailable'] as const)('hides comment input for %s', async (status) => {
+    await render(comments(status));
+    expect(host.querySelector('textarea')).toBeNull();
+    expect(api.createComment).not.toHaveBeenCalled();
+  });
+
+  it('aborts a pending write on unmount without committing a late result', async () => {
+    const pending = deferred<typeof comment>();
+    api.createComment.mockReturnValue(pending.promise);
+    await render(comments());
+    await input('textarea', '正文');
+    await act(() => host.querySelector('form')!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })));
+    const signal = api.createComment.mock.calls[0]![1].signal as AbortSignal;
+    await act(() => root.render(null));
+    expect(signal.aborted).toBe(true);
+    await act(() => pending.resolve(comment));
+    expect(host.textContent).toBe('');
+  });
+
+  it('keeps the committed sort and cursor when a new sort fails', async () => {
+    api.listComments.mockRejectedValueOnce(new Error('offline'));
+    await render(<CommentSection comments={[comment as never]} nextCursor="old-cursor" postSlug="post" viewerStatus="anonymous" />);
+    await act(() => button('最早优先').click());
+    expect(button('最新优先').getAttribute('aria-pressed')).toBe('true');
+    api.listComments.mockResolvedValueOnce({ items: [], nextCursor: null });
+    await act(() => button('加载更多评论').click());
+    expect(api.listComments.mock.calls[1]![0]).toMatchObject({ order: 'desc', cursor: 'old-cursor' });
+  });
+
+  it('does not allow comment sorting to cancel an in-flight submission', async () => {
+    const pending = deferred<typeof comment>();
+    api.createComment.mockReturnValue(pending.promise);
+    await render(<CommentSection comments={[comment as never]} nextCursor="cursor" postSlug="post" viewerStatus="authenticated" />);
+    await input('textarea', '正文');
+    await act(() => host.querySelector('form')!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })));
+    await act(() => button('最早优先').click());
+    expect(api.listComments).not.toHaveBeenCalled();
+    expect(api.createComment.mock.calls[0]![1].signal.aborted).toBe(false);
+    await act(() => pending.resolve(comment));
+  });
+
+  it('keeps ascending comments ordered when a new submission precedes loading older pages', async () => {
+    const first = { ...comment, id: 'comment-1', content: '最早评论', pendingReview: false };
+    const second = { ...comment, id: 'comment-2', content: '中间评论', createdAt: '2026-09-02T00:00:00.000Z', pendingReview: false };
+    const newest = { ...comment, id: 'comment-3', content: '最新评论', createdAt: '2026-09-03T00:00:00.000Z' };
+    await render(<CommentSection comments={[first as never]} nextCursor="desc-cursor" postSlug="post" viewerStatus="authenticated" />);
+    api.listComments.mockResolvedValueOnce({ items: [first], nextCursor: 'asc-cursor' });
+    await act(() => button('最早优先').click());
+    api.createComment.mockResolvedValueOnce(newest);
+    await input('textarea', newest.content);
+    await act(() => host.querySelector('form')!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })));
+    api.listComments.mockResolvedValueOnce({ items: [second, { ...newest, pendingReview: false }], nextCursor: null });
+    await act(() => button('加载更多评论').click());
+    expect(api.listComments.mock.calls[1]![0]).toMatchObject({ order: 'asc', cursor: 'asc-cursor' });
+    expect([...host.querySelectorAll('.theme-comment-list article p')].map((item) => item.textContent)).toEqual(['最早评论', '中间评论', '最新评论']);
+    expect(host.querySelector('.theme-comment-list')!.textContent).not.toContain('待审核');
+  });
+
+  it('serializes like/unlike writes even before React commits the loading state', async () => {
+    const pending = deferred<{ liked: boolean; likeCount: number }>();
+    api.likePost.mockReturnValue(pending.promise);
+    await render(<ArticleEngagement engagement={{ viewCount: 3, likeCount: 1, viewerState: 'not-liked' }} postSlug="post" />);
+    await act(() => { button('点赞').click(); button('点赞').click(); });
+    expect(api.likePost).toHaveBeenCalledTimes(1);
+    await act(() => pending.resolve({ liked: true, likeCount: 2 }));
+    api.unlikePost.mockResolvedValueOnce({ liked: false, likeCount: 1 });
+    await act(() => button('已赞').click());
+    expect(api.unlikePost).toHaveBeenCalledTimes(1);
+    expect(host.textContent).toContain('点赞 1');
+  });
+
+  it('invalidates stale searches when the query changes and shows a completed empty result', async () => {
+    const pending = deferred<{ items: unknown[] }>();
+    api.searchPosts.mockReturnValueOnce(pending.promise);
+    await render(<BlogSearch />);
+    await input('input', '旧查询');
+    await act(() => host.querySelector('form')!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })));
+    await input('input', '新查询');
+    expect(api.searchPosts.mock.calls[0]![1].signal.aborted).toBe(true);
+    await act(() => pending.resolve({ items: [{ id: 'old', slug: 'old', title: '过期结果' }] }));
+    expect(host.textContent).not.toContain('过期结果');
+    api.searchPosts.mockResolvedValueOnce({ items: [] });
+    await act(() => host.querySelector('form')!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })));
+    expect(host.textContent).toContain('未找到相关文章');
+  });
+});

package/templates/blog-theme/test/pages.test.tsx.template

@@ -0,0 +1,125 @@
+// @vitest-environment happy-dom
+import { createExecutionContext } from '@hile/context';
+import { BlogThemeDataLoader, type BlogThemeDataSource, type BlogThemeRouteProps } from '@zlooks.cn/blog-theme';
+import { serializeGlobalConfigRscSnapshot, GLOBAL_CONFIG_RSC_PARAM } from '@zlooks.cn/global-config-shared';
+import { serializeZlooksRscShellContext, ZLOOKS_RSC_SHELL_CONTEXT_PARAM } from '@zlooks.cn/ui/shell-context';
+import { renderToStaticMarkup } from 'react-dom/server';
+import type { ReactElement } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { BLOG_THEME } from '../src/identity.js';
+import * as pages from '../src/plugin/page.js';
+
+// Only the service acquisition boundary is replaced; the public SDK builds every ViewModel.
+const fixture = vi.hoisted(() => ({ source: undefined as BlogThemeDataSource | undefined }));
+vi.mock('@zlooks.cn/blog-theme/rsc', () => ({
+  createServiceBackedBlogThemeDataLoader: () => new BlogThemeDataLoader({
+    definition: BLOG_THEME,
+    source: () => fixture.source!,
+    callOptions: () => ({ context: createExecutionContext({}), timeout: 5000, retries: 0 }),
+  }),
+}));
+vi.mock('@hile/rsc/client/navigation', () => ({ RscLink: (props: object) => <a {...props} />, useRscNavigation: () => ({ push: vi.fn() }) }));
+
+const instant = '2026-09-01T00:00:00.000Z';
+const category = { id: '018ff2ec-8c3e-7a40-a000-000000000001', slug: 'engineering', name: '工程分类', description: null, sortOrder: 0 };
+const tag = { id: '018ff2ec-8c3e-7a40-a000-000000000002', slug: 'typescript', name: '类型标签' };
+const post = {
+  id: '018ff2ec-8c3e-7a40-a000-000000000003', slug: 'article', title: '真实模型文章', summary: '文章摘要',
+  category, tags: [tag], coverUrl: null, publishedAt: instant, updatedAt: instant,
+};
+const page = {
+  id: '018ff2ec-8c3e-7a40-a000-000000000004', slug: 'about', title: '关于本站', summary: '内容页摘要',
+  position: 'navigation' as const, sortOrder: 0, publishedAt: instant, updatedAt: instant,
+};
+
+function dataSource(): BlogThemeDataSource {
+  return {
+    listPosts: vi.fn<BlogThemeDataSource['listPosts']>().mockResolvedValue({ items: [post], nextCursor: null, total: 30 }),
+    listPostArchive: vi.fn<BlogThemeDataSource['listPostArchive']>().mockResolvedValue({ items: [post], nextCursor: null, total: 30, months: [{ year: 2026, month: 9, count: 30 }] }),
+    readPost: vi.fn<BlogThemeDataSource['readPost']>().mockResolvedValue({ found: true, post: { ...post, content: '## 文章正文' } }),
+    openPost: vi.fn<BlogThemeDataSource['openPost']>().mockResolvedValue({ found: true, post: { ...post, content: '## 文章正文' }, engagement: { viewCount: 3, likeCount: 1, viewerState: 'anonymous' } }),
+    readPostConnections: vi.fn<BlogThemeDataSource['readPostConnections']>().mockResolvedValue({ found: true, connections: { previousPost: null, nextPost: null, relatedPosts: [] } }),
+    listComments: vi.fn<BlogThemeDataSource['listComments']>().mockResolvedValue({ found: true, comments: { items: [], nextCursor: null } }),
+    listRecentComments: vi.fn<BlogThemeDataSource['listRecentComments']>().mockResolvedValue([]),
+    listCategories: vi.fn<BlogThemeDataSource['listCategories']>().mockResolvedValue([{ ...category, postCount: 30 }]),
+    listTags: vi.fn<BlogThemeDataSource['listTags']>().mockResolvedValue([tag]),
+    listPages: vi.fn<BlogThemeDataSource['listPages']>().mockImplementation(async ({ position }) => [{ ...page, position: position ?? null }]),
+    readPage: vi.fn<BlogThemeDataSource['readPage']>().mockResolvedValue({ found: true, page: { ...page, content: '## 内容页正文' } }),
+    listFriendLinks: vi.fn<BlogThemeDataSource['listFriendLinks']>().mockResolvedValue([{ id: '018ff2ec-8c3e-7a40-a000-000000000005', name: '友好站点', url: 'https://friend.example/', description: '友链说明', logoUrl: '/friend.svg', sortOrder: 0 }]),
+  };
+}
+
+function routeProps(slug?: string, searchParams: Record<string, string> = {}): BlogThemeRouteProps {
+  return {
+    params: {
+      ...(slug ? { slug } : {}),
+      [GLOBAL_CONFIG_RSC_PARAM]: serializeGlobalConfigRscSnapshot({ schemaVersion: 2, revision: 1, value: { identity: { name: '测试站点', homeHref: '/' }, linkGroups: [], legal: { registrations: [] } }, updatedAt: instant, updatedBy: 'test-fixture' }),
+      [ZLOOKS_RSC_SHELL_CONTEXT_PARAM]: serializeZlooksRscShellContext({ navigation: [], origin: 'https://theme.example/', pathname: '/blog', user: { status: 'unavailable' } }),
+    },
+    searchParams,
+    rsc: { pluginId: 'blog', buildId: 'unit-test-build' },
+  };
+}
+
+type Page = (props: BlogThemeRouteProps) => Promise<ReactElement>;
+async function html(render: Page, slug?: string, searchParams: Record<string, string> = {}) {
+  let tree = await render(routeProps(slug, searchParams));
+  // Invalid routes use one asynchronous server-only frame; resolve it before the DOM renderer.
+  if (typeof tree.type === 'function' && tree.type.constructor.name === 'AsyncFunction') {
+    tree = await (tree.type as (props: unknown) => Promise<ReactElement>)(tree.props);
+  }
+  const document = new DOMParser().parseFromString(renderToStaticMarkup(tree), 'text/html');
+  expect(document.querySelector('main')).not.toBeNull();
+  expect(document.querySelector('link[rel="canonical"]')?.getAttribute('href')).toMatch(/^https:\/\/theme\.example\/blog/);
+  return document;
+}
+
+beforeEach(() => { fixture.source = dataSource(); });
+
+describe('all theme routes using public SDK ViewModels', () => {
+  it.each([
+    [pages.BlogHomePage, undefined, '真实模型文章'],
+    [pages.BlogPostPage, 'article', '文章正文'],
+    [pages.BlogArchivePage, undefined, '文章归档'],
+    [pages.BlogSinglePagePage, 'about', '内容页正文'],
+    [pages.BlogCategoryPage, 'engineering', '工程分类'],
+    [pages.BlogTagPage, 'typescript', '类型标签'],
+    [pages.BlogFriendLinksPage, undefined, '友好站点'],
+  ] as const)('renders a complete %s route with shell and SEO', async (render, slug, text) => {
+    const document = await html(render, slug);
+    expect(document.body.textContent).toContain(text);
+    expect(document.querySelectorAll('h1')).toHaveLength(1);
+    expect(document.querySelector('meta[name="robots"]')?.getAttribute('content')).toBe('index, follow');
+    expect(document.querySelector('textarea')).toBeNull();
+  });
+
+  it.each([pages.BlogPostPage, pages.BlogSinglePagePage, pages.BlogCategoryPage, pages.BlogTagPage])('renders invalid parameters with noindex SEO', async (render) => {
+    const document = await html(render, 'INVALID');
+    expect(document.body.textContent).toContain('不存在');
+    expect(document.querySelector('meta[name="robots"]')?.getAttribute('content')).toBe('noindex, nofollow');
+    expect(fixture.source!.openPost).not.toHaveBeenCalled();
+  });
+
+  it('preserves all archive filters in numbered pagination links', async () => {
+    vi.mocked(fixture.source!.listPostArchive).mockResolvedValue({ items: [post], nextCursor: null, total: BLOG_THEME.query.archivePageSize + 1, months: [] });
+    const document = await html(pages.BlogArchivePage, undefined, { startYear: '2025', startMonth: '1', endYear: '2026', endMonth: '9' });
+    const href = document.querySelector('nav[aria-label="分页"] a[href*="page=2"]')?.getAttribute('href');
+    expect(href).toContain('startYear=2025&startMonth=1&endYear=2026&endMonth=9&page=2');
+  });
+
+  it('links sidebar pages and shows an explicit empty friend-link state', async () => {
+    const home = await html(pages.BlogHomePage);
+    expect(home.querySelector('aside a[href="/blog/pages/about"]')).not.toBeNull();
+    vi.mocked(fixture.source!.listFriendLinks).mockResolvedValue([]);
+    expect((await html(pages.BlogFriendLinksPage)).body.textContent).toContain('暂无友情链接');
+  });
+
+  it('renders missing content and empty lists without inventing content', async () => {
+    vi.mocked(fixture.source!.openPost).mockResolvedValue({ found: false });
+    expect((await html(pages.BlogPostPage, 'missing')).body.textContent).toContain('文章不存在');
+    vi.mocked(fixture.source!.listPosts).mockResolvedValue({ items: [], total: 0, nextCursor: null });
+    const home = await html(pages.BlogHomePage);
+    expect(home.body.textContent).toContain('这里还没有文章');
+    expect(home.querySelector('nav[aria-label="分页"]')).toBeNull();
+  });
+});