@zlooks.cn/cli 1.0.5 → 1.0.7

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

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

@@ -0,0 +1,102 @@
+// @vitest-environment happy-dom
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ZlooksRscShellContext } from '@zlooks.cn/ui/shell-context';
+import BlogFrame from '../src/plugin/blog-frame.js';
+
+const navigation = vi.hoisted(() => ({ push: vi.fn(), refresh: vi.fn() }));
+vi.mock('@hile/rsc/client/navigation', () => ({ RscLink: (props: object) => <a {...props} />, useRscNavigation: () => navigation }));
+let host: HTMLDivElement;
+let root: Root;
+const fetchMock = vi.fn();
+const site = {
+  schemaVersion: 2 as const, revision: 1, updatedAt: '2026-09-01T00:00:00.000Z', updatedBy: 'test',
+  value: { identity: { name: '测试站点', homeHref: '/' }, linkGroups: [], legal: {
+    copyright: '测试版权', registrations: [{ id: 'icp', kind: 'icp' as const, number: '测试备案', verificationUrl: 'https://beian.miit.gov.cn/' }],
+  } },
+};
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.stubGlobal('fetch', fetchMock);
+  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(); vi.unstubAllGlobals(); });
+
+async function render(user: ZlooksRscShellContext['user']) {
+  await act(() => root.render(<BlogFrame navigationPages={[]} shell={{
+    user, origin: 'https://theme.example', pathname: '/blog',
+    navigation: [{ key: 'blog:home', label: '博客', href: '/blog', order: 1 }, { key: 'other', label: '其他功能', href: '/other', order: 2 }],
+  }} site={site}><p>页面内容</p></BlogFrame>));
+}
+function button(label: string) {
+  const found = [...document.querySelectorAll('button')].find((item) => item.getAttribute('aria-label') === label || item.textContent?.trim() === label);
+  expect(found, label).toBeDefined();
+  return found!;
+}
+const authenticated = { status: 'authenticated' as const, user: { label: '测试读者', avatarText: '读' }, accountHref: '/account', logoutHref: '/api/user/logout' };
+
+describe('shared UI shell', () => {
+  it('uses Host navigation and site legal data without an initialization fetch', async () => {
+    await render({ status: 'anonymous', loginMethods: [] });
+    expect(host.querySelector('nav a[href="/other"]')?.textContent).toBe('其他功能');
+    expect(host.querySelectorAll('nav a[href="/blog"]')).toHaveLength(1);
+    expect(host.querySelector('nav a[aria-current="page"]')?.getAttribute('href')).toBe('/blog');
+    expect(host.querySelector('footer')?.textContent).toContain('测试版权');
+    expect(host.querySelector('footer a')?.textContent).toBe('测试备案');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('opens real shared login methods and navigates through the Host port', async () => {
+    await render({ status: 'anonymous', loginMethods: [{ id: 'password', label: '密码登录', href: '/auth.password' }] });
+    await act(() => button('登录').click());
+    const link = document.querySelector<HTMLAnchorElement>('a[href="/auth.password"]');
+    expect(link).not.toBeNull();
+    await act(() => link!.click());
+    expect(navigation.push).toHaveBeenCalledWith('/auth.password');
+  });
+
+  it('disables account access when the upstream is unavailable', async () => {
+    await render({ status: 'unavailable' });
+    expect(button('账户服务暂不可用').disabled).toBe(true);
+    expect(document.querySelector('[aria-label="登录"]')).toBeNull();
+  });
+
+  it('switches light, dark and system preference through the shared hook', async () => {
+    await render({ status: 'unavailable' });
+    for (const [label, mode] of [['浅色', 'light'], ['深色', 'dark'], ['自动', 'default']] as const) {
+      const control = [...host.querySelectorAll('label')].find((item) => item.textContent === label);
+      expect(control).toBeDefined();
+      await act(() => control!.click());
+      expect(window.localStorage.getItem('zlooks.theme')).toBe(mode);
+      expect(control!.querySelector<HTMLInputElement>('input')?.checked).toBe(true);
+    }
+  });
+
+  it('opens the account menu and confirms logout before requesting and refreshing', async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ code: 0, data: {} }), { status: 200 }));
+    await render(authenticated);
+    await act(() => button('打开测试读者的账户信息').click());
+    expect(document.querySelector('a[href="/account"]')).not.toBeNull();
+    await act(() => button('退出登录').click());
+    expect(fetchMock).not.toHaveBeenCalled();
+    const dialog = [...document.querySelectorAll('[role="dialog"]')].find((item) => item.textContent?.includes('确认退出登录'));
+    expect(dialog?.textContent).toContain('确认退出登录');
+    await act(() => [...dialog!.querySelectorAll('button')].find((item) => item.textContent === '退出登录')!.click());
+    expect(fetchMock).toHaveBeenCalledWith('/api/user/logout', expect.objectContaining({ method: 'POST', credentials: 'same-origin' }));
+    expect(navigation.refresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps logout confirmation open and does not refresh when the server rejects it', async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ code: 1, error: '退出暂不可用' }), { status: 503 }));
+    await render(authenticated);
+    await act(() => button('打开测试读者的账户信息').click());
+    await act(() => button('退出登录').click());
+    const dialog = [...document.querySelectorAll('[role="dialog"]')].find((item) => item.textContent?.includes('确认退出登录'))!;
+    await act(() => [...dialog.querySelectorAll('button')].find((item) => item.textContent === '退出登录')!.click());
+    expect(navigation.refresh).not.toHaveBeenCalled();
+    expect(document.body.textContent).toContain('退出暂不可用');
+    expect(dialog.isConnected).toBe(true);
+  });
+});

package/templates/blog-theme/test/theme-contract.test.ts.template

@@ -0,0 +1,43 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const root = resolve(import.meta.dirname, '..');
+
+describe('theme contract', () => {
+  it('keeps one SDK-owned boot composition root', async () => {
+    const services = await readdir(resolve(root, 'src/services'), { recursive: true });
+    expect(services.filter((path) => path.endsWith('.ts'))).toEqual(['blog-theme.boot.ts']);
+    const boot = await readFile(resolve(root, 'src/services/blog-theme.boot.ts'), 'utf8');
+    expect(boot).toContain('@zlooks.cn/blog-theme/runtime');
+    expect(boot).toContain('createBlogThemeBootService');
+  });
+
+  it('declares every Blog route', async () => {
+    const config = JSON.parse(await readFile(resolve(root, 'hile-rsc.json'), 'utf8')) as {
+      readonly pluginId: string;
+      readonly routes: readonly { readonly path: string }[];
+    };
+    expect(config.pluginId).toBe('blog');
+    expect(config.routes.map(({ path }) => path)).toEqual([
+      '/', '/posts/[slug]', '/archives', '/pages/[slug]', '/categories/[slug]', '/tags/[slug]', '/friends',
+    ]);
+  });
+
+  it('uses SDK-owned server data and client interactions', async () => {
+    const page = await readFile(resolve(root, 'src/plugin/page.tsx'), 'utf8');
+    const interactions = await readFile(resolve(root, 'src/plugin/blog-interactions.tsx'), 'utf8');
+    expect(page).toContain('createServiceBackedBlogThemeDataLoader');
+    expect(page).not.toMatch(/@zlooks\.cn\/blog-shared|loadService\(/);
+    expect(interactions).toContain('@zlooks.cn/blog-theme/client');
+    for (const method of ['searchPosts', 'likePost', 'unlikePost', 'listComments', 'createComment']) {
+      expect(interactions).toContain(method);
+    }
+  });
+
+  it('renders Markdown without raw HTML injection', async () => {
+    const interactions = await readFile(resolve(root, 'src/plugin/blog-interactions.tsx'), 'utf8');
+    expect(interactions).toContain('react-markdown');
+    expect(interactions).not.toContain('dangerouslySetInnerHTML');
+  });
+});

package/templates/blog-theme/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["DOM", "DOM.Iterable", "ES2024"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts", "test/**/*.tsx", "vitest.config.ts"],
+  "exclude": ["node_modules", "dist", ".hile-rsc"]
+}

package/templates/blog-theme/tsconfig.runtime.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/plugin", "node_modules", "dist", ".hile-rsc", "test"]
+}

package/templates/blog-theme/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.{ts,tsx}'],
+    server: { deps: { inline: [/@zlooks\.cn\/ui/, /antd/, /@ant-design/, /@rc-component/] } },
+  },
+});