clarity-theme 0.1.4 → 0.2.0

package/README.md

@@ -105,9 +105,9 @@ All documents are also available in 简体中文 as sibling `*.zh-CN.md` files.
 - **Getting started** — [new project](./docs/getting-started/new-project.md), [manual installation](./docs/getting-started/manual-installation.md), [migrating from blog-v3](./docs/getting-started/migration-from-blog-v3.md)
 - **Guides** — [configuration](./docs/guides/configuration.md), [content](./docs/guides/content.md), [customization](./docs/guides/customization.md), [integrations](./docs/guides/integrations.md)
 - **Reference** — [public API](./docs/reference/api.md), [routes and outputs](./docs/reference/routes-and-outputs.md), [compatibility matrix](./docs/reference/compatibility.md)
-- **Concepts** — [architecture](./docs/concepts/architecture.md)
-- **Maintainers** — [development](./docs/maintainers/development.md), [testing](./docs/maintainers/testing.md), [upstream sync](./docs/maintainers/upstream-sync.md), [patches](./docs/maintainers/patches.md), [publishing](./docs/maintainers/publishing.md), [release checklist](./docs/maintainers/release-checklist.md), [project status](./docs/maintainers/project-status.md), [roadmap](./docs/maintainers/roadmap.md), [documentation rules](./docs/maintainers/documentation.md)
-- **Release history** — [CHANGELOG](./CHANGELOG.md); historical records live under [docs/history](./docs/history/)
+- **Concepts** — [architecture](./docs/concepts/architecture.md) — the upstream → sync-manifest → `src/` → Layer modules → consumer pipeline, and the SOURCE / TRANSFORM / CLARITY-ONLY / LEGACY source classification
+- **Maintainers** — [development](./docs/maintainers/development.md), [testing & parity](./docs/maintainers/testing.md), [upstream sync](./docs/maintainers/upstream-sync.md), [transform parity](./docs/maintainers/transform-parity.md), [legacy policy](./docs/maintainers/legacy-policy.md), [patches](./docs/maintainers/patches.md), [publishing](./docs/maintainers/publishing.md), [release checklist](./docs/maintainers/release-checklist.md), [project status](./docs/maintainers/project-status.md), [roadmap](./docs/maintainers/roadmap.md), [documentation rules](./docs/maintainers/documentation.md)
+- **Release history** — [CHANGELOG](./CHANGELOG.md); historical records live under [docs/history](./docs/history/) (frozen narratives — not current specification)
 
 ## Development
 

package/README.zh-CN.md

@@ -105,9 +105,9 @@ Clarity 属于应用运行时的一部分（Nuxt 构建与静态生成会直接
 - **入门** — [创建新项目](./docs/getting-started/new-project.zh-CN.md)、[手动安装](./docs/getting-started/manual-installation.zh-CN.md)、[从 blog-v3 迁移](./docs/getting-started/migration-from-blog-v3.zh-CN.md)
 - **指南** — [配置](./docs/guides/configuration.zh-CN.md)、[内容](./docs/guides/content.zh-CN.md)、[自定义](./docs/guides/customization.zh-CN.md)、[集成](./docs/guides/integrations.zh-CN.md)
 - **参考** — [公共 API](./docs/reference/api.zh-CN.md)、[路由与输出](./docs/reference/routes-and-outputs.zh-CN.md)、[兼容性矩阵](./docs/reference/compatibility.zh-CN.md)
-- **概念** — [架构](./docs/concepts/architecture.zh-CN.md)
-- **维护者** — [开发](./docs/maintainers/development.zh-CN.md)、[测试](./docs/maintainers/testing.zh-CN.md)、[上游同步](./docs/maintainers/upstream-sync.zh-CN.md)、[补丁](./docs/maintainers/patches.zh-CN.md)、[发布](./docs/maintainers/publishing.zh-CN.md)、[发布清单](./docs/maintainers/release-checklist.zh-CN.md)、[项目状态](./docs/maintainers/project-status.zh-CN.md)、[路线图](./docs/maintainers/roadmap.zh-CN.md)、[文档规则](./docs/maintainers/documentation.zh-CN.md)
-- **发布历史** — [CHANGELOG](./CHANGELOG.md)；历史记录位于 [docs/history](./docs/history/)
+- **概念** — [架构](./docs/concepts/architecture.zh-CN.md)——upstream → sync-manifest → `src/` → Layer 模块 → consumer 管线，以及 SOURCE / TRANSFORM / CLARITY-ONLY / LEGACY 源码分类
+- **维护者** — [开发](./docs/maintainers/development.zh-CN.md)、[测试与 Parity](./docs/maintainers/testing.zh-CN.md)、[上游同步](./docs/maintainers/upstream-sync.zh-CN.md)、[Transform 面治理](./docs/maintainers/transform-parity.zh-CN.md)、[Legacy 政策](./docs/maintainers/legacy-policy.zh-CN.md)、[补丁](./docs/maintainers/patches.zh-CN.md)、[发布](./docs/maintainers/publishing.zh-CN.md)、[发布清单](./docs/maintainers/release-checklist.zh-CN.md)、[项目状态](./docs/maintainers/project-status.zh-CN.md)、[路线图](./docs/maintainers/roadmap.zh-CN.md)、[文档规则](./docs/maintainers/documentation.zh-CN.md)
+- **发布历史** — [CHANGELOG](./CHANGELOG.md)；历史记录位于 [docs/history](./docs/history/)（冻结叙事——不是现行规范）
 
 ## 开发
 

package/nuxt.config.ts

@@ -38,6 +38,8 @@ export default defineNuxtConfig({
 				// "JetBrains Mono", 思源宋体 "Noto Serif SC"
 				{ rel: 'preconnect', href: 'https://fonts.gstatic.cn', crossorigin: '' },
 				{ rel: 'stylesheet', href: 'https://fonts.googleapis.cn/css2?family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&family=Noto+Serif+SC:wght@200..900&display=swap' },
+				// 抖音美好体 "DOUYINSANSBOLD-GB"
+				{ rel: 'stylesheet', href: 'https://fonts.bytedance.com/dfd/api/v1/css?family=DOUYINSANSBOLD-GB&display=swap' },
 			],
 			templateParams: {
 				separator: '|',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clarity-theme",
   "type": "module",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Clarity Theme — 从 blog-v3 提取的可复用 Nuxt 4 Layer 博客主题",
   "license": "MIT",
   "publishConfig": {
@@ -36,6 +36,7 @@
   },
   "main": "./nuxt.config.ts",
   "files": [
+    "!src/generated",
     "LICENSE",
     "README.md",
     "nuxt.config.ts",
@@ -135,10 +136,17 @@
     "docs:check": "node scripts/check-docs.mjs",
     "verify": "node scripts/verify-theme.mjs",
     "test:sync": "node --test tests/sync-upstream.test.mjs",
+    "test:docs-governance": "node --test tests/docs-governance.test.mjs",
+    "test:config": "node --test tests/config-schema.test.mjs",
+    "test:transform-parity": "node --test tests/transform-parity.test.mjs",
     "test:migration": "node --test tests/migration-skill.test.mjs",
     "test:contract": "node scripts/test-compatibility.mjs --contract-only",
     "test:release": "pnpm verify && pnpm test:consumer && pnpm test:compatibility",
     "test:consumer": "node scripts/test-consumer.mjs",
+    "test:file-generate": "node scripts/test-file-generate.mjs",
+    "test:runtime-parity": "node scripts/test-runtime-parity.mjs",
+    "test:visual-parity": "node scripts/test-visual-parity.mjs",
+    "test:parity": "pnpm test:upstream-parity && pnpm test:runtime-parity && pnpm test:visual-parity",
     "test:compatibility": "node scripts/test-compatibility.mjs",
     "test:create": "pnpm --dir create-clarity-theme test",
     "test:create:e2e": "pnpm --dir create-clarity-theme test:e2e",

package/src/config/app.ts

@@ -1,5 +1,5 @@
 import type { NavItem } from '../types/nav'
-import type { ClarityPublicConfig, ClarityPublicIntegrationsConfig } from './public'
+import type { ClarityPublicIntegrationsConfig } from './public'
 import type { ClarityArticleConfig, ClarityAuthor, ClarityFeedConfig, ClarityHeadScript, ClarityStatsConfig } from './schema'
 
 export interface NavGroup {
@@ -115,20 +115,3 @@ export type ClarityFlatAppConfigInput<T = ClarityFlatAppConfig> = {
 			? ClarityFlatAppConfigInput<T[K]>
 			: T[K]
 }
-
-export type ClarityAppConfig = ClarityPublicConfig & ClarityUiConfig
-
-/**
- * app/app.config.ts 中 `clarity` 键的覆盖输入类型（0.1.x 兼容）：
- * UI 配置深度可选（数组整体替换，与 defu 行为一致）。
- *
- * 站点级字段（site / article / feed / stats / integrations / features / changelog）
- * 不属于 app.config.ts，请写入 clarity.config.ts。
- */
-export type ClarityUiConfigInput<T = ClarityUiConfig> = {
-	[K in keyof T]?: T[K] extends readonly unknown[]
-		? T[K]
-		: T[K] extends object
-			? ClarityUiConfigInput<T[K]>
-			: T[K]
-}

package/src/config/index.ts

@@ -1,6 +1,6 @@
 export type { Nav, NavItem } from '../types/nav'
-export type { ClarityAppConfig, ClarityUiConfig, ClarityUiConfigInput, NavGroup } from './app'
+export type { ClarityUiConfig, NavGroup } from './app'
 export { defineClarityConfig } from './define'
 export type { Arch, FeedEntry, FeedGroup } from './feed'
-export type { ClarityPublicConfig, ClarityPublicIntegrationsConfig } from './public'
+export type { ClarityPublicIntegrationsConfig } from './public'
 export * from './schema'

package/src/config/public.ts

@@ -1,71 +1,13 @@
-import type {
-	ClarityArticleConfig,
-	ClarityAuthor,
-	ClarityChangelogEntry,
-	ClarityConfig,
-	ClarityIntegrationsConfig,
-	ClaritySiteConfig,
-} from './schema'
+import type { ClarityIntegrationsConfig } from './schema'
 
 /**
- * 由 clarity.config.ts 注入 appConfig 的客户端可见配置。
- *
- * 可见性约定（详见 docs/guides/configuration.md）：
- * - 只有客户端渲染确实需要的字段进入 appConfig；
+ * 客户端可见性约定（详见 docs/guides/configuration.md）：
  * - feed、完整 stats、features 与 site.author.email 等服务端/构建期字段
  *   改由 Nitro 私有 runtimeConfig 提供（config/server.ts），不进入客户端 bundle；
  * - 仅构建期使用的字段（integrations.scripts、article.hidePostPrefix、
  *   article.robotsNotIndex）由模块直接消费，同样不进入 appConfig。
- * 这些配置允许进入客户端 bundle，不包含任何密钥（secret 只允许 runtimeConfig）。
+ * 允许进入客户端 bundle 的配置不包含任何密钥（secret 只允许 runtimeConfig）。
  */
 
 /** appConfig 中暴露的 integrations 子集：scripts 仅构建期注入 <head> */
 export type ClarityPublicIntegrationsConfig = Omit<ClarityIntegrationsConfig, 'scripts'>
-
-/** appConfig 中暴露的 site 子集：author.email 仅用于服务端 feed/meta 输出 */
-export type ClarityPublicSiteConfig = Omit<ClaritySiteConfig, 'author'> & {
-	author: Omit<ClarityAuthor, 'email'>
-}
-
-/** appConfig 中暴露的 article 子集：其余字段仅构建期使用 */
-export type ClarityPublicArticleConfig = Pick<ClarityArticleConfig, 'categories' | 'order'>
-
-/**
- * appConfig 中暴露的 stats 子集：由 includePaths 派生的展示事实，
- * 决定 BlogStats 标签使用「文章字数」还是「总字数」，不透出完整匹配规则。
- */
-export interface ClarityPublicStatsConfig {
-	postsOnly: boolean
-}
-
-export interface ClarityPublicConfig {
-	site: ClarityPublicSiteConfig
-	article: ClarityPublicArticleConfig
-	stats: ClarityPublicStatsConfig
-	integrations: ClarityPublicIntegrationsConfig
-	changelog: ClarityChangelogEntry[]
-}
-
-export function toPublicClarityConfig(config: ClarityConfig): ClarityPublicConfig {
-	return {
-		site: {
-			...config.site,
-			author: {
-				name: config.site.author.name,
-				avatar: config.site.author.avatar,
-				homepage: config.site.author.homepage,
-			},
-		},
-		article: {
-			categories: config.article.categories,
-			order: config.article.order,
-		},
-		stats: {
-			postsOnly: config.stats.includePaths.length > 0,
-		},
-		integrations: config.integrations.twikoo
-			? { twikoo: config.integrations.twikoo }
-			: {},
-		changelog: config.changelog,
-	}
-}

package/src/modules/anti-mirror/index.ts

@@ -1,3 +1,5 @@
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { defineNuxtModule } from 'nuxt/kit'
 import { minifySync } from 'oxc-minify'
 import handleMirror from './runtime/client'
@@ -14,10 +16,13 @@ export default defineNuxtModule({
 	meta: {
 		name: 'anti-mirror',
 	},
-	async setup(options, nuxt) {
-		// 生成的数据模块由 clarity-config 在 setup 阶段写入，静态 import 会在
-		// 模块加载阶段读到上一次构建的旧值，因此改为 setup 内动态 import。
-		const { default: blogConfig } = await import('../../generated/blog.config.mjs')
+	async setup(_options, nuxt) {
+		// 生成的数据模块由 clarity-config（先于本模块注册）在 setup 阶段写入
+		// <buildDir>/clarity/；静态相对路径会命中安装包内部位置（穿透 pnpm
+		// 硬链接污染 store），改用基于 buildDir 的 file URL 动态导入，jiti 与
+		// Node 原生加载均可解析。
+		const buildInfoUrl = pathToFileURL(join(nuxt.options.buildDir, 'clarity', 'blog.config.mjs')).href
+		const { default: blogConfig } = await import(buildInfoUrl)
 		nuxt.options.app.head.script ??= []
 		nuxt.options.app.head.script.push({
 			innerHTML: toIifeString(handleMirror, blacklist.map(btoa), btoa(blogConfig.url)),

package/src/modules/clarity-config/index.ts

@@ -3,6 +3,7 @@ import type { ClarityConfig } from '../../config/schema'
 import type { ClarityServerConfig } from '../../config/server'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, relative, resolve } from 'node:path'
+import { platform } from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { createJiti } from 'jiti'
 import {
@@ -14,7 +15,6 @@ import {
 } from 'nuxt/kit'
 import { parse as parseYaml } from 'yaml'
 import { fallbackPnpmWorkspace } from '../../config/pnpm-workspace'
-import { toPublicClarityConfig } from '../../config/public'
 import { clarityConfigSchema } from '../../config/schema'
 import { toServerClarityConfig } from '../../config/server'
 import uiDefaults from '../../config/ui'
@@ -22,6 +22,8 @@ import uiDefaults from '../../config/ui'
 const moduleDir = dirname(fileURLToPath(import.meta.url))
 /** Theme 运行时源码根（src/）：模块位于 src/modules/clarity-config */
 const themeSrcDir = resolve(moduleDir, '../..')
+/** Windows 路径比较需要大小写不敏感（vite 解析产物盘符大小写不定） */
+const IS_WINDOWS = platform === 'win32'
 
 /** app/app.config.ts 中允许作为 UI 覆盖的顶层键（站点级字段属于 clarity.config.ts） */
 const uiConfigKeys = new Set(['component', 'footer', 'header', 'link', 'nav', 'pagination', 'themes'])
@@ -31,6 +33,15 @@ export interface ModuleOptions {
 	configFile?: string
 }
 
+/** 构建数据重定向插件的最小结构化形状（vite resolveId 子集） */
+interface RedirectPlugin {
+	name: string
+	resolveId: {
+		order: 'pre'
+		handler: (source: string) => { id: string } | undefined
+	}
+}
+
 export default defineNuxtModule<ModuleOptions>({
 	meta: {
 		name: 'clarity-config',
@@ -65,7 +76,7 @@ export default defineNuxtModule<ModuleOptions>({
 		// @pinia/nuxt 不会自动扫描 Layer 的 stores 目录，需显式注册
 		addImportsDir(resolve(themeSrcDir, 'stores'))
 
-		// ---- AppConfig 类型化：上游扁平键 + 0.1.x 的 clarity 键都获得类型提示 ----
+		// ---- AppConfig 类型化：上游扁平键获得类型提示 ----
 		// 注意：类型文件生成于 buildDir/types/ 下，相对路径必须以其为基准计算，
 		// 否则导入解析失败会因 skipLibCheck 静默退化为 any（审计发现 #9）。
 		const appConfigTypeDir = resolve(nuxt.options.buildDir, 'types')
@@ -77,15 +88,13 @@ export default defineNuxtModule<ModuleOptions>({
 				// app/types/index.ts 的 Window.twikoo 等环境声明在 node_modules Layer 中
 				// 不会被 tsconfig include 命中（被 node_modules exclude 过滤），需显式导入
 				`import '${globalsTypePath}'`,
-				`import type { ClarityAppConfig, ClarityAppConfigArticle, ClarityUiConfigInput } from '${appConfigTypePath}'`,
+				`import type { ClarityAppConfigArticle, ClarityUiConfig } from '${appConfigTypePath}'`,
 				'',
 				'declare module \'@nuxt/schema\' {',
-				'  // 读取侧：clarity 用 unknown 回落到注入值；UI 扁平键补充完整类型，',
+				'  // 读取侧：UI 扁平键补充完整类型（0.2.0 起不再提供 clarity 嵌套键），',
 				'  // 使上游组件在 JSON 字面量（空数组 / 宽化字符串）下仍获得正确类型。',
 				'  // article 只声明 categories（Record 索引），order / types 保留 Resolved 字面量。',
 				'  interface CustomAppConfig {',
-				'    /** @deprecated 0.1.x 兼容键：UI 覆盖请直接使用顶层扁平键（上游形状） */',
-				'    clarity?: unknown',
 				'    article?: ClarityAppConfigArticle',
 				'    component?: ClarityUiConfig[\'component\']',
 				'    footer?: ClarityUiConfig[\'footer\']',
@@ -94,9 +103,6 @@ export default defineNuxtModule<ModuleOptions>({
 				'    nav?: ClarityUiConfig[\'nav\']',
 				'    themes?: ClarityUiConfig[\'themes\']',
 				'  }',
-				'  interface AppConfigInput {',
-				'    clarity?: ClarityAppConfig | ClarityUiConfigInput',
-				'  }',
 				'}',
 				'',
 			].join('\n'),
@@ -134,42 +140,59 @@ export default defineNuxtModule<ModuleOptions>({
 		// 以 ESM 导入 JSON/YAML），导致含 BlogTech 的页面（首页）在预渲染时崩溃。
 		// 因此在 buildDir 生成等价 ES 模块，运行时别名与 TS 声明都指向生成物。
 		const consumerPkg = (await loadJson(resolve(rootDir, 'package.json'), jiti)) ?? {}
+		const missingPkgFields = ['name', 'version'].filter(field => !consumerPkg[field])
+		if (missingPkgFields.length) {
+			logger.warn(
+				`package.json 缺少 [${missingPkgFields.join(', ')}] 字段，BlogTech 等组件将显示空值`
+				+ '（数据经生成模块归一化，构建不会因此失败）。',
+			)
+		}
 		const pnpmWorkspace = loadPnpmWorkspace(rootDir)
-		// 写入 Theme 包内的固定路径：prepare / build / prerenderer 等多个
-		// Nuxt 实例可能使用不同 buildDir，包内路径在所有上下文中一致可用。
-		const buildInfoDir = resolve(themeSrcDir, 'generated')
-		mkdirSync(buildInfoDir, { recursive: true })
+		// 写入消费项目 buildDir（<buildDir>/clarity/）：生成物是 consumer 私有
+		// 构建数据，写入安装包内部（src/generated）会穿透 pnpm 硬链接污染
+		// store——并发构建共享同一 store 条目时互相覆盖、读取方拿到半写状态
+		// （repair phase 2 定位的静默故障源）。写入必须幂等重入：模块 setup 时
+		// 写一次（供 prepare / jiti 加载的 Layer 模块读取），并在 build:before
+		// 再写一次——Nuxt build 会在模块运行后清理 buildDir，把 setup 阶段的
+		// 生成物删掉，vite 打包前必须重写。
+		const buildInfoDir = resolve(nuxt.options.buildDir, 'clarity')
 		const packageJsonModulePath = join(buildInfoDir, 'package-json.mjs').replaceAll('\\', '/')
-		writeFileSync(packageJsonModulePath, [
-			`const packageJson = ${JSON.stringify({
-				name: String(consumerPkg.name ?? ''),
-				version: String(consumerPkg.version ?? ''),
-				packageManager: String(consumerPkg.packageManager ?? ''),
-			})}`,
-			'export default packageJson',
-			`export const packageManager = ${JSON.stringify(String(consumerPkg.packageManager ?? ''))}`,
-			`export const version = ${JSON.stringify(String(consumerPkg.version ?? ''))}`,
-			'',
-		].join('\n'))
 		const pnpmWorkspaceModulePath = join(buildInfoDir, 'pnpm-workspace.mjs').replaceAll('\\', '/')
-		writeFileSync(pnpmWorkspaceModulePath, `export default ${JSON.stringify(pnpmWorkspace)}\n`)
+		const blogConfigData = toUpstreamBlogConfig(config)
+		const blogConfigModulePath = join(buildInfoDir, 'blog.config.mjs').replaceAll('\\', '/')
+		const writeBuildInfoModules = () => {
+			mkdirSync(buildInfoDir, { recursive: true })
+			writeFileSync(packageJsonModulePath, [
+				`const packageJson = ${JSON.stringify({
+					name: String(consumerPkg.name ?? ''),
+					version: String(consumerPkg.version ?? ''),
+					packageManager: String(consumerPkg.packageManager ?? ''),
+				})}`,
+				'export default packageJson',
+				`export const packageManager = ${JSON.stringify(String(consumerPkg.packageManager ?? ''))}`,
+				`export const version = ${JSON.stringify(String(consumerPkg.version ?? ''))}`,
+				'',
+			].join('\n'))
+			writeFileSync(pnpmWorkspaceModulePath, `export default ${JSON.stringify(pnpmWorkspace)}\n`)
+			writeFileSync(blogConfigModulePath, [
+				`const blogConfig = ${JSON.stringify(blogConfigData)}`,
+				'export default blogConfig',
+				`export const myFeed = ${JSON.stringify(toMyFeedEntry(blogConfigData))}`,
+				'',
+			].join('\n'))
+		}
+		writeBuildInfoModules()
+		nuxt.hook('build:before', writeBuildInfoModules)
 		nuxt.options.alias = {
 			'~~/package.json': packageJsonModulePath,
 			'~~/pnpm-workspace.yaml': pnpmWorkspaceModulePath,
 			...nuxt.options.alias,
 		}
 
-		// 上游形状的 blog.config 数据模块：anti-mirror 等 Layer 模块由 Nuxt 以
-		// jiti 加载，无法解析 #clarity/* 别名（src/blog.config.ts 运行时适配层
-		// 仅适用于 App / Nitro 构建上下文），因此这里把映射结果内联成真实模块。
-		const blogConfigData = toUpstreamBlogConfig(config)
-		const blogConfigModulePath = join(buildInfoDir, 'blog.config.mjs').replaceAll('\\', '/')
-		writeFileSync(blogConfigModulePath, [
-			`const blogConfig = ${JSON.stringify(blogConfigData)}`,
-			'export default blogConfig',
-			`export const myFeed = ${JSON.stringify(toMyFeedEntry(blogConfigData))}`,
-			'',
-		].join('\n'))
+		// 上游形状的 blog.config 数据模块（<buildDir>/clarity/blog.config.mjs）：
+		// anti-mirror 等 jiti 加载的 Layer 模块无法解析 #clarity/* 别名
+		// （src/blog.config.ts 运行时适配层仅适用于 App / Nitro 构建上下文），
+		// 因此把映射结果内联成真实模块，供其以 file URL 动态导入。
 
 		// 两个说明符的 TS 侧声明（app / server 类型工程的路径重定向目标）
 		const yamlDecl = addTypeTemplate({
@@ -229,14 +252,48 @@ export default defineNuxtModule<ModuleOptions>({
 			nitroConfig.typescript.tsConfig.compilerOptions.paths['~~/pnpm-workspace.yaml'] = [withLeadingDot(yamlDecl.filename)]
 		})
 
-		// ---- 消费项目 app/app.config.ts：读取 0.1.x `clarity` 键的 UI 覆盖 ----
+		// ---- Vite 打包上下文的重定向契约 ----
+		// 上方为 `~~/package.json` / `~~/pnpm-workspace.yaml` 设置的精确别名，
+		// 在 dev（JS 版 alias 插件，首个匹配生效）中按预期指向生成模块；
+		// 但生产构建的 bundled 环境使用 rolldown 原生 alias 插件，其匹配
+		// 语义让更短的 `~~` → rootDir 前缀别名抢先，导入被改写为消费项目的
+		// 真实文件路径（consumer package.json 缺 version 时即 MISSING_EXPORT）。
+		// 消费项目的真实文件是数据源而非打包目标，这里以显式 resolveId 契约
+		// 把两个绝对路径重定向到生成模块：client / SSR 打包语义一致，且不再
+		// 依赖跨上下文的隐式别名匹配顺序。
+		const rootPackageJsonId = resolve(rootDir, 'package.json').replaceAll('\\', '/')
+		const rootWorkspaceYamlId = resolve(rootDir, 'pnpm-workspace.yaml').replaceAll('\\', '/')
+		const idEquals = (a: string, b: string) => IS_WINDOWS
+			? a.toLowerCase() === b.toLowerCase()
+			: a === b
+		nuxt.hook('vite:extendConfig', (config) => {
+			// InlineConfig.plugins 是 readonly 声明，但 hook 语义允许就地追加；
+			// 插件形状用本地结构化类型，避免对 vite 类型的直接依赖
+			const plugins = (config as { plugins: Array<RedirectPlugin> }).plugins ??= []
+			plugins.unshift({
+				name: 'clarity:build-data-redirect',
+				resolveId: {
+					order: 'pre',
+					handler(source) {
+						if (idEquals(source, rootPackageJsonId)) {
+							return { id: packageJsonModulePath }
+						}
+						if (idEquals(source, rootWorkspaceYamlId)) {
+							return { id: pnpmWorkspaceModulePath }
+						}
+						return undefined
+					},
+				},
+			})
+		})
+
+		// ---- 消费项目 app/app.config.ts：站点级字段的迁移警告 ----
 		const consumerAppConfig = await loadConsumerAppConfig(nuxt, jiti)
-		const clarityUi = pickUiOverrides(consumerAppConfig?.clarity)
 		await warnSiteLevelAppConfigOverrides(consumerAppConfig, logger)
 
 		// ---- 上游形状的扁平 AppConfig 注入（upstream parity 的关键）----
 		// blog-v3 组件一律通过 useAppConfig() 读取扁平键（title / nav / component.*）。
-		// 这里将 clarity.config.ts + UI 默认值 + 0.1.x clarity 覆盖注入为同一形状；
+		// 这里将 clarity.config.ts + UI 默认值注入为同一形状；
 		// 消费项目仍可在自己的 app.config.ts 中按上游习惯直接覆盖任意扁平键。
 		updateAppConfig({
 			// 站点数据（上游来自 blog.config.ts 展开进 app.config.ts）
@@ -269,34 +326,16 @@ export default defineNuxtModule<ModuleOptions>({
 			stats: config.stats,
 			twikoo: integrations.twikoo ?? { envId: '', preload: '' },
 
-			// UI 配置：站点派生值覆盖结构默认值，0.1.x clarity 覆盖优先级最高
-			...mergeUiConfig(clarityUi, {
-				...uiDefaults,
-				header: {
-					...uiDefaults.header,
-					logo: site.author.avatar ?? site.favicon,
-					subtitle: site.subtitle ?? site.description,
-				},
-				footer: {
-					...uiDefaults.footer,
-					copyright: `© ${new Date().getFullYear()} ${site.author.name}`,
-				},
-			}),
-		})
-
-		// ---- 0.1.x 兼容：继续注入完整的 clarity 键（useClarityConfig() 读取侧）----
-		updateAppConfig({
-			clarity: {
-				...toPublicClarityConfig(config),
-				header: {
-					logo: site.author.avatar ?? '',
-					subtitle: site.subtitle ?? '',
-				},
-				footer: {
-					copyright: site.copyright?.name
-						? `© ${new Date().getFullYear()} ${site.author.name} · ${site.copyright.name}`
-						: `© ${new Date().getFullYear()} ${site.author.name}`,
-				},
+			// UI 配置：站点派生值覆盖结构默认值
+			...uiDefaults,
+			header: {
+				...uiDefaults.header,
+				logo: site.author.avatar ?? site.favicon,
+				subtitle: site.subtitle ?? site.description,
+			},
+			footer: {
+				...uiDefaults.footer,
+				copyright: `© ${new Date().getFullYear()} ${site.author.name}`,
 			},
 		})
 
@@ -438,16 +477,7 @@ async function warnSiteLevelAppConfigOverrides(appConfig: Record<string, unknown
 	if (!appConfig) {
 		return
 	}
-	const offenders = Object.keys(appConfig).filter(key => !uiConfigKeys.has(key) && key !== 'clarity')
-	if (appConfig.clarity && typeof appConfig.clarity === 'object') {
-		const clarityOffenders = Object.keys(appConfig.clarity as Record<string, unknown>).filter(key => !uiConfigKeys.has(key))
-		if (clarityOffenders.length) {
-			logger.warn(
-				`app/app.config.ts 的 clarity 中出现站点级字段 [${clarityOffenders.join(', ')}]，`
-				+ '请将站点配置迁移到 clarity.config.ts。',
-			)
-		}
-	}
+	const offenders = Object.keys(appConfig).filter(key => !uiConfigKeys.has(key))
 	if (offenders.length) {
 		logger.warn(
 			`app/app.config.ts 中出现站点级字段 [${offenders.join(', ')}]，`
@@ -456,33 +486,6 @@ async function warnSiteLevelAppConfigOverrides(appConfig: Record<string, unknown
 	}
 }
 
-/** 深度合并 UI 覆盖：对象递归合并、数组整体替换（覆盖语义） */
-function mergeUiConfig(overrides: Record<string, unknown> | undefined, base: Record<string, unknown>) {
-	if (!overrides) {
-		return base
-	}
-	const result: Record<string, unknown> = { ...base }
-	for (const [key, value] of Object.entries(overrides)) {
-		const baseValue = result[key]
-		result[key]
-			= value && baseValue && typeof value === 'object' && typeof baseValue === 'object'
-				&& !Array.isArray(value) && !Array.isArray(baseValue)
-				? mergeUiConfig(value as Record<string, unknown>, baseValue as Record<string, unknown>)
-				: value
-	}
-	return result
-}
-
-function pickUiOverrides(clarity: unknown) {
-	if (!clarity || typeof clarity !== 'object') {
-		return undefined
-	}
-	const picked = Object.fromEntries(
-		Object.entries(clarity as Record<string, unknown>).filter(([key]) => uiConfigKeys.has(key)),
-	)
-	return Object.keys(picked).length ? picked : undefined
-}
-
 /** clarity.config → 上游 blog.config 扁平形状（与 src/blog.config.ts 适配层保持一致） */
 function toUpstreamBlogConfig(config: ClarityConfig) {
 	const { site, article, feed, stats, integrations } = config

package/src/server/utils/clarity.ts

@@ -4,7 +4,7 @@ import type { ClarityServerConfig } from '../../config/server'
  * 获取服务端专用 Clarity 配置（完整 site/feed/stats 与 feature 路由开关）。
  *
  * 数据来自 Nitro 私有 runtimeConfig，不会进入客户端 bundle；
- * 请只在 server/ 侧调用，客户端渲染请使用 useClarityConfig()。
+ * 请只在 server/ 侧调用；客户端渲染读取扁平 app config（useAppConfig()）。
  */
 export function useClarityServerConfig(): ClarityServerConfig {
 	return useRuntimeConfig().clarity as ClarityServerConfig

package/src/generated/blog.config.mjs

@@ -1,3 +0,0 @@
-const blogConfig = {"title":"Clarity Playground","subtitle":"Clarity Theme 示例站点","description":"Clarity Theme 的最小可运行示例，用于验证 Layer 独立构建与站点配置注入。","author":{"name":"Clarity 用户","avatar":"","email":"user@example.com","homepage":"https://clarity-theme.example.com/"},"copyright":{"abbr":"CC BY 4.0","name":"署名 4.0 国际","url":"https://creativecommons.org/licenses/by/4.0/deed.zh-hans"},"favicon":"/favicon.svg","language":"zh-CN","timeEstablished":"2026-01-01","timeZone":"Asia/Shanghai","url":"http://localhost:22098/","defaultCategory":"未分类","article":{"categories":{"未分类":{"icon":"tabler:circle-dashed"},"技术":{"icon":"tabler:code","color":"#7777ff"},"生活":{"icon":"tabler:leaf","color":"#ff7777"}},"types":{"tech":{},"story":{}},"order":{"date":"创建日期","updated":"更新日期"},"useRandomPremalat":false,"hidePostPrefix":true,"robotsNotIndex":[]},"feed":{"limit":20,"enableStyle":true},"scripts":[],"stats":{"includePaths":["posts/%"]},"twikoo":{"envId":"","preload":""}}
-export default blogConfig
-export const myFeed = {"author":"Clarity 用户","sitenick":"Clarity Playground","title":"Clarity Playground","desc":"Clarity Theme 示例站点","link":"http://localhost:22098/","feed":"http://localhost:22098/atom.xml","icon":"/favicon.svg","avatar":"","archs":["Nuxt"],"date":"2026-01-01","comment":"这是我自己"}

package/src/generated/package-json.mjs

@@ -1,4 +0,0 @@
-const packageJson = {"name":"clarity-theme-playground","version":"0.0.0","packageManager":"pnpm@12.4.1"}
-export default packageJson
-export const packageManager = "pnpm@12.4.1"
-export const version = "0.0.0"

package/src/generated/pnpm-workspace.mjs

@@ -1 +0,0 @@
-export default {"catalogs":{"content":{"@nuxt/content":"^3.16.0"},"framework":{"nuxt":"^4.5.2","vue":"^3.5.42"}}}

package/src/shared/utils/clarity.ts

@@ -1,34 +0,0 @@
-import type { ClarityAppConfig } from '../../config/app'
-import type { FeedEntry } from '../../config/feed'
-import type { ClaritySiteConfig } from '../../config/schema'
-
-/** 获取完整 Clarity 配置（站点配置 + UI 配置） */
-export function useClarityConfig(): ClarityAppConfig {
-	return useAppConfig().clarity as unknown as ClarityAppConfig
-}
-
-/** 获取站点配置（标题、作者、URL 等） */
-export function useClaritySite(): ClaritySiteConfig {
-	return useClarityConfig().site
-}
-
-/** 获取文章配置的客户端子集（分类图标/颜色、排序方式） */
-export function useClarityArticle(): ClarityAppConfig['article'] {
-	return useClarityConfig().article
-}
-
-/** 由站点配置生成本站订阅源条目（用于友链页与 OPML） */
-export function useClaritySiteFeedEntry(): FeedEntry {
-	const site = useClaritySite()
-	return {
-		author: site.author.name,
-		title: site.title,
-		desc: site.subtitle || site.description,
-		link: site.url,
-		feed: new URL('/atom.xml', site.url).toString(),
-		icon: site.favicon,
-		avatar: site.author.avatar || site.favicon,
-		date: site.established || '',
-		comment: '这是我自己',
-	}
-}