clarity-theme 0.1.0 → 0.1.2

package/{modules → src/modules}/clarity-config/index.ts

@@ -1,63 +1,67 @@
 import type { Nuxt } from '@nuxt/schema'
 import type { ClarityConfig } from '../../config/schema'
+import type { ClarityServerConfig } from '../../config/server'
 import { existsSync } from 'node:fs'
-import { dirname, relative, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { dirname, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { createJiti } from 'jiti'
 import {
 	addImportsDir,
 	addTypeTemplate,
 	defineNuxtModule,
-	updateAppConfig,
-	useLogger,
-} from 'nuxt/kit'
-import nuxtPkg from 'nuxt/package.json'
-import { minify } from 'oxc-minify'
-import vuePkg from 'vue/package.json'
+	updateAppConfig,
+	useLogger,
+} from 'nuxt/kit'
+import nuxtPkg from 'nuxt/package.json'
+import { minify } from 'oxc-minify'
+import vuePkg from 'vue/package.json'
 import { toPublicClarityConfig } from '../../config/public'
-import { toServerClarityConfig } from '../../config/server'
 import { clarityConfigSchema } from '../../config/schema'
+import { toServerClarityConfig } from '../../config/server'
 import handleMirror from './anti-mirror-client'
-
-const moduleDir = dirname(fileURLToPath(import.meta.url))
-const themeDir = resolve(moduleDir, '../..')
-
+
+const moduleDir = dirname(fileURLToPath(import.meta.url))
+/** Theme 运行时源码根（src/）：模块位于 src/modules/clarity-config */
+const themeSrcDir = resolve(moduleDir, '../..')
+/** Theme npm 包根（nuxt.config.ts / package.json 所在层） */
+const themePkgDir = resolve(moduleDir, '../../..')
+
 /** app/app.config.ts 的 clarity 键只允许 UI 覆盖（站点级字段属于 clarity.config.ts） */
 const uiConfigKeys = new Set(['component', 'footer', 'header', 'link', 'nav', 'pagination', 'themes'])
-
-export interface ModuleOptions {
-	/** 消费项目中 clarity 配置文件路径（相对 rootDir） */
-	configFile?: string
-}
-
-export default defineNuxtModule<ModuleOptions>({
-	meta: {
-		name: 'clarity-config',
-		configKey: 'clarityConfig',
-	},
-
-	async setup(options, nuxt) {
-		const logger = useLogger('clarity-config')
-		const rootDir = nuxt.options.rootDir
-
-		const configPath = resolve(rootDir, options.configFile ?? findConfigFile(rootDir))
-		const feedsPath = findFeedsFile(rootDir, themeDir)
-
-		// ---- 依赖注入层：Theme 内部不感知消费项目的文件布局 ----
-		Object.assign(nuxt.options.alias, {
-			'#clarity/config': configPath,
-			'#clarity/feeds': feedsPath.resolved,
-		})
-
+
+export interface ModuleOptions {
+	/** 消费项目中 clarity 配置文件路径（相对 rootDir） */
+	configFile?: string
+}
+
+export default defineNuxtModule<ModuleOptions>({
+	meta: {
+		name: 'clarity-config',
+		configKey: 'clarityConfig',
+	},
+
+	async setup(options, nuxt) {
+		const logger = useLogger('clarity-config')
+		const rootDir = nuxt.options.rootDir
+
+		const configPath = resolve(rootDir, options.configFile ?? findConfigFile(rootDir))
+		const feedsPath = findFeedsFile(rootDir, themeSrcDir)
+
+		// ---- 依赖注入层：Theme 内部不感知消费项目的文件布局 ----
+		Object.assign(nuxt.options.alias, {
+			'#clarity/config': configPath,
+			'#clarity/feeds': feedsPath.resolved,
+		})
+
 		// @pinia/nuxt 不会自动扫描 Layer 的 stores 目录，需显式注册
-		addImportsDir(resolve(themeDir, 'app/stores'))
+		addImportsDir(resolve(themeSrcDir, 'stores'))
 
 		// ---- AppConfig 类型化：消费者 defineAppConfig({ clarity: ... }) 获得完整类型提示 ----
 		// 注意：类型文件生成于 buildDir/types/ 下，相对路径必须以其为基准计算，
 		// 否则导入解析失败会因 skipLibCheck 静默退化为 any（审计发现 #9）。
 		const appConfigTypeDir = resolve(nuxt.options.buildDir, 'types')
-		const appConfigTypePath = relative(appConfigTypeDir, resolve(themeDir, 'config/app.ts')).replaceAll('\\', '/')
-		const globalsTypePath = relative(appConfigTypeDir, resolve(themeDir, 'app/types/index.ts')).replaceAll('\\', '/')
+		const appConfigTypePath = relative(appConfigTypeDir, resolve(themeSrcDir, 'config/app.ts')).replaceAll('\\', '/')
+		const globalsTypePath = relative(appConfigTypeDir, resolve(themeSrcDir, 'types/index.ts')).replaceAll('\\', '/')
 		addTypeTemplate({
 			filename: 'types/clarity-app-config.d.ts',
 			getContents: () => [
@@ -79,27 +83,27 @@ export default defineNuxtModule<ModuleOptions>({
 				'',
 			].join('\n'),
 		})
-
-		// @bikariya/shiki 运行时固定导入 ~/shiki.config，
-		// 消费项目未提供时回退到 Theme 内置配置；
-		// 需置于 '~' 之前以保证 Vite 别名前缀优先匹配
-		if (!existsSync(resolve(nuxt.options.srcDir, 'shiki.config.ts'))) {
-			nuxt.options.alias = {
-				'~/shiki.config': resolve(themeDir, 'app/shiki.config.ts'),
-				...nuxt.options.alias,
-			}
-		}
-
-		if (!existsSync(configPath)) {
-			throw new Error(
-				`[clarity-config] 未找到 ${configPath}。`
-				+ '请在消费项目根目录创建 clarity.config.ts（可参考 playground/clarity.config.ts）。',
-			)
-		}
-		if (!feedsPath.found) {
-			logger.warn('未找到 feeds.ts，友链页面与 OPML 订阅将输出空数据。')
-		}
-
+
+		// @bikariya/shiki 运行时固定导入 ~/shiki.config，
+		// 消费项目未提供时回退到 Theme 内置配置；
+		// 需置于 '~' 之前以保证 Vite 别名前缀优先匹配
+		if (!existsSync(resolve(nuxt.options.srcDir, 'shiki.config.ts'))) {
+			nuxt.options.alias = {
+				'~/shiki.config': resolve(themeSrcDir, 'shiki.config.ts'),
+				...nuxt.options.alias,
+			}
+		}
+
+		if (!existsSync(configPath)) {
+			throw new Error(
+				`[clarity-config] 未找到 ${configPath}。`
+				+ '请在消费项目根目录创建 clarity.config.ts（可参考 playground/clarity.config.ts）。',
+			)
+		}
+		if (!feedsPath.found) {
+			logger.warn('未找到 feeds.ts，友链页面与 OPML 订阅将输出空数据。')
+		}
+
 		// ---- 读取并校验站点配置（错误在构建开始前暴露） ----
 		const jiti = createJiti(import.meta.url, { moduleCache: false, interopDefault: true })
 		const configModule = await importConfigFile(jiti, configPath)
@@ -108,31 +112,33 @@ export default defineNuxtModule<ModuleOptions>({
 
 		// ---- 边界审计：app/app.config.ts 中不应出现站点级字段（其优先级更高，会覆盖站点配置注入） ----
 		await warnNonUiAppConfigOverrides(nuxt, jiti, logger)
-
+
 		// ---- Site Config → App Config 桥梁 ----
-		// 注意 Nuxt appConfig 合并优先级：消费项目 app.config > Theme app.config > 模块注入，
-		// 因此站点派生默认值（header.logo 等）不放入 Theme 的 app.config.ts，
-		// 由这里注入后仍可被消费项目覆盖。
+		// 注意 Nuxt appConfig 合并优先级：消费项目 app.config > Theme app.config > 模块注入，
+		// 因此站点派生默认值（header.logo 等）不放入 Theme 的 app.config.ts，
+		// 由这里注入后仍可被消费项目覆盖。
 		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}`,
-				},
-			},
+			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}`,
+				},
+			},
 		})
 
 		// ---- 服务端专用配置：注入 Nitro 私有 runtimeConfig（不进入客户端 bundle）----
 		// Atom/OPML/stats 处理器与 feature 路由守卫从这里读取完整配置。
-		nuxt.options.runtimeConfig.clarity = toServerClarityConfig(config)
-
-		// ---- SEO / site / robots / llms ----
+		// 注意：Nuxt 会按消费者实际值推导 runtimeConfig 类型（可选字段可能被推断为必填），
+		// 此处以 Theme 声明的 ClarityServerConfig 为准，避免与消费者无关的推断形状冲突。
+		;(nuxt.options.runtimeConfig as { clarity?: ClarityServerConfig }).clarity = toServerClarityConfig(config)
+
+		// ---- SEO / site / robots / llms ----
 		nuxt.options.site = {
 			...nuxt.options.site,
 			name: site.title,
@@ -153,61 +159,61 @@ export default defineNuxtModule<ModuleOptions>({
 			title: site.title,
 			description: site.description,
 		}
-
-		// ---- Head 元数据 ----
-		const head = nuxt.options.app.head
-		head.meta ??= []
-		head.meta.push({ name: 'author', content: [site.author.name, site.author.email].filter(Boolean).join(', ') })
-		head.link ??= []
-		head.link.push({ rel: 'icon', href: site.favicon })
-		if (features.atom) {
-			head.link.push({ rel: 'alternate', type: 'application/atom+xml', href: '/atom.xml' })
-		}
-		const twikooPreload = integrations.twikoo?.preload ?? integrations.twikoo?.envId
-		if (twikooPreload) {
-			head.link.push({ rel: 'preconnect', href: twikooPreload })
-		}
-		head.script ??= []
-		head.script.push(...integrations.scripts as any[])
-		head.titleTemplate = `%s %separator ${site.title}`
-
-		// ---- 构建信息（供 BlogTech 等 Widget 使用） ----
-		const consumerPkg = await loadJson(resolve(rootDir, 'package.json'), jiti)
-		const themePkg = await loadJson(resolve(themeDir, 'package.json'), jiti)
-		nuxt.options.runtimeConfig.public.clarity = {
-			theme: 'Clarity',
-			themeVersion: String(themePkg?.version ?? ''),
-			themeHomepage: String(themePkg?.homepage ?? ''),
-			siteVersion: String(consumerPkg?.version ?? ''),
-			sitePackageManager: String(consumerPkg?.packageManager ?? ''),
-			nuxtVersion: nuxtPkg.version,
-			vueVersion: vuePkg.version,
-		}
-
-		// ---- 路由规则 ----
+
+		// ---- Head 元数据 ----
+		const head = nuxt.options.app.head
+		head.meta ??= []
+		head.meta.push({ name: 'author', content: [site.author.name, site.author.email].filter(Boolean).join(', ') })
+		head.link ??= []
+		head.link.push({ rel: 'icon', href: site.favicon })
+		if (features.atom) {
+			head.link.push({ rel: 'alternate', type: 'application/atom+xml', href: '/atom.xml' })
+		}
+		const twikooPreload = integrations.twikoo?.preload ?? integrations.twikoo?.envId
+		if (twikooPreload) {
+			head.link.push({ rel: 'preconnect', href: twikooPreload })
+		}
+		head.script ??= []
+		head.script.push(...integrations.scripts as any[])
+		head.titleTemplate = `%s %separator ${site.title}`
+
+		// ---- 构建信息（供 BlogTech 等 Widget 使用） ----
+		const consumerPkg = await loadJson(resolve(rootDir, 'package.json'), jiti)
+		const themePkg = await loadJson(resolve(themePkgDir, 'package.json'), jiti)
+		nuxt.options.runtimeConfig.public.clarity = {
+			theme: 'Clarity',
+			themeVersion: String(themePkg?.version ?? ''),
+			themeHomepage: String(themePkg?.homepage ?? ''),
+			siteVersion: String(consumerPkg?.version ?? ''),
+			sitePackageManager: String(consumerPkg?.packageManager ?? ''),
+			nuxtVersion: nuxtPkg.version,
+			vueVersion: vuePkg.version,
+		}
+
+		// ---- 路由规则 ----
 		const routeRules = nuxt.options.routeRules ??= {}
-		if (features.stats) {
-			routeRules['/api/stats'] = { prerender: true, headers: { 'Content-Type': 'application/json' } }
-		}
-		if (features.atom) {
-			routeRules['/atom.xml'] = { prerender: true, headers: { 'Content-Type': 'application/xml' } }
-		}
-		if (features.opml) {
-			routeRules['/subscriptions.opml'] = { prerender: true, headers: { 'Content-Type': 'application/xml' } }
-		}
-		routeRules['/favicon.ico'] = { redirect: { to: site.favicon } }
-
-		// ---- 自定义链接与 /posts 前缀处理 ----
-		nuxt.hook('content:file:afterParse', (ctx) => {
-			const { permalink, path } = ctx.content as Record<string, string | undefined>
-			if (permalink) {
-				ctx.content.path = permalink
-			}
-			else if (article.hidePostPrefix && path?.startsWith('/posts/')) {
-				ctx.content.path = path.slice('/posts'.length)
-			}
-		})
-
+		if (features.stats) {
+			routeRules['/api/stats'] = { prerender: true, headers: { 'Content-Type': 'application/json' } }
+		}
+		if (features.atom) {
+			routeRules['/atom.xml'] = { prerender: true, headers: { 'Content-Type': 'application/xml' } }
+		}
+		if (features.opml) {
+			routeRules['/subscriptions.opml'] = { prerender: true, headers: { 'Content-Type': 'application/xml' } }
+		}
+		routeRules['/favicon.ico'] = { redirect: { to: site.favicon } }
+
+		// ---- 自定义链接与 /posts 前缀处理 ----
+		nuxt.hook('content:file:afterParse', (ctx) => {
+			const { permalink, path } = ctx.content as Record<string, string | undefined>
+			if (permalink) {
+				ctx.content.path = permalink
+			}
+			else if (article.hidePostPrefix && path?.startsWith('/posts/')) {
+				ctx.content.path = path.slice('/posts'.length)
+			}
+		})
+
 		// ---- 可选功能：anti-mirror ----
 		// 黑名单完全由站点配置提供；Theme 不携带任何上游默认域名（审计发现 #5）。
 		if (features.antiMirror !== false) {
@@ -286,7 +292,7 @@ async function warnNonUiAppConfigOverrides(nuxt: Nuxt, jiti: ReturnType<typeof c
 		}
 	}
 }
-
+
 async function injectAntiMirror(nuxt: Nuxt, blacklist: string[], target: string) {
 	const source = `(${handleMirror.toString()})(${JSON.stringify(blacklist.map(btoa))},${JSON.stringify(btoa(target))})`
 	const { code, errors } = await minify('clarity-anti-mirror.iife.js', source)
@@ -295,30 +301,30 @@ async function injectAntiMirror(nuxt: Nuxt, blacklist: string[], target: string)
 	}
 	;(nuxt.options.app.head.script ??= []).push({ innerHTML: code })
 }
-
-function findConfigFile(rootDir: string) {
-	for (const name of ['clarity.config.ts', 'clarity.config.mjs', 'clarity.config.js']) {
-		if (existsSync(resolve(rootDir, name))) {
-			return name
-		}
-	}
-	return 'clarity.config.ts'
-}
-
-function findFeedsFile(rootDir: string, themeDir: string) {
-	for (const name of ['feeds.ts', 'feeds.mjs', 'feeds.js']) {
-		if (existsSync(resolve(rootDir, name))) {
-			return { found: true, resolved: resolve(rootDir, name) }
-		}
-	}
-	return { found: false, resolved: resolve(themeDir, 'config/feeds.empty.ts') }
-}
-
-async function loadJson(path: string, jiti: ReturnType<typeof createJiti>) {
-	try {
+
+function findConfigFile(rootDir: string) {
+	for (const name of ['clarity.config.ts', 'clarity.config.mjs', 'clarity.config.js']) {
+		if (existsSync(resolve(rootDir, name))) {
+			return name
+		}
+	}
+	return 'clarity.config.ts'
+}
+
+function findFeedsFile(rootDir: string, themeSrcDir: string) {
+	for (const name of ['feeds.ts', 'feeds.mjs', 'feeds.js']) {
+		if (existsSync(resolve(rootDir, name))) {
+			return { found: true, resolved: resolve(rootDir, name) }
+		}
+	}
+	return { found: false, resolved: resolve(themeSrcDir, 'config/feeds.empty.ts') }
+}
+
+async function loadJson(path: string, jiti: ReturnType<typeof createJiti>) {
+	try {
 		return ((await jiti.import(path)) as { default?: Record<string, unknown> } | undefined)?.default
-	}
-	catch {
-		return undefined
-	}
-}
+	}
+	catch {
+		return undefined
+	}
+}

package/src/modules/clarity-source-layout/index.ts

@@ -0,0 +1,78 @@
+import type { Nuxt } from '@nuxt/schema'
+import { dirname, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineNuxtModule, getLayerDirectories } from 'nuxt/kit'
+
+const moduleDir = dirname(fileURLToPath(import.meta.url))
+const themeSrcDir = resolve(moduleDir, '../..')
+const themePkgDir = resolve(moduleDir, '../../..')
+
+/**
+ * Clarity keeps all runtime source under `src/`. These values must only apply
+ * to the theme layer; declaring them statically in `nuxt.config.ts` would let
+ * c12 merge them into consumers which do not explicitly override them.
+ */
+export default defineNuxtModule({
+	meta: {
+		name: 'clarity-source-layout',
+	},
+
+	setup(_options, nuxt) {
+		const layer = findThemeLayer(nuxt)
+		if (!layer) {
+			return
+		}
+
+		const sourceDir = withTrailingSlash(themeSrcDir)
+		const directories = {
+			layouts: withTrailingSlash(resolve(themeSrcDir, 'layouts')),
+			middleware: withTrailingSlash(resolve(themeSrcDir, 'middleware')),
+			modules: withTrailingSlash(resolve(themeSrcDir, 'modules')),
+			pages: withTrailingSlash(resolve(themeSrcDir, 'pages')),
+			plugins: withTrailingSlash(resolve(themeSrcDir, 'plugins')),
+			public: withTrailingSlash(resolve(themeSrcDir, 'public')),
+			server: withTrailingSlash(resolve(themeSrcDir, 'server')),
+			shared: withTrailingSlash(resolve(themeSrcDir, 'shared')),
+		}
+
+		layer.config.srcDir = sourceDir
+		layer.config.serverDir = directories.server
+		layer.config.dir = {
+			...layer.config.dir,
+			app: sourceDir,
+			modules: directories.modules,
+			public: directories.public,
+			shared: directories.shared,
+		}
+
+		// `getLayerDirectories()` caches a plain metadata object per layer before
+		// modules are installed. Nuxt exposes no invalidation API, so update the
+		// cached paths in place as well as `layer.config`.
+		const cached = getLayerDirectories(nuxt).find(directory => isSamePath(directory.root, themePkgDir))
+		if (cached) {
+			Object.assign(cached, {
+				app: sourceDir,
+				appLayouts: directories.layouts,
+				appMiddleware: directories.middleware,
+				appPages: directories.pages,
+				appPlugins: directories.plugins,
+				modules: directories.modules,
+				public: directories.public,
+				server: directories.server,
+				shared: directories.shared,
+			})
+		}
+	},
+})
+
+function findThemeLayer(nuxt: Nuxt) {
+	return nuxt.options._layers.find(layer => isSamePath(layer.config.rootDir ?? layer.cwd, themePkgDir))
+}
+
+function isSamePath(left: string, right: string) {
+	return left === right || relative(resolve(left), resolve(right)) === ''
+}
+
+function withTrailingSlash(path: string) {
+	return `${path.replace(/[\\/]$/, '').replaceAll('\\', '/')}/`
+}

package/{app → src}/pages/[...slug].vue

@@ -1,59 +1,59 @@
-<script setup lang="ts">
-const route = useRoute()
-
-const { data: post } = await useAsyncData(
-	`content:${route.path}`,
-	() => queryCollection('content').path(route.path).first(),
-)
-
-const excerpt = computed(() => post.value?.description || '')
-const asideWidgetNames = computed<WidgetName[]>(() => {
-	if (!post.value)
-		return ['blog-log']
-	return (post.value.meta?.aside as WidgetName[] | undefined) ?? ['toc']
-})
-const { widgets } = useWidgets(asideWidgetNames)
-
-if (post.value) {
-	useSeoMeta({
-		title: post.value.title,
-		ogType: 'article',
-		ogImage: post.value.image,
-		description: post.value.description,
-	})
-}
-else {
-	const event = useRequestEvent()
-	event && setResponseStatus(event, 404)
-	route.meta.title = '404'
-}
-</script>
-
-<template>
-<template #aside>
-	<!-- 更换页面时相同 key 的组件不会更新 -->
-	<component :is="widget.comp" v-for="widget in widgets" :key="widget.name" />
-</template>
-
-<template v-if="post">
-	<PostHeader v-bind="post" />
-	<PostExcerpt v-if="excerpt" :excerpt />
-	<!-- 使用 float-in 动画会导致搜索跳转不准确 -->
-	<ContentRenderer
-		class="article"
-		:class="getPostTypeClassName(post?.type, { prefix: 'md' })"
-		:value="post"
-		tag="article"
-	/>
-
-	<PostFooter v-bind="post" />
-	<PostSurround />
-	<PostComment />
-</template>
-
-<ZError
-	v-else
-	icon="line-md:document-delete-twotone"
-	title="内容为空或页面不存在"
-/>
-</template>
+<script setup lang="ts">
+const route = useRoute()
+
+const { data: post } = await useAsyncData(
+	`content:${route.path}`,
+	() => queryCollection('content').path(route.path).first(),
+)
+
+const excerpt = computed(() => post.value?.description || '')
+const asideWidgetNames = computed<WidgetName[]>(() => {
+	if (!post.value)
+		return ['blog-log']
+	return (post.value.meta?.aside as WidgetName[] | undefined) ?? ['toc']
+})
+const { widgets } = useWidgets(asideWidgetNames)
+
+if (post.value) {
+	useSeoMeta({
+		title: post.value.title,
+		ogType: 'article',
+		ogImage: post.value.image,
+		description: post.value.description,
+	})
+}
+else {
+	const event = useRequestEvent()
+	event && setResponseStatus(event, 404)
+	route.meta.title = '404'
+}
+</script>
+
+<template>
+<template #aside>
+	<!-- 更换页面时相同 key 的组件不会更新 -->
+	<component :is="widget.comp" v-for="widget in widgets" :key="widget.name" />
+</template>
+
+<template v-if="post">
+	<PostHeader v-bind="post" />
+	<PostExcerpt v-if="excerpt" :excerpt />
+	<!-- 使用 float-in 动画会导致搜索跳转不准确 -->
+	<ContentRenderer
+		class="article"
+		:class="getPostTypeClassName(post?.type, { prefix: 'md' })"
+		:value="post"
+		tag="article"
+	/>
+
+	<PostFooter v-bind="post" />
+	<PostSurround />
+	<PostComment />
+</template>
+
+<ZError
+	v-else
+	icon="line-md:document-delete-twotone"
+	title="内容为空或页面不存在"
+/>
+</template>