clarity-theme 0.1.1 → 0.1.2

package/README.md

@@ -245,6 +245,57 @@ All documents are also available in 简体中文 as sibling `*.zh-CN.md` files.
 | [Changelog](./CHANGELOG.md) | Consumer-facing release history |
 | [Extraction history](./docs/history/2026-09-layer-extraction.md) | Historical phases and one-time differential validation |
 
+## Repository Layout
+
+The repository root is the engineering layer; all Theme runtime source lives
+under `src/`:
+
+```
+clarity-theme/
+├─ src/                  # Theme runtime source (Layer srcDir)
+│  ├─ assets/ components/ composables/ layouts/ middleware/
+│  ├─ pages/ plugins/ stores/ types/ utils/
+│  ├─ app.config.ts app.vue error.vue shiki.config.ts
+│  ├─ config/            # config API sources (npm ./config ./content ./schema)
+│  ├─ img/               # img API sources (npm ./img)
+│  ├─ modules/           # source-layout bootstrap + clarity-config modules
+│  ├─ public/ server/ shared/ remark-plugins/
+├─ skills/               # Agent workflow skills (not part of the npm package)
+├─ docs/                 # Human documentation
+├─ playground/           # Workspace-linked development consumer
+├─ scripts/  tests/      # Verification and tooling
+└─ nuxt.config.ts, package.json, sync-manifest.json, …
+```
+
+`nuxt.config.ts` stays at the package root. Its first module,
+`src/modules/clarity-source-layout`, applies the `src/` directory metadata to
+the Clarity layer only; static `srcDir`/`serverDir`/`dir.*` values are not
+used because c12 would merge them into consumer root config. npm, Git-commit,
+and local-directory installs therefore resolve the same layout without
+overriding a consumer's own application directories.
+
+The npm package, the Agent skill, and the docs are three separate concerns:
+
+- **`clarity-theme` (npm package)** — the runtime Nuxt Layer installed with
+  `extends: ['clarity-theme']`. Its `files` field ships only `src/` plus the
+  root entry files; dev assets never enter the tarball.
+- **`skills/migrate-blog-v3-to-clarity`** — the canonical Agent workflow for
+  migrating an existing blog-v3 project. It is versioned with the repository
+  but intentionally **not** bundled into the npm package.
+- **`docs/`** — human-readable documentation mirrored in English and Chinese.
+
+### Installing the migration skill
+
+```bash
+npx skills add iicemeta/clarity-theme --list   # discover available skills
+npx skills add iicemeta/clarity-theme --skill migrate-blog-v3-to-clarity
+```
+
+For development, `npx skills add ./skills --list` discovers the local copy.
+To migrate a blog-v3 site with an Agent, ask it to use the
+`migrate-blog-v3-to-clarity` skill; the human walkthrough remains
+[Migration](./docs/MIGRATION.md).
+
 ## Development
 
 ```bash
@@ -260,6 +311,7 @@ pnpm test:migration
 pnpm test:contract
 pnpm test:consumer
 pnpm test:compatibility
+pnpm pack --dry-run       # inspect the npm tarball without writing it
 ```
 
 CI derives Node and pnpm versions from package metadata. It runs lint/typecheck/verify/sync/migration/contract/peers on the fixed Node matrix, then playground generate, real consumer acceptance, and rendering compatibility on the primary Node version. A separate weekly workflow only detects and reports upstream drift.
@@ -281,7 +333,7 @@ The weekly workflow only detects and reports drift. It never applies, commits, o
 
 ## Release Status
 
-Clarity Theme is a **v0.1.1 gated npm release**. The Layer/package boundary, validated configuration, Content factory, rendering pipeline, server outputs, playground, real-consumer acceptance, compatibility matrix, three-layer CI, upstream-sync baseline, release gate, and OIDC publish workflow are implemented. See the [release checklist](./docs/RELEASE-CHECKLIST.md) for the exact remaining manual publication steps.
+Clarity Theme is a **v0.1.2 gated npm release**. The Layer/package boundary, validated configuration, Content factory, rendering pipeline, server outputs, playground, real-consumer acceptance, compatibility matrix, three-layer CI, upstream-sync baseline, release gate, and OIDC publish workflow are implemented. See the [release checklist](./docs/RELEASE-CHECKLIST.md) for the exact remaining manual publication steps.
 
 The v0.1.0 correctness gates from [Roadmap](./docs/ROADMAP.md) are resolved: server/client configuration is split, feature-off routes return 404 at runtime, anti-mirror navigation is verified in a real browser, the no-op random-permalink field is removed, and multi-pattern stats are covered by a regression test. Remaining deferred items are recorded in the roadmap and release notes.
 

package/README.zh-CN.md

@@ -266,6 +266,54 @@ UI 分组、同路径组件覆盖、CSS 覆盖、服务端/路由自定义与 Sh
 | [更新日志](./CHANGELOG.md) | 面向使用者的发布历史 |
 | [抽取历史](./docs/history/2026-09-layer-extraction.zh-CN.md) | 历史阶段与一次性差分验证 |
 
+## 仓库结构
+
+仓库根目录是工程管理层；Theme 的全部运行时源码统一放在 `src/`：
+
+```
+clarity-theme/
+├─ src/                  # Theme 运行时源码（Layer srcDir）
+│  ├─ assets/ components/ composables/ layouts/ middleware/
+│  ├─ pages/ plugins/ stores/ types/ utils/
+│  ├─ app.config.ts app.vue error.vue shiki.config.ts
+│  ├─ config/            # config API 源码（npm ./config ./content ./schema）
+│  ├─ img/               # img API 源码（npm ./img）
+│  ├─ modules/           # source-layout 引导模块 + clarity-config 模块
+│  ├─ public/ server/ shared/ remark-plugins/
+├─ skills/               # Agent 工作流 Skill（不进入 npm 包）
+├─ docs/                 # 人工文档
+├─ playground/           # workspace 链接的开发用消费项目
+├─ scripts/  tests/      # 验证与工具脚本
+└─ nuxt.config.ts、package.json、sync-manifest.json、…
+```
+
+`nuxt.config.ts` 保留在包根目录。它最先加载的
+`src/modules/clarity-source-layout` 只为 Clarity 自身 layer 应用 `src/`
+目录元数据；不静态声明 `srcDir`/`serverDir`/`dir.*`，是因为 c12 会把它们
+合并进未显式覆盖这些键的 consumer root 配置。因此 npm 安装、Git commit
+安装与本地目录安装解析到同一份布局，同时不会覆盖 consumer 自己的
+应用目录。
+
+npm 包、Agent Skill 与文档三者职责分离：
+
+- **`clarity-theme`（npm 包）** — 运行时 Nuxt Layer，通过
+  `extends: ['clarity-theme']` 使用。`files` 只发布 `src/` 与根入口文件，
+  开发资产不会进入 tarball。
+- **`skills/migrate-blog-v3-to-clarity`** — 迁移既有 blog-v3 项目的
+  Agent 工作流 Skill。它与仓库一起版本化，但**刻意不**打进 npm 包。
+- **`docs/`** — 中英双语的人工文档。
+
+### 安装迁移 Skill
+
+```bash
+npx skills add iicemeta/clarity-theme --list   # 发现可用 Skill
+npx skills add iicemeta/clarity-theme --skill migrate-blog-v3-to-clarity
+```
+
+开发环境可用 `npx skills add ./skills --list` 发现本地副本。让 Agent 迁移
+blog-v3 站点时，请让它使用 `migrate-blog-v3-to-clarity` Skill；人工流程
+见[迁移指南](./docs/MIGRATION.zh-CN.md)。
+
 ## 开发
 
 ```bash
@@ -281,6 +329,7 @@ pnpm test:migration
 pnpm test:contract
 pnpm test:consumer
 pnpm test:compatibility
+pnpm pack --dry-run       # 不落盘检查 npm tarball
 ```
 
 CI 从包元数据推导 Node 与 pnpm 版本。它先在固定的 Node 矩阵上运行 lint/typecheck/verify/sync/migration/contract/peers，再在主 Node 版本上运行 playground 生成、真实消费者验收与渲染兼容性。另有一个每周工作流只检测并报告上游漂移。
@@ -302,7 +351,7 @@ pnpm sync:verify  # 重新运行主题纯度与基线检查
 
 ## 发布状态
 
-Clarity Theme 是一个 **v0.1.1 门禁 npm 发布版本**。Layer/包边界、已校验配置、Content 工厂、渲染管线、服务端输出、playground、真实消费者验收、兼容性矩阵、三层 CI、上游同步基线、发布门禁与 OIDC 发布工作流均已实现。剩余的人工发布步骤见[发布检查清单](./docs/RELEASE-CHECKLIST.zh-CN.md)。
+Clarity Theme 是一个 **v0.1.2 门禁 npm 发布版本**。Layer/包边界、已校验配置、Content 工厂、渲染管线、服务端输出、playground、真实消费者验收、兼容性矩阵、三层 CI、上游同步基线、发布门禁与 OIDC 发布工作流均已实现。剩余的人工发布步骤见[发布检查清单](./docs/RELEASE-CHECKLIST.zh-CN.md)。
 
 [路线图](./docs/ROADMAP.zh-CN.md)中的 v0.1.0 正确性门禁已解决：服务端/客户端配置已拆分、功能关闭路由在运行时返回 404、反镜像导航已在真实浏览器中验证、no-op 随机固定链接字段已移除，多模式统计已增加回归测试。其余推迟事项记录在路线图与发布说明中。
 

package/nuxt.config.ts

@@ -12,13 +12,13 @@ const toThemePath = (path: string) => join(themeDir, path).replaceAll('\\', '/')
 function pluginPath(path: string) {
 	// 插件必须是 .mjs：@nuxt/content 以 Node 原生方式加载，
 	// 不允许 node_modules 内的 TS 文件（TS 剥离限制）
-	return pathToFileURL(join(themeDir, 'remark-plugins', `${path}.mjs`)).href
+	return pathToFileURL(join(themeDir, 'src', 'remark-plugins', `${path}.mjs`)).href
 }
 
 /**
  * Clarity Theme Layer 配置
  *
- * 站点数据（SEO、favicon、scripts 等）由 modules/clarity-config
+ * 站点数据（SEO、favicon、scripts 等）由 src/modules/clarity-config
  * 读取消费项目的 clarity.config.ts 后统一注入，此处仅包含 Theme 自身能力。
  */
 export default defineNuxtConfig({
@@ -50,18 +50,18 @@ export default defineNuxtConfig({
 	compatibilityDate: '2024-08-03',
 
 	components: [
-		{ path: toThemePath('app/components/partial'), prefix: 'Z' },
-		toThemePath('app/components'),
+		{ path: toThemePath('src/components/partial'), prefix: 'Z' },
+		toThemePath('src/components'),
 	],
 
 	// @keep-sorted
 	css: [
-		toThemePath('app/assets/css/animation.scss'),
-		toThemePath('app/assets/css/article.scss'),
-		toThemePath('app/assets/css/color.scss'),
-		toThemePath('app/assets/css/font.scss'),
-		toThemePath('app/assets/css/main.scss'),
-		toThemePath('app/assets/css/reusable.scss'),
+		toThemePath('src/assets/css/animation.scss'),
+		toThemePath('src/assets/css/article.scss'),
+		toThemePath('src/assets/css/color.scss'),
+		toThemePath('src/assets/css/font.scss'),
+		toThemePath('src/assets/css/main.scss'),
+		toThemePath('src/assets/css/reusable.scss'),
 	],
 
 	// @keep-sorted
@@ -72,6 +72,9 @@ export default defineNuxtConfig({
 
 	// @keep-sorted
 	modules: [
+		// 必须最先运行：把 src/ 仅应用到 Clarity 自身 layer，避免静态
+		// srcDir / serverDir / dir.* 经 c12 合并泄漏到 consumer root 配置。
+		toThemePath('src/modules/clarity-source-layout'),
 		'@bikariya/image-viewer',
 		'@bikariya/modals',
 		'@bikariya/shiki',
@@ -84,7 +87,7 @@ export default defineNuxtConfig({
 		'@vueuse/nuxt',
 		// Layer 配置中的相对 module 路径会以消费项目为基准解析，必须使用绝对路径；
 		// 且 clarity-config 必须先于 nuxt-llms 运行：后者在 setup 时读取注入的 llms 站点配置
-		toThemePath('modules/clarity-config'),
+		toThemePath('src/modules/clarity-config'),
 		'nuxt-llms',
 	],
 
@@ -112,8 +115,8 @@ export default defineNuxtConfig({
 		nodeTsConfig: {
 			// @keep-sorted
 			include: [
-				'../config/**/*.ts',
-				'../remark-plugins/**/*.ts',
+				'../src/config/**/*.ts',
+				'../src/remark-plugins/**/*.ts',
 			],
 		},
 	},
@@ -122,7 +125,7 @@ export default defineNuxtConfig({
 		css: {
 			preprocessorOptions: {
 				scss: {
-					additionalData: `@use "${toThemePath('app/assets/css/_variable.scss')}" as *;`,
+					additionalData: `@use "${toThemePath('src/assets/css/_variable.scss')}" as *;`,
 				},
 			},
 		},
@@ -189,7 +192,7 @@ ${homepage}
 
 	icon: {
 		customCollections: [
-			{ prefix: 'clarity', dir: toThemePath('app/assets/icons') },
+			{ prefix: 'clarity', dir: toThemePath('src/assets/icons') },
 		],
 		clientBundle: {
 			scan: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clarity-theme",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Clarity Theme — 从 blog-v3 提取的可复用 Nuxt 4 Layer 博客主题",
   "license": "MIT",
   "publishConfig": {
@@ -18,36 +18,29 @@
   "exports": {
     ".": "./nuxt.config.ts",
     "./config": {
-      "types": "./config/index.d.mts",
-      "default": "./config/index.mjs"
+      "types": "./src/config/index.d.mts",
+      "default": "./src/config/index.mjs"
     },
     "./content": {
-      "types": "./config/content.d.mts",
-      "default": "./config/content.mjs"
+      "types": "./src/config/content.d.mts",
+      "default": "./src/config/content.mjs"
     },
     "./img": {
-      "types": "./img/index.d.mts",
-      "default": "./img/index.mjs"
+      "types": "./src/img/index.d.mts",
+      "default": "./src/img/index.mjs"
     },
     "./schema": {
-      "types": "./config/schema.d.mts",
-      "default": "./config/schema.mjs"
+      "types": "./src/config/schema.d.mts",
+      "default": "./src/config/schema.mjs"
     }
   },
   "main": "./nuxt.config.ts",
   "files": [
     "LICENSE",
     "README.md",
-    "app",
-    "config",
-    "img",
-    "modules",
     "nuxt.config.ts",
     "package.json",
-    "public",
-    "remark-plugins",
-    "server",
-    "shared"
+    "src"
   ],
   "engines": {
     "node": "^22.19 || ^24.11 || >=26"
@@ -112,6 +105,7 @@
     "@nuxt/hints": "^1.1.4",
     "@stylistic/stylelint-plugin": "^5.2.1",
     "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
     "@zinkawaii/stylelint-config": "^0.5.2",
     "cspell": "^10.2.2",
     "eslint": "^10.10.0",
@@ -132,8 +126,8 @@
     "dev": "pnpm --dir playground dev",
     "build": "pnpm --dir playground build",
     "generate": "pnpm --dir playground generate",
-    "lint": "eslint && stylelint \"app/**/*.{vue,scss}\" \"playground/app/**/*.vue\"",
-    "lint:fix": "eslint --fix && stylelint \"app/**/*.{vue,scss}\" \"playground/app/**/*.vue\" --fix",
+    "lint": "eslint && stylelint \"src/**/*.{vue,scss}\" \"playground/app/**/*.vue\"",
+    "lint:fix": "eslint --fix && stylelint \"src/**/*.{vue,scss}\" \"playground/app/**/*.vue\" --fix",
     "typecheck": "pnpm --dir playground typecheck",
     "verify": "node scripts/verify-theme.mjs",
     "test:sync": "node --test tests/sync-upstream.test.mjs",

package/{app → src}/app.config.ts

@@ -2,7 +2,7 @@
  * Clarity Theme UI 默认配置。
  *
  * 站点数据（标题、作者、文章分类等）来自根目录 clarity.config.ts，
- * 由 modules/clarity-config 注入到 appConfig.clarity 中。
+ * 由 src/modules/clarity-config 注入到 appConfig.clarity 中。
  *
  * 消费项目可在自己的 app/app.config.ts 中按需覆盖任意键。
  */

package/{app → src}/composables/useArticle.ts

@@ -1,5 +1,5 @@
-import type { MetaSlotsTree } from '../../remark-plugins/rehype-meta-slots'
-import type { ClarityContentRow } from '../../shared/types/content'
+import type { MetaSlotsTree } from '../remark-plugins/rehype-meta-slots'
+import type { ClarityContentRow } from '../shared/types/content'
 import type { ArticleOrderType, ArticleProps } from '../types/article'
 import { orderBy } from 'es-toolkit/array'
 

package/{config → src/config}/app.ts

@@ -1,4 +1,4 @@
-import type { NavItem } from '../app/types/nav'
+import type { NavItem } from '../types/nav'
 import type { ClarityPublicConfig } from './public'
 
 export interface NavGroup {

package/{config → src/config}/feeds.empty.ts

@@ -1,4 +1,4 @@
-import type { FeedGroup } from '../app/types/feed'
+import type { FeedGroup } from '../types/feed'
 
 /** 消费项目未提供 feeds.ts 时的空数据兜底 */
 const emptyFeeds: FeedGroup[] = []

package/{config → src/config}/index.ts

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

package/{img → src/img}/index.ts

@@ -1,8 +1,8 @@
 /**
  * `clarity-theme/img` 类型真源。
  *
- * 类型实现复用 `app/utils/img.ts`（Layer 内部与包导出共享同一份签名），
+ * 类型实现复用 `src/utils/img.ts`（Layer 内部与包导出共享同一份签名），
  * 运行时实现在同目录 index.mjs：Node 原生 TS 剥离不允许
  * node_modules 内的 TS 文件，因此包入口运行时必须是 .mjs。
  */
-export * from '../app/utils/img'
+export * from '../utils/img'

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

@@ -21,7 +21,10 @@ import { toServerClarityConfig } from '../../config/server'
 import handleMirror from './anti-mirror-client'
 
 const moduleDir = dirname(fileURLToPath(import.meta.url))
-const themeDir = resolve(moduleDir, '../..')
+/** 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'])
@@ -42,7 +45,7 @@ export default defineNuxtModule<ModuleOptions>({
 		const rootDir = nuxt.options.rootDir
 
 		const configPath = resolve(rootDir, options.configFile ?? findConfigFile(rootDir))
-		const feedsPath = findFeedsFile(rootDir, themeDir)
+		const feedsPath = findFeedsFile(rootDir, themeSrcDir)
 
 		// ---- 依赖注入层：Theme 内部不感知消费项目的文件布局 ----
 		Object.assign(nuxt.options.alias, {
@@ -51,14 +54,14 @@ export default defineNuxtModule<ModuleOptions>({
 		})
 
 		// @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: () => [
@@ -86,7 +89,7 @@ export default defineNuxtModule<ModuleOptions>({
 		// 需置于 '~' 之前以保证 Vite 别名前缀优先匹配
 		if (!existsSync(resolve(nuxt.options.srcDir, 'shiki.config.ts'))) {
 			nuxt.options.alias = {
-				'~/shiki.config': resolve(themeDir, 'app/shiki.config.ts'),
+				'~/shiki.config': resolve(themeSrcDir, 'shiki.config.ts'),
 				...nuxt.options.alias,
 			}
 		}
@@ -176,7 +179,7 @@ export default defineNuxtModule<ModuleOptions>({
 
 		// ---- 构建信息（供 BlogTech 等 Widget 使用） ----
 		const consumerPkg = await loadJson(resolve(rootDir, 'package.json'), jiti)
-		const themePkg = await loadJson(resolve(themeDir, 'package.json'), jiti)
+		const themePkg = await loadJson(resolve(themePkgDir, 'package.json'), jiti)
 		nuxt.options.runtimeConfig.public.clarity = {
 			theme: 'Clarity',
 			themeVersion: String(themePkg?.version ?? ''),
@@ -308,13 +311,13 @@ function findConfigFile(rootDir: string) {
 	return 'clarity.config.ts'
 }
 
-function findFeedsFile(rootDir: string, themeDir: string) {
+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(themeDir, 'config/feeds.empty.ts') }
+	return { found: false, resolved: resolve(themeSrcDir, 'config/feeds.empty.ts') }
 }
 
 async function loadJson(path: string, jiti: ReturnType<typeof createJiti>) {

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/{server → src/server}/routes/subscriptions.opml.get.ts

@@ -1,4 +1,4 @@
-import type { FeedEntry, FeedGroup } from '../../app/types/feed'
+import type { FeedEntry, FeedGroup } from '../../types/feed'
 import XmlBuilder from 'fast-xml-builder'
 import { toZonedTemporal } from '../../shared/utils/time'
 

package/{app → src}/types/article.ts

@@ -1,6 +1,6 @@
-import type { ClarityAppConfig } from '../../config/app'
-import type { ArticleSchema } from '../../config/content'
-import type { MetaSlotsTree } from '../../remark-plugins/rehype-meta-slots'
+import type { ClarityAppConfig } from '../config/app'
+import type { ArticleSchema } from '../config/content'
+import type { MetaSlotsTree } from '../remark-plugins/rehype-meta-slots'
 
 export type ArticleOrderType = keyof ClarityAppConfig['article']['order']
 

package/src/types/feed.ts

@@ -0,0 +1 @@
+export type { FeedEntry, FeedGroup } from '../config/feed'

package/app/types/feed.ts

@@ -1 +0,0 @@
-export type { FeedEntry, FeedGroup } from '../../config/feed'