skinsuite 0.2.0 → 0.2.2

package/README.md

@@ -288,6 +288,22 @@ npm test            # 先构建，再用 node:test 跑 dist 产物
 
 ⚠️ `src/` 里的相对 import **必须带 `.js` 后缀**：包以 `moduleResolution: NodeNext` 编译，TS 会把 `.js` 映射回 `.ts` 源码，而产物里的相对说明符是原样保留的 —— 不带后缀浏览器与 Node 的原生 ESM 都解析不到。
 
+### 关于 exports：类型统一指向 `src/`，运行时才分 `dist/`
+
+```jsonc
+".":      { "types": "./src/index.ts", "import": "./dist/index.js" },
+"./vue":  { "types": "./src/vue/index.ts", "import": "./src/vue/index.ts" },
+"./vite": { "types": "./src/vite/index.ts", "import": "./src/vite/index.ts" }
+```
+
+`./vue` / `./vite` 含 `.vue` 与构建期代码，**只能以源码形态发布**（`tsc` 编不出 SFC）。
+于是根入口的类型也必须指向 `src/index.ts`：若它指向 `dist/index.d.ts`，同一个类型在
+一个程序里会有**两个身份**（dist 的 d.ts 与 vue 层引用的 src），composite 项目做声明
+产出时直接红 —— `TS2883: The inferred type of 'X' cannot be named without a reference
+to '...' from '../../node_modules/skinsuite/src/types'`。
+
+`dist/` 仍然保留（`.js` + `.d.ts` + sourcemap），运行时走它，纯 JS 消费者不受影响。
+
 ---
 
 ## License

package/dist/vite/dir.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 缺省主题根目录（相对宿主工程根）
+ *
+ * 留这个默认值是为了 **CI 与独立克隆**：`.env` 通常被 gitignore，全新 checkout 里
+ * 没有它，此时必须仍能构建 —— 否则"没配 env 就构建失败"会把部署门槛抬高。
+ * 宿主可通过 `resolveThemeDir(mode, root, { defaultDir })` 覆盖。
+ */
+export declare const DEFAULT_THEME_DIR = "src/theme";
+/** 主题根目录内、主题包的子目录名（固定约定，宿主 `views/*.ts` 的字面量 glob 依赖它稳定） */
+export declare const THEME_PACKAGES_SUBDIR = "themes";
+/** 主题根目录内的版式契约目录名（`views/*.ts`，设备声明 + 页面契约，插件副作用 import 拉齐） */
+export declare const THEME_VIEWS_SUBDIR = "views";
+/** 主题根目录内的清单文件名（插件按它找 `theme.config.ts`） */
+export declare const DEFAULT_THEME_MANIFEST = "theme.config.ts";
+/**
+ * 解析主题**根目录**为**绝对路径**
+ *
+ * @param mode  Vite 的 mode（development / production / test …），决定叠加哪个 `.env.<mode>`
+ * @param root  以哪个目录为工程根找 `.env`，缺省 `process.cwd()`
+ * @param opts  可选覆盖：`defaultDir` 缺省回落目录、`envKey` 环境变量名
+ */
+export declare function resolveThemeDir(mode: string, root?: string, opts?: {
+    defaultDir?: string;
+    envKey?: string;
+}): string;
+//# sourceMappingURL=dir.d.ts.map

package/dist/vite/dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dir.d.ts","sourceRoot":"","sources":["../../src/vite/dir.ts"],"names":[],"mappings":"AAgDA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAE9C,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C,4CAA4C;AAC5C,eAAO,MAAM,sBAAsB,oBAAoB,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAsB,EAC5B,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,MAAM,CAOR"}

package/dist/vite/dir.js

@@ -0,0 +1,77 @@
+/**
+ * 主题**根目录**的解析入口（构建期，随 `skinsuite/vite` 一起发布）
+ *
+ * 属于主题库自带的构建能力：任何宿主（Vue / React / 任意 Vite 工程）引入
+ * `skinsuite` 后，只要在 `vite.config.ts` 挂上 `themeAssets()` 插件、并把目录解析
+ * 交给本文件的 `resolveThemeDir()`，就**不再需要自己写一行扫描/目录代码**。
+ *
+ * === 为什么走 env 而不是一份 TS 配置文件 ===
+ * 目录是**部署事实**（可能整包换掉一套品牌主题、可能放在 monorepo 的另一处），
+ * 写进源码就意味着换目录要改代码 + 重新 review。env 是"同一份产物服务多个部署"
+ * 的既有通道，目录也走同一条：
+ *
+ *   ```
+ *   VITE_THEME_DIR=src/theme          # 相对宿主工程根；主题**根目录**
+ *   ```
+ *
+ * === `VITE_THEME_DIR` 指向的是「主题根目录」，不是「主题包目录」===
+ * 根目录内是**三个固定子目录/文件**（约定俗成、名字固定，换根目录位置时整包跟着走）：
+ *
+ *   ```
+ *   <根目录>/                          ← VITE_THEME_DIR（如 src/theme）
+ *   ├── theme.config.ts               清单：调试开关（契约 = defineThemeManifest）
+ *   ├── themes/                       主题包目录（一个包 = 一种版式）
+ *   │   ├── default/  ├── compact/
+ *   └── views/                        声明目录（devices.ts 设备声明 + login.ts 等页面契约）
+ *   ```
+ *
+ * 于是「主题域」是**一个自足目录**：换根目录位置时，主题包、清单、声明一起走，
+ * 宿主要改的只有 `VITE_THEME_DIR` 这一个变量。
+ *
+ * ⚠️ `themes` 与 `views` 是**固定子目录名**（不是可配置项）：构建插件扫包目录与
+ *    声明目录都认这两个名字 —— 靠「名字固定」对齐，不靠配置。
+ *
+ * 而**主题域自己的策略**（调试开关、路由投影）不在这里 —— 那份配置跟着主题域走，
+ * 住在根目录的 `theme.config.ts`（契约见 `skinsuite` 的 `defineThemeManifest`）。
+ * 分工是「宿主说根目录在哪」/「主题域说自己怎么用」，不是同一类东西。
+ *
+ * ⚠️ 必须用 `loadEnv()` 读，不能直接 `process.env.VITE_THEME_DIR`：
+ *    vite.config 执行时 Vite 还没加载 `.env` 文件（那只在 config 解析后发生），
+ *    直接读 `process.env` 在 `npm run dev` 下恒 undefined —— 于是永远回落默认值，
+ *    看着能用、改 env 却不生效，属于最难发现的一类。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17
+ */
+import path from 'node:path';
+import { loadEnv } from 'vite';
+/**
+ * 缺省主题根目录（相对宿主工程根）
+ *
+ * 留这个默认值是为了 **CI 与独立克隆**：`.env` 通常被 gitignore，全新 checkout 里
+ * 没有它，此时必须仍能构建 —— 否则"没配 env 就构建失败"会把部署门槛抬高。
+ * 宿主可通过 `resolveThemeDir(mode, root, { defaultDir })` 覆盖。
+ */
+export const DEFAULT_THEME_DIR = 'src/theme';
+/** 主题根目录内、主题包的子目录名（固定约定，宿主 `views/*.ts` 的字面量 glob 依赖它稳定） */
+export const THEME_PACKAGES_SUBDIR = 'themes';
+/** 主题根目录内的版式契约目录名（`views/*.ts`，设备声明 + 页面契约，插件副作用 import 拉齐） */
+export const THEME_VIEWS_SUBDIR = 'views';
+/** 主题根目录内的清单文件名（插件按它找 `theme.config.ts`） */
+export const DEFAULT_THEME_MANIFEST = 'theme.config.ts';
+/**
+ * 解析主题**根目录**为**绝对路径**
+ *
+ * @param mode  Vite 的 mode（development / production / test …），决定叠加哪个 `.env.<mode>`
+ * @param root  以哪个目录为工程根找 `.env`，缺省 `process.cwd()`
+ * @param opts  可选覆盖：`defaultDir` 缺省回落目录、`envKey` 环境变量名
+ */
+export function resolveThemeDir(mode, root = process.cwd(), opts = {}) {
+    const envKey = opts.envKey ?? 'VITE_THEME_DIR';
+    const defaultDir = opts.defaultDir ?? DEFAULT_THEME_DIR;
+    // 第三个参数是前缀白名单：只读 VITE_ 开头的，避免把后端密钥之类带进来
+    const env = loadEnv(mode, root, 'VITE_');
+    const configured = (env[envKey] ?? '').trim();
+    return path.resolve(root, configured || defaultDir);
+}
+//# sourceMappingURL=dir.js.map

package/dist/vite/dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dir.js","sourceRoot":"","sources":["../../src/vite/dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE7C,4DAA4D;AAC5D,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAQ,CAAC;AAE9C,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C,4CAA4C;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,OAAe,OAAO,CAAC,GAAG,EAAE,EAC5B,OAAiD,EAAE;IAEnD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,gBAAgB,CAAC;IAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC;IACxD,wCAAwC;IACxC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,IAAI,UAAU,CAAC,CAAC;AACtD,CAAC"}

package/dist/vite/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `skinsuite/vite` —— 主题库的**构建期适配器**（Vite 插件 + 目录解析）
+ *
+ * 纯内核（`skinsuite`）与 Vue 绑定（`skinsuite/vue`）都刻意不碰构建器，因为
+ * "扫描主题目录"是 Vite 专属的能力（webpack 要写成 `require.context`）。这一半
+ * 收在这里，让宿主在 `vite.config.ts` 里三行接完，不必自己抄扫描逻辑：
+ *
+ * ```ts
+ * import { themeAssets, resolveThemeDir } from 'skinsuite/vite';
+ * export default defineConfig(({ mode }) => ({
+ *   plugins: [themeAssets({ dir: resolveThemeDir(mode) })]
+ * }));
+ * ```
+ *
+ * === 为什么这个子路径指向源码 `.ts` 而不是 `dist/` ===
+ * `vite.config.ts` 由 Vite 用 esbuild 预打包后执行，裸包说明符会被当外部依赖交给
+ * Node `import()`。若指向 `dist/`，就要求"包必须先构建" —— CI 里 `npm ci` 不会
+ * 构建工作区包，配置会直接起不来。Vite 自己能转译 TS，源码直供就绕开这个前提，
+ * 与 `skinsuite/vue` 同一手法。
+ *
+ * ⚠️ 本层相对 import **必须用显式 `.ts` 后缀**（`./plugin.ts` 而非 `./plugin` 或
+ *    `./plugin.js`）：
+ *    这个入口是**唯一在 vite.config / vitest.config 里被 import 的子路径**，config
+ *    被 Node 直接执行（Vite 的 config 加载器只 bundle config 自身），Node 既不自动补
+ *    无后缀、也不把 `.js` 映射到 `.ts` 源码。而纯内核（`./tone.js`）走 NodeNext 编译、
+ *    `skinsuite/vue` 走应用代码的 Vite 转译，两者都用不上这个入口的约束，所以这里
+ *    自成一套后缀规则。`.ts` 后缀由宿主的 `allowImportingTsExtensions` + Vite 转译共同消化。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17
+ */
+export { themeAssets } from './plugin.js';
+export type { ThemeAssetsPluginOptions } from './plugin.js';
+export { DEFAULT_THEME_DIR, THEME_PACKAGES_SUBDIR, DEFAULT_THEME_MANIFEST, resolveThemeDir } from './dir.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/vite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EAChB,MAAM,UAAU,CAAC"}

package/dist/vite/index.js

@@ -0,0 +1,35 @@
+/**
+ * `skinsuite/vite` —— 主题库的**构建期适配器**（Vite 插件 + 目录解析）
+ *
+ * 纯内核（`skinsuite`）与 Vue 绑定（`skinsuite/vue`）都刻意不碰构建器，因为
+ * "扫描主题目录"是 Vite 专属的能力（webpack 要写成 `require.context`）。这一半
+ * 收在这里，让宿主在 `vite.config.ts` 里三行接完，不必自己抄扫描逻辑：
+ *
+ * ```ts
+ * import { themeAssets, resolveThemeDir } from 'skinsuite/vite';
+ * export default defineConfig(({ mode }) => ({
+ *   plugins: [themeAssets({ dir: resolveThemeDir(mode) })]
+ * }));
+ * ```
+ *
+ * === 为什么这个子路径指向源码 `.ts` 而不是 `dist/` ===
+ * `vite.config.ts` 由 Vite 用 esbuild 预打包后执行，裸包说明符会被当外部依赖交给
+ * Node `import()`。若指向 `dist/`，就要求"包必须先构建" —— CI 里 `npm ci` 不会
+ * 构建工作区包，配置会直接起不来。Vite 自己能转译 TS，源码直供就绕开这个前提，
+ * 与 `skinsuite/vue` 同一手法。
+ *
+ * ⚠️ 本层相对 import **必须用显式 `.ts` 后缀**（`./plugin.ts` 而非 `./plugin` 或
+ *    `./plugin.js`）：
+ *    这个入口是**唯一在 vite.config / vitest.config 里被 import 的子路径**，config
+ *    被 Node 直接执行（Vite 的 config 加载器只 bundle config 自身），Node 既不自动补
+ *    无后缀、也不把 `.js` 映射到 `.ts` 源码。而纯内核（`./tone.js`）走 NodeNext 编译、
+ *    `skinsuite/vue` 走应用代码的 Vite 转译，两者都用不上这个入口的约束，所以这里
+ *    自成一套后缀规则。`.ts` 后缀由宿主的 `allowImportingTsExtensions` + Vite 转译共同消化。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17
+ */
+/// <reference path="./theme.d.ts" />
+export { themeAssets } from './plugin.js';
+export { DEFAULT_THEME_DIR, THEME_PACKAGES_SUBDIR, DEFAULT_THEME_MANIFEST, resolveThemeDir } from './dir.js';
+//# sourceMappingURL=index.js.map

package/dist/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qCAAqC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EAChB,MAAM,UAAU,CAAC"}

package/dist/vite/plugin.d.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from 'vite';
+export interface ThemeAssetsPluginOptions {
+    /** 主题**根目录**：相对 Vite root 或绝对路径（通常来自 `resolveThemeDir()`，已是绝对路径） */
+    dir: string;
+    /** 虚拟模块 id，缺省 `virtual:theme` */
+    moduleId?: string;
+    /** 清单文件名，缺省 `theme.config.ts`；设为空串则**不**注入清单 */
+    manifestFile?: string;
+}
+/**
+ * 主题域插件
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { themeAssets, resolveThemeDir } from 'skinsuite/vite';
+ *
+ * export default defineConfig(({ mode }) => ({
+ *   plugins: [themeAssets({ dir: resolveThemeDir(mode) })]
+ * }));
+ * ```
+ */
+export declare function themeAssets(options: ThemeAssetsPluginOptions): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/vite/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/vite/plugin.ts"],"names":[],"mappings":"AAgEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAcnC,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAuQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CA+CrE"}

package/dist/vite/plugin.js

@@ -0,0 +1,348 @@
+/**
+ * 主题域扫描插件 —— **主题库自带的 Vite 适配器**（随 `skinsuite/vite` 一起发布）
+ *
+ * 把 `VITE_THEME_DIR` 指向的**主题根目录**扫成一个虚拟模块 `virtual:theme`，它同时产出三样东西：
+ *
+ *   ① **资产**：主题包定义、配色元信息、配色附加样式（惰性）、版式组件加载表 `themeViews`
+ *   ② **清单**：根目录里那份 `theme.config.ts`（调试开关，见 `defineThemeManifest`）
+ *   ③ **声明**：`views/*.ts`（设备声明 + 页面契约）以副作用 import 拉齐注册
+ *
+ * 本模块被 import 的那一刻（模块求值期副作用）自动完成三件装配：
+ * `installThemeViews(themeViews)` + `installThemeRegistry(...)` + `installThemeManifest(...)`，
+ * 宿主**无需 import `virtual:theme` 再转发**，也无需手动 import 任何 `views/*.ts`。
+ *
+ * === 目录口径：`VITE_THEME_DIR` 是「主题根目录」，不是「主题包目录」===
+ * 根目录内固定三个名字（约定俗成，换根目录位置时整包跟着走）：
+ *   `theme.config.ts`  清单
+ *   `themes/`          主题包目录（本插件扫这里，出 packages/colors/styles/themeViews）
+ *   `views/`           声明目录（devices.ts 设备声明 + 页面契约，本插件副作用 import 拉齐注册）
+ * 所以本插件在 `dir` 下**再进一层 `themes/`** 扫包、再进一层 `views/` 拉声明，
+ * 清单则从 `dir` 根层读。
+ *
+ * === 为什么它放在库里（而非让每个宿主各写一份）===
+ * 它是主题机制的**构建期半边**：内核负责契约（`ThemeManifest`），
+ * 这里负责扫描。没有它，「主题目录是配置项」就只实现了一半 —— 每个宿主都得
+ * 自己抄一遍一百多行的扫描逻辑，正是"库不够强大"的典型症状。
+ *
+ * `vite.config.ts` 由 Vite 用 esbuild 预打包后执行，裸包说明符会被当外部依赖交给
+ * Node `import()`。因此本入口**刻意用 subpath export 指向源码 `.ts`**（而非 `dist/`），
+ * 与 `skinsuite/vue` 同一手法：Vite 自己能转译 TS，源码直供就绕开了
+ * "包必须先构建 dist 才能被 config 引用"的脆弱前提（CI 里 `npm ci` 不会构建工作区包）。
+ *
+ * === 它解决的问题 ===
+ * `import.meta.glob` 的模式必须是**字面量**（Vite 在编译期静态展开），所以
+ * 「主题目录放在哪」一旦写进 glob 就再也改不了 —— 想换目录只能改源码。
+ * 本插件把扫描搬到构建期（Node 侧 `fs`），用**虚拟模块**把结果喂给运行时，
+ * 于是目录路径变成 `VITE_THEME_DIR` 这一个环境变量。
+ *
+ * === 产出形态（资产部分与 `import.meta.glob` 的结果保持一致）===
+ * ```ts
+ * export const packages:   { './default/index.js': Module }
+ * export const colors:     { './default/mobile/login/colors/white/index.js': Module }
+ * export const styles:     { './default/mobile/login/colors/white/theme.scss': () => Promise<string> }
+ * export const themeViews: { 'login': { './default/mobile/login/index.vue': () => Module } }
+ * // 副作用：installThemeViews(themeViews) / installThemeRegistry(...) / installThemeManifest(...)
+ * ```
+ * 资产键**相对主题包目录**（`themes/`，`./` 开头），值保持「模块命名空间」而非默认导出 ——
+ * 这样宿主注册表代码一行都不用改（它按「包/设备/页面/配色」四段解析键）。`styles` 是
+ * **惰性**的（`?inline` 动态 import），背景图与字体不会进首屏包。
+ *
+ * === 为什么不用 codegen 落盘 ===
+ * 生成物入库有两个麻烦：`git status` 常脏、以及"忘了重新生成"导致的静默过期。
+ * 虚拟模块没有落盘产物，改一个目录下次请求就是新的。
+ *
+ * === 容错的边界 ===
+ * 目录不存在、包写坏、配色缺 `tone` —— 一律**跳过而不是报错**：一个写歪的目录不该
+ * 让整站起不来。目录口径的问题由宿主的关卡负责大喊。
+ * **唯独清单不跳过**：它一旦写错，`defineThemeManifest` 会在启动时直接抛，
+ * 因为「面板不出现」「路由推不出页面」这类症状根本无从归因。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { DEFAULT_THEME_PACKAGE, THEME_COLOR_DEF_FILE, THEME_COLOR_STYLE_FILE, THEME_COLORS_SEGMENT, THEME_DIR_LEVELS, THEME_PACKAGE_DEF_FILE } from '../constants.js';
+import { DEFAULT_THEME_MANIFEST, THEME_PACKAGES_SUBDIR, THEME_VIEWS_SUBDIR } from './dir.js';
+/** 版式组件的叶子文件名（`themes/<包>/<设备>/<页面>/index.vue`） */
+const VIEW_COMPONENT_FILE = 'index.vue';
+const DEFAULT_MODULE_ID = 'virtual:theme';
+/** 目录不存在 / 没有清单时的产出：空注册表 + 空清单（import 本模块即自动装配） */
+const EMPTY_MODULE = [
+    "import { installThemeRegistry, buildThemeRegistry, resolveThemeManifest, installThemeManifest } from 'skinsuite';",
+    "import { installThemeViews } from 'skinsuite/vue';",
+    'export const packages = {};',
+    'export const colors = {};',
+    'export const styles = {};',
+    'export const themeViews = {};',
+    'installThemeViews(themeViews);',
+    'installThemeRegistry(buildThemeRegistry({ packages, colors, styles }));',
+    'export const themeManifest = resolveThemeManifest(null);',
+    'installThemeManifest(themeManifest);'
+].join('\n');
+/** 是否为目录；不存在或不可读一律 false（扫描全程"读不到就跳过"） */
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function subdirs(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter(entry => entry.isDirectory())
+            .map(entry => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** 目录下的 `.ts` 文件（不含 `.d.ts`）；不存在或不可读返回空（读不到就跳过） */
+function tsFiles(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter(entry => entry.isFile() && entry.name.endsWith('.js') && !entry.name.endsWith('.d.js'))
+            .map(entry => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 扫描主题**包目录**（根目录下的 `themes/` 子目录）
+ *
+ * `dir` 是主题根目录（`VITE_THEME_DIR`），真正的包住在 `dir/themes/` 下 ——
+ * 这个子目录名固定，宿主 `views/*.ts` 的 `import.meta.glob` 字面量也认它，两边靠名字对齐。
+ *
+ * === 目录结构由内核契约驱动，而非手写嵌套 for（2026-10-17）===
+ * 「包 / 设备 / 页面 / colors / 配色」这五段里，`colors` 是**固定字面段**、其余四段
+ * 是**取值段**（取值由文件系统与宿主设备清单决定，本插件不认识具体值）。这段结构的
+ * 唯一来源是 `constants.ts` 的 `THEME_DIR_LEVELS`（取值目录段）+ `THEME_COLORS_SEGMENT`
+ * （固定字面段）+ `THEME_COLOR_DEF_FILE` / `THEME_COLOR_STYLE_FILE`（叶子文件）。
+ * 本函数用 `walk` 按 `THEME_DIR_LEVELS` 做**通用递归下降**——目录加一层、或 `colors`
+ * 改名，只动那一份契约，这里与注册表的 `colorFromKey()` 一起跟着变，不再有
+ * "扫得到但解析不出"或反之的静默脱节。
+ *
+ * 只认内核约定的三种文件，其余一律忽略（清单文件住在根层，不在 `themes/` 里，天然不进这里）。
+ */
+function scan(dir) {
+    const packagesDir = join(dir, THEME_PACKAGES_SUBDIR);
+    const result = { packages: [], colors: [], styles: [], views: [], decls: [] };
+    for (const pkg of subdirs(packagesDir)) {
+        const pkgDir = join(packagesDir, pkg);
+        if (existsSync(join(pkgDir, THEME_PACKAGE_DEF_FILE))) {
+            result.packages.push({
+                key: `./${pkg}/${THEME_PACKAGE_DEF_FILE}`,
+                file: join(pkgDir, THEME_PACKAGE_DEF_FILE)
+            });
+        }
+        // 按契约递归下降：取值目录段（THEME_DIR_LEVELS）逐层深入，最后在 `colors/`
+        // 固定字面段之下收叶子（index.ts / theme.scss）。
+        walk(pkgDir, [pkg], result);
+    }
+    // 声明目录 `views/*.ts`（设备声明 devices.ts + 页面契约 login/register/forgot-password）：
+    // 插件以副作用 import 拉齐，宿主 bootstrap/store 不再手动 import。
+    for (const name of tsFiles(join(dir, THEME_VIEWS_SUBDIR))) {
+        result.decls.push({
+            key: `./${THEME_VIEWS_SUBDIR}/${name}`,
+            file: join(dir, THEME_VIEWS_SUBDIR, name)
+        });
+    }
+    return result;
+}
+/**
+ * 按 `THEME_DIR_LEVELS` 递归下降主题包目录
+ *
+ * `THEME_DIR_LEVELS = ['pkg','device','page','colorId']`，其中 `pkg` 由 `scan()` 的
+ * 外层循环进入，本函数递归「设备 → 页面 → 配色」三段；`colorId` 是最后一个取值段，
+ * 它的**父目录**是固定字面段 `colors/`（不是一层取值目录），所以到 `colorId` 这层
+ * 不再递归子目录，而是直接在 `colors/<配色>/` 下收叶子文件。
+ *
+ * @param base     当前目录的绝对路径
+ * @param segments 已累积的**取值段**值（与 `THEME_DIR_LEVELS` 前缀一一对应，含包名）
+ * @param result   累积产物
+ */
+function walk(base, segments, result) {
+    // 已累积到「包/设备/页面」三段后，下一层是固定字面段 `colors/` + 最后一个取值段 `colorId`。
+    // 判定依据 = `THEME_DIR_LEVELS` 里还剩几段未进入：只剩 `colorId` 一段时收叶子。
+    if (segments.length === THEME_DIR_LEVELS.length - 1) {
+        // 已到「包/设备/页面」层：版式组件（本页 index.vue）+ colors/ 配色
+        const viewFile = join(base, VIEW_COMPONENT_FILE);
+        if (existsSync(viewFile)) {
+            result.views.push({
+                pkg: segments[0],
+                page: segments[2],
+                key: './' + [...segments, VIEW_COMPONENT_FILE].join('/'),
+                file: viewFile
+            });
+        }
+        const colorsDir = join(base, THEME_COLORS_SEGMENT);
+        for (const color of subdirs(colorsDir)) {
+            const colorDir = join(colorsDir, color);
+            // 键以 `./` 开头（相对主题包目录），段间单斜杠：`./<包>/<设备>/<页面>/colors/<配色>`
+            const keyBase = './' + [...segments, THEME_COLORS_SEGMENT, color].join('/');
+            if (existsSync(join(colorDir, THEME_COLOR_DEF_FILE))) {
+                result.colors.push({
+                    key: `${keyBase}/${THEME_COLOR_DEF_FILE}`,
+                    file: join(colorDir, THEME_COLOR_DEF_FILE)
+                });
+            }
+            if (existsSync(join(colorDir, THEME_COLOR_STYLE_FILE))) {
+                result.styles.push({
+                    key: `${keyBase}/${THEME_COLOR_STYLE_FILE}`,
+                    file: join(colorDir, THEME_COLOR_STYLE_FILE)
+                });
+            }
+        }
+        return;
+    }
+    // 取值段逐层下降：设备 → 页面。
+    for (const name of subdirs(base)) {
+        walk(join(base, name), [...segments, name], result);
+    }
+}
+/** 绝对路径 → 模块说明符（root 内用 `/xxx`，root 外用正斜杠绝对路径） */
+function toSpecifier(abs, root) {
+    const absolute = resolve(abs);
+    const base = resolve(root);
+    if (absolute.startsWith(base + sep)) {
+        return '/' + absolute.slice(base.length + 1).split(sep).join('/');
+    }
+    return absolute.split(sep).join('/');
+}
+/** 生成虚拟模块源码 */
+function render(result, root, manifestSpec) {
+    const lines = [
+        // 装配依赖（纯内核机制）：本模块被 import 时自动装注册表 + 解析清单单例
+        "import { installThemeRegistry, buildThemeRegistry, resolveThemeManifest, installThemeManifest } from 'skinsuite';",
+        // 版式加载表单例（Vue 绑定层）：本模块体把 themeViews 装进内核单例，页面契约惰性解析
+        "import { installThemeViews } from 'skinsuite/vue';",
+        manifestSpec
+            ? `import { default as __manifest } from ${JSON.stringify(manifestSpec)};`
+            : 'const __manifest = null;',
+        // 声明文件副作用 import（views/*.ts）：拉齐 defineThemeDevice / defineThemePage 注册。
+        // 🔴 必须在 `installThemeViews(themeViews)` 之前**作为 import 语句**存在（ESM import 全部
+        //    提升到模块体之前执行），而页面契约现在是惰性解析 loader，不读 themeViews ——
+        //    所以这里安全，不再是「页面契约 import virtual:theme」的循环。
+        ...result.decls.map(entry => `import ${JSON.stringify(toSpecifier(entry.file, root))};`),
+        ''
+    ];
+    const emit = (entries, exportName) => {
+        entries.forEach((entry, index) => {
+            lines.push(`import * as __${exportName}${index} from ${JSON.stringify(toSpecifier(entry.file, root))};`);
+        });
+        lines.push(`export const ${exportName} = {`);
+        entries.forEach((entry, index) => {
+            lines.push(`  ${JSON.stringify(entry.key)}: __${exportName}${index},`);
+        });
+        lines.push('};');
+    };
+    emit(result.packages, 'packages');
+    emit(result.colors, 'colors');
+    lines.push('export const styles = {');
+    result.styles.forEach((entry, index) => {
+        const spec = JSON.stringify(toSpecifier(entry.file, root) + '?inline');
+        lines.push(`  ${JSON.stringify(entry.key)}: () => import(${spec}).then(__m${index} => __m${index}.default),`);
+    });
+    lines.push('};');
+    // ---- themeViews：版式组件（按页面分组；内置包 eager 零请求、非内置包惰性）----
+    // 🔴 内置包用**同步返回**（`() => __viewN`，eager 静态 import 的模块命名空间），
+    //    这样 `ViewRegistry.builtin()` 才能首帧同步拿到内置包版式（零请求、不闪屏）。
+    const builtinViews = result.views.filter(v => v.pkg === DEFAULT_THEME_PACKAGE);
+    builtinViews.forEach((entry, index) => {
+        lines.push(`import * as __view${index} from ${JSON.stringify(toSpecifier(entry.file, root))};`);
+    });
+    const byPage = new Map();
+    for (const entry of result.views) {
+        const list = byPage.get(entry.page);
+        if (list)
+            list.push(entry);
+        else
+            byPage.set(entry.page, [entry]);
+    }
+    lines.push('export const themeViews = {');
+    for (const [page, entries] of byPage) {
+        lines.push(`  ${JSON.stringify(page)}: {`);
+        entries.forEach(entry => {
+            if (entry.pkg === DEFAULT_THEME_PACKAGE) {
+                const idx = builtinViews.indexOf(entry);
+                lines.push(`    ${JSON.stringify(entry.key)}: () => __view${idx},`);
+            }
+            else {
+                const spec = JSON.stringify(toSpecifier(entry.file, root));
+                lines.push(`    ${JSON.stringify(entry.key)}: () => import(${spec}),`);
+            }
+        });
+        lines.push('  },');
+    }
+    lines.push('};');
+    // ---- 装配副作用 + 清单单例（import 本模块即自动装版式加载表 + 注册表 + 清单）----
+    lines.push('installThemeViews(themeViews);');
+    lines.push('installThemeRegistry(buildThemeRegistry({ packages, colors, styles }));');
+    lines.push('export const themeManifest = resolveThemeManifest(__manifest);');
+    lines.push('installThemeManifest(themeManifest);');
+    return lines.join('\n');
+}
+/**
+ * 主题域插件
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { themeAssets, resolveThemeDir } from 'skinsuite/vite';
+ *
+ * export default defineConfig(({ mode }) => ({
+ *   plugins: [themeAssets({ dir: resolveThemeDir(mode) })]
+ * }));
+ * ```
+ */
+export function themeAssets(options) {
+    const moduleId = options.moduleId ?? DEFAULT_MODULE_ID;
+    const virtualId = '\0' + moduleId;
+    const manifestFile = options.manifestFile ?? DEFAULT_THEME_MANIFEST;
+    let root = process.cwd();
+    return {
+        name: 'skinsuite:theme-assets',
+        // 虚拟模块要抢在 Vite 的内置解析之前
+        enforce: 'pre',
+        configResolved(config) {
+            root = config.root;
+        },
+        resolveId(id) {
+            return id === moduleId ? virtualId : null;
+        },
+        load(id) {
+            if (id !== virtualId)
+                return null;
+            const dir = resolve(root, options.dir);
+            // 根目录不存在 = 还没建主题，给**空注册表 + 空清单**而不是让应用起不来
+            if (!isDir(dir))
+                return EMPTY_MODULE;
+            const manifestPath = manifestFile ? join(dir, manifestFile) : '';
+            const manifestSpec = manifestPath && existsSync(manifestPath)
+                ? toSpecifier(manifestPath, root)
+                : null;
+            return render(scan(dir), root, manifestSpec);
+        },
+        configureServer(server) {
+            const dir = resolve(root, options.dir);
+            const onChange = (file) => {
+                if (!file.startsWith(dir))
+                    return;
+                const mod = server.moduleGraph.getModuleById(virtualId);
+                if (mod)
+                    server.moduleGraph.invalidateModule(mod);
+                server.ws.send({ type: 'full-reload' });
+            };
+            // 只监听**增删**：新增/删除主题目录或清单会改变虚拟模块的导出面；
+            // 改已有文件的内容由 HMR 自己处理（那是普通模块，不必重建清单）。
+            server.watcher.on('add', onChange);
+            server.watcher.on('unlink', onChange);
+        }
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/vite/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/vite/plugin.ts"],"names":[],"mappings":"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"}

package/docs/onboarding.md

@@ -235,16 +235,23 @@ VITE_THEME_DIR=src/theme
 
 缺省就是 `src/theme`，可不写。**换目录只改这一个变量，不动代码。**
 
-### 5.2 tsconfig / env 类型（可选）
+### 5.2 tsconfig / env 类型（必做一行）
 
-`skinsuite/vite` 自带 `virtual:theme` 的类型声明，宿主通过引入 `skinsuite/vite` 即可获得，
-一般无需自写。若你的 `vue-tsc` 报找不到 `virtual:theme`，确认 `vite.config.ts` 已被 tsconfig
-纳入检查范围，或补一句：
+`skinsuite/vite` 自带 `virtual:theme` 的类型声明（`src/vite/theme.d.ts`），但**类型声明只有在
+被纳入 TS 程序时才有意义**。在你项目的 `src/vite-env.d.ts` 里加一行：
 
 ```ts
-/// <reference types="skinsuite/vite" />
+/// <reference types="vite/client" />
+import "skinsuite/vite";   // 让 theme.d.ts 的 declare module 'virtual:theme' 进程序
 ```
 
+🔴 **不要写 `/// <reference types="skinsuite/vite" />`**——`reference types` 解析不到包的
+**子路径**入口，症状是 `vue-tsc -b` 报 `Cannot find module or type declarations for side-effect
+import of 'virtual:theme'`（TS2882），而 `vite build` / 浏览器全正常，很容易误判成「只是编辑器问题」。
+
+`import` 写在 `.d.ts` 里是**纯类型侧**的：不产生任何运行时代码，也不会把插件打进产物，只是
+把 `src/vite/index.ts` 上的 `/// <reference path="./theme.d.ts" />` 带进程序。
+
 ---
 
 ## 六、bootstrap.ts（启动编排，从这开始写）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skinsuite",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "多主题 / 多版式机制的纯内核（零运行时依赖）：目录名与默认值的白名单常量、主题包契约类型、明暗 mode 与色系 tone、CSS 变量 token 的安全校验、设备维度 URL 参数读取。不碰 DOM / 构建器 / 路由，可在任意前端（Vue / React / Node / SSR）复用。",
   "type": "module",
   "main": "./dist/index.js",
@@ -8,7 +8,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./src/index.ts",
       "import": "./dist/index.js"
     },
     "./vue": {
@@ -17,7 +17,7 @@
     },
     "./vite": {
       "types": "./src/vite/index.ts",
-      "import": "./src/vite/index.ts"
+      "import": "./dist/vite/index.js"
     },
     "./package.json": "./package.json"
   },
@@ -34,7 +34,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.vite.json",
     "typecheck": "tsc -p tsconfig.json",
     "test": "npm run build && node --test",
     "prepack": "npm run build"

package/src/vite/index.ts

@@ -31,11 +31,11 @@
  */
 /// <reference path="./theme.d.ts" />
 
-export { themeAssets } from './plugin.ts';
-export type { ThemeAssetsPluginOptions } from './plugin.ts';
+export { themeAssets } from './plugin.js';
+export type { ThemeAssetsPluginOptions } from './plugin.js';
 export {
   DEFAULT_THEME_DIR,
   THEME_PACKAGES_SUBDIR,
   DEFAULT_THEME_MANIFEST,
   resolveThemeDir
-} from './dir.ts';
+} from './dir.js';

package/src/vite/plugin.ts

@@ -37,8 +37,8 @@
  *
  * === 产出形态（资产部分与 `import.meta.glob` 的结果保持一致）===
  * ```ts
- * export const packages:   { './default/index.ts': Module }
- * export const colors:     { './default/mobile/login/colors/white/index.ts': Module }
+ * export const packages:   { './default/index.js': Module }
+ * export const colors:     { './default/mobile/login/colors/white/index.js': Module }
  * export const styles:     { './default/mobile/login/colors/white/theme.scss': () => Promise<string> }
  * export const themeViews: { 'login': { './default/mobile/login/index.vue': () => Module } }
  * // 副作用：installThemeViews(themeViews) / installThemeRegistry(...) / installThemeManifest(...)
@@ -70,8 +70,8 @@ import {
   THEME_COLORS_SEGMENT,
   THEME_DIR_LEVELS,
   THEME_PACKAGE_DEF_FILE
-} from '../constants.ts';
-import { DEFAULT_THEME_MANIFEST, THEME_PACKAGES_SUBDIR, THEME_VIEWS_SUBDIR } from './dir.ts';
+} from '../constants.js';
+import { DEFAULT_THEME_MANIFEST, THEME_PACKAGES_SUBDIR, THEME_VIEWS_SUBDIR } from './dir.js';
 
 /** 版式组件的叶子文件名（`themes/<包>/<设备>/<页面>/index.vue`） */
 const VIEW_COMPONENT_FILE = 'index.vue';
@@ -149,7 +149,7 @@ function subdirs(path: string): string[] {
 function tsFiles(path: string): string[] {
   try {
     return readdirSync(path, { withFileTypes: true })
-      .filter(entry => entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts'))
+      .filter(entry => entry.isFile() && entry.name.endsWith('.js') && !entry.name.endsWith('.d.js'))
       .map(entry => entry.name)
       .sort();
   } catch {