skinsuite 0.1.0 → 0.2.1

package/README.md

@@ -27,6 +27,24 @@ npm install skinsuite
 
 ---
 
+## 接入指南（新前端从零接入）
+
+> 要在一个**新的 Vue + Vite 前端**里用上多主题 / 多版式 / 多设备 / 调试面板？从头一步步走：
+
+- **完整接入指南**：[`docs/onboarding.md`](./docs/onboarding.md) —— 从安装、目录约定、写主题资产、
+  写声明文件、`vite.config.ts`、`bootstrap.ts`、store、`App.vue`、路由与容器，到验证清单与常见坑，
+  每一步给真实 API + 完整代码。
+
+先看三个入口的分工，再看下面的「30 秒上手」体会单个 API 的用法：
+
+| 入口 | 作用 |
+| --- | --- |
+| `skinsuite` | 纯内核（本 README 的 API 全在这里） |
+| `skinsuite/vue` | Vue 绑定：`<ThemeView>` / `<ThemeRoot>` / `createThemeState` / 设备域 |
+| `skinsuite/vite` | 构建期插件：`themeAssets` 扫主题目录生成 `virtual:theme` |
+
+---
+
 ## 30 秒上手
 
 ### 1. 安全地接受外部下发的 CSS 变量
@@ -189,7 +207,9 @@ readDeviceParam(query, name, device);
 | 设备取值集合 | `mobile` / `standard` / `mini` 是**某个 app** 的词汇表，不是机制的一部分 |
 | 业务资产（`themes/**`） | 版式实现与配色数据是"你的页面长什么样"，随应用走 |
 
-配套的宿主 Vue 适配层（store + DOM 注入 + glob 适配器）计划单发一个包 `skinsuite-vue`，见 [Roadmap](#roadmap)。
+配套的宿主 Vue 适配层（`<ThemeView>` / `<ThemeRoot>` / 状态机 / 设备域）与 Vite 构建插件
+已经作为**同包子路径** `skinsuite/vue` 与 `skinsuite/vite` 一起发布 —— 见
+[接入指南](./docs/onboarding.md)，不再单发一个包。
 
 ### 在自有项目里接入（Vite 示例）
 
@@ -246,11 +266,13 @@ CSS 自定义属性是能**直接改变渲染**的输入。未经校验就 `setP
 
 | 期 | 内容 | 状态 |
 | --- | --- | --- |
-| Stage 1 | 常量与白名单、`types`、`tone`、`mode`、设备维度参数、token 形态与校验 | ✅ 已发布（本版本） |
-| Stage 2 | 版式注册表工厂 + 版式选择器（四档链：`?view.<设备>` → `?view` → 包声明 → 环境变量 → 当前包） | 计划中 |
-| Stage 3 | 配色注册表与回退链（`createColorRegistry` 等） | 计划中 |
-| Stage 4 | store 的纯逻辑（URL 意图归一、明暗联动规则）；DOM 与存储拆成适配器 | 计划中 |
-| Stage 5 | 配套 Vue 适配层 `skinsuite-vue` | 计划中 |
+| Stage 1 | 常量与白名单、`types`、`tone`、`mode`、设备维度参数、token 形态与校验 | ✅ 已发布 |
+| Stage 2 | 版式注册表工厂 + 版式选择器（`defineThemePage` / `createViewPicker`，`?th[_<设备缩写>]` → 包声明 → 当前包） | ✅ 已发布（`skinsuite/vue`） |
+| Stage 3 | 配色注册表与回退链（`createColorRegistry` 等） | ✅ 已发布 |
+| Stage 4 | store 的纯逻辑（`createThemeState`：URL 意图归一、明暗联动、token 注入） | ✅ 已发布（`skinsuite/vue`） |
+| Stage 5 | Vue 适配层 + Vite 构建插件（`skinsuite/vue` / `skinsuite/vite`） | ✅ 已发布 |
+
+> 阶段划分已随机制下沉而完成，上表仅作历史对照。接入方式以 [docs/onboarding.md](./docs/onboarding.md) 为准。
 
 在 1.0 之前（0.x），次要版本可能包含重命名 —— 公开出口是显式具名导出，改名即 semver-minor。
 
@@ -266,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/constants.d.ts

@@ -8,7 +8,7 @@
  *
  * ⚠️ 本文件**零依赖**（不 import 任何东西），也不碰 DOM / 构建器 / 路由：
  *    这是 `skinsuite` 能被任意前端复用的前提（见
- *    docs/frontend/theme-package-extraction.md 的「〇、一条原则」）。
+ *    docs/standards/theme-package-extraction.md 的「〇、一条原则」）。
  *
  * @author yijiu2025
  */
@@ -81,13 +81,50 @@ export declare const DEFAULT_THEME_COLOR = "white";
  */
 export declare const DEFAULT_THEME_DARK_COLOR = "black";
 /**
- * 基础版式的**逻辑** id（与版式注册表工厂的默认 `baseId` 是同一约定值）
+ * 主题包目录的**结构契约** —— 「目录长什么样」的唯一来源
  *
- * ⚠️ 它**不是**配色注册表里的 view 值：配色记录里的 view 段恒等于包名
- * （一个主题包 = 一种版式），`'base'` 永远不会出现在配色键里。
- * 外部 `?view=base` 由版式选择器归一化到当前包名，到不了配色注册表。
+ * === 为什么要有它（2026-10-17）===
+ * 目录骨架原先是一份**隐式约定**，散在三个形态各异的实现里：
+ *   • 构建插件的 `scan()`：嵌套 for 循环 + 写死的 `'colors'` 字符串
+ *   • 注册表的 `colorFromKey()`：正则 `\./([^/]+)/([^/]+)/([^/]+)/colors/([^/]+)/…`
+ *   • `types.ts` 的注释 ASCII 树
+ * 三处各自维护对同一件事的认知。改目录结构（比如配色下再分 `tone` 层、或
+ * `colors` 改名）时，只要漏改一处，就出现**静默扫不到主题**这种无从归因的脱节
+ * （扫描是"读不到就跳过"，不报错）——与「设备词汇表散落四处」是同一类坑。
  *
- * 保留它只是为了版式工厂的默认值；新增代码不要拿它当配色查找的 view 参数。
+ * 现在收敛成下面这一组常量：**段序列 + 固定字面段 + 叶子文件名**。构建插件扫描
+ * 目录、注册表解析键，都从这里派生，不再各自手写。
+ *
+ * === 它**只**承诺「结构形态」，不承诺「取值集合」===
+ * 段里 `pkg` / `device` / `page` / `colorId` 的**合法取值**（有哪些设备、有哪些包）
+ * 是宿主的词汇表，内核不绑定（设备集合在宿主 `devices.ts`，包集合由文件系统决定）。
+ * 这里只承诺"有这么几段、顺序如此、其中 `colors` 是固定字面段"。
+ *
+ * === 目录形态（唯一形态，2026-09-26 收窄后）===
+ * ```
+ * themes/<包>/<设备>/<页面>/colors/<配色>/{index.ts, theme.scss}
+ * ```
+ * 配色与版式**同级**，「版式」不是一层目录（变体版式请新建主题包）。
+ * 曾支持的 6 段变体形态（`<页面>/<版式>/colors/`）已删除。
+ */
+/** 配色键里的**固定字面段**：`colors` 是目录结构的一部分，不是取值段 */
+export declare const THEME_COLORS_SEGMENT = "colors";
+/** 配色定义文件（`<配色>/index.ts`）与附加样式（`<配色>/theme.scss`）的文件名 */
+export declare const THEME_COLOR_DEF_FILE = "index.ts";
+export declare const THEME_COLOR_STYLE_FILE = "theme.scss";
+/** 主题包定义入口（`<包>/index.ts`）的文件名 */
+export declare const THEME_PACKAGE_DEF_FILE = "index.ts";
+/**
+ * 主题包目录的**取值目录段**（`themes/` 之下、从包到配色叶子的真实目录层）
+ *
+ * 与 `THEME_COLORS_SEGMENT`（固定字面段）、`THEME_COLOR_DEF_FILE` /
+ * `THEME_COLOR_STYLE_FILE`（叶子文件名）共同构成「目录长什么样」的完整契约。
+ * 顺序即目录深度：`['pkg','device','page','colorId']` 对应
+ * `themes/<pkg>/<device>/<page>/colors/<colorId>/`。
+ *
+ * 构建插件的 `scan()` 用它做**递归下降**（每段一层目录），注册表的 `colorFromKey()`
+ * 用它拼正则（键 = `./` + 这些段，`page` 与 `colorId` 之间插入 `THEME_COLORS_SEGMENT`）。
+ * 改目录结构（配色下再分层、`colors` 改名）只动这一处。
  */
-export declare const BASE_VIEW_ID = "base";
+export declare const THEME_DIR_LEVELS: readonly ["pkg", "device", "page", "colorId"];
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,QAAiB,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,QAAiB,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAC/C,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD,kCAAkC;AAClC,eAAO,MAAM,sBAAsB,aAAa,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,+CAAgD,CAAC"}

package/dist/constants.js

@@ -8,7 +8,7 @@
  *
  * ⚠️ 本文件**零依赖**（不 import 任何东西），也不碰 DOM / 构建器 / 路由：
  *    这是 `skinsuite` 能被任意前端复用的前提（见
- *    docs/frontend/theme-package-extraction.md 的「〇、一条原则」）。
+ *    docs/standards/theme-package-extraction.md 的「〇、一条原则」）。
  *
  * @author yijiu2025
  */
@@ -81,13 +81,50 @@ export const DEFAULT_THEME_COLOR = 'white';
  */
 export const DEFAULT_THEME_DARK_COLOR = 'black';
 /**
- * 基础版式的**逻辑** id（与版式注册表工厂的默认 `baseId` 是同一约定值）
+ * 主题包目录的**结构契约** —— 「目录长什么样」的唯一来源
  *
- * ⚠️ 它**不是**配色注册表里的 view 值：配色记录里的 view 段恒等于包名
- * （一个主题包 = 一种版式），`'base'` 永远不会出现在配色键里。
- * 外部 `?view=base` 由版式选择器归一化到当前包名，到不了配色注册表。
+ * === 为什么要有它（2026-10-17）===
+ * 目录骨架原先是一份**隐式约定**，散在三个形态各异的实现里：
+ *   • 构建插件的 `scan()`：嵌套 for 循环 + 写死的 `'colors'` 字符串
+ *   • 注册表的 `colorFromKey()`：正则 `\./([^/]+)/([^/]+)/([^/]+)/colors/([^/]+)/…`
+ *   • `types.ts` 的注释 ASCII 树
+ * 三处各自维护对同一件事的认知。改目录结构（比如配色下再分 `tone` 层、或
+ * `colors` 改名）时，只要漏改一处，就出现**静默扫不到主题**这种无从归因的脱节
+ * （扫描是"读不到就跳过"，不报错）——与「设备词汇表散落四处」是同一类坑。
  *
- * 保留它只是为了版式工厂的默认值；新增代码不要拿它当配色查找的 view 参数。
+ * 现在收敛成下面这一组常量：**段序列 + 固定字面段 + 叶子文件名**。构建插件扫描
+ * 目录、注册表解析键，都从这里派生，不再各自手写。
+ *
+ * === 它**只**承诺「结构形态」，不承诺「取值集合」===
+ * 段里 `pkg` / `device` / `page` / `colorId` 的**合法取值**（有哪些设备、有哪些包）
+ * 是宿主的词汇表，内核不绑定（设备集合在宿主 `devices.ts`，包集合由文件系统决定）。
+ * 这里只承诺"有这么几段、顺序如此、其中 `colors` 是固定字面段"。
+ *
+ * === 目录形态（唯一形态，2026-09-26 收窄后）===
+ * ```
+ * themes/<包>/<设备>/<页面>/colors/<配色>/{index.ts, theme.scss}
+ * ```
+ * 配色与版式**同级**，「版式」不是一层目录（变体版式请新建主题包）。
+ * 曾支持的 6 段变体形态（`<页面>/<版式>/colors/`）已删除。
+ */
+/** 配色键里的**固定字面段**：`colors` 是目录结构的一部分，不是取值段 */
+export const THEME_COLORS_SEGMENT = 'colors';
+/** 配色定义文件（`<配色>/index.ts`）与附加样式（`<配色>/theme.scss`）的文件名 */
+export const THEME_COLOR_DEF_FILE = 'index.ts';
+export const THEME_COLOR_STYLE_FILE = 'theme.scss';
+/** 主题包定义入口（`<包>/index.ts`）的文件名 */
+export const THEME_PACKAGE_DEF_FILE = 'index.ts';
+/**
+ * 主题包目录的**取值目录段**（`themes/` 之下、从包到配色叶子的真实目录层）
+ *
+ * 与 `THEME_COLORS_SEGMENT`（固定字面段）、`THEME_COLOR_DEF_FILE` /
+ * `THEME_COLOR_STYLE_FILE`（叶子文件名）共同构成「目录长什么样」的完整契约。
+ * 顺序即目录深度：`['pkg','device','page','colorId']` 对应
+ * `themes/<pkg>/<device>/<page>/colors/<colorId>/`。
+ *
+ * 构建插件的 `scan()` 用它做**递归下降**（每段一层目录），注册表的 `colorFromKey()`
+ * 用它拼正则（键 = `./` + 这些段，`page` 与 `colorId` 之间插入 `THEME_COLORS_SEGMENT`）。
+ * 改目录结构（配色下再分层、`colors` 改名）只动这一处。
  */
-export const BASE_VIEW_ID = 'base';
+export const THEME_DIR_LEVELS = ['pkg', 'device', 'page', 'colorId'];
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,8CAA8C;AAC9C,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE7C,0DAA0D;AAC1D,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,YAAY,CAAC;AAEnD,kCAAkC;AAClC,MAAM,CAAC,MAAM,sBAAsB,GAAG,UAAU,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC"}

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  *   • **构建器耦合**（`import.meta.glob` / `import.meta.env`）→ 由宿主适配器提供
  *   • **路由**（vue-router）→ 应用自己的世界观
  *   • **业务资产**（`themes/**` 的版式与配色实现）→ 随应用走
- * 见 `docs/frontend/theme-package-extraction.md` 的「〇、一条原则」与「五、四个注入点契约」。
+ * 见 `docs/standards/theme-package-extraction.md` 的「〇、一条原则」与「五、四个注入点契约」。
  *
  * === 为什么用显式具名导出，而不是 `export *` ===
  * 立项文档 §四 有一张"公开 API 面"的表，本文件就是那张表的**落地**：表里没有的名字
@@ -29,14 +29,40 @@
  *
  * @author yijiu2025
  */
-export { THEME_ID_RE, DEFAULT_THEME_ID, DEFAULT_THEME_PACKAGE, DEFAULT_THEME_PAGE, DEFAULT_THEME_COLOR, DEFAULT_THEME_DARK_COLOR, BASE_VIEW_ID } from './constants.js';
-export { THEME_TONES, TONE_LABELS, isThemeTone, normalizeTone } from './tone.js';
-export type { ThemeTone } from './tone.js';
-export { MODE_CYCLE, MODE_LABELS, isThemeMode, normalizeMode } from './mode.js';
-export type { ThemeMode } from './mode.js';
+export { THEME_ID_RE, DEFAULT_THEME_ID, DEFAULT_THEME_PACKAGE, DEFAULT_THEME_PAGE, DEFAULT_THEME_COLOR, DEFAULT_THEME_DARK_COLOR, THEME_DIR_LEVELS, THEME_COLORS_SEGMENT, THEME_COLOR_DEF_FILE, THEME_COLOR_STYLE_FILE, THEME_PACKAGE_DEF_FILE } from './constants.js';
+export { THEME_TONES, TONE_LABELS, isThemeTone, normalizeTone } from './scheme.js';
+export type { ThemeTone } from './scheme.js';
+export { MODE_CYCLE, MODE_LABELS, isThemeMode, normalizeMode } from './scheme.js';
+export type { ThemeMode } from './scheme.js';
 export { isSafeTokenName, isSafeTokenValue, isSafeTokenEntry, sanitizeOverrides } from './tokens.js';
 export type { ThemeTokenOverrides, SanitizeResult, ThemeTokenLayers } from './tokens.js';
 export type { MauthThemeMeta, MauthThemePackage, MauthThemeColor, MauthThemeRecord } from './types.js';
+export { buildThemeRegistry, installThemeRegistry } from './registry.js';
+export type { ThemeAssetModules } from './registry.js';
+export { listThemes, listColorsOf, toneOfColor, toneOfAnyScope, listColorIdsOfTone, resolveThemeId, getThemeRecord, getDefaultThemeId, isKnownTheme, listColorViews } from './registry.js';
 export { DEVICE_SCOPED_PARAMS, readDeviceParam } from './views/params.js';
 export type { DeviceScopedParam } from './views/params.js';
+export { asDeviceId, containersOf, deviceContext, deviceLabel, pickDeviceId } from './views/device.js';
+export type { DeviceDef, DeviceMatchContext } from './views/device.js';
+/**
+ * 设备注册表工厂：一份 `DeviceDef[]` 清单 → 全套已绑定的判定机制。
+ * 宿主不再逐个转发判定函数，只写清单、调一次工厂。
+ */
+export { createDeviceRegistry } from './views/device-registry.js';
+export type { DeviceRegistry, DeviceRegistryOptions } from './views/device-registry.js';
+/**
+ * 外部下发的主题配置：**只归一形状，不碰网络**
+ *
+ * 取数（超时 / 重试 / cookie 策略）属于宿主，故不在此。
+ */
+export { normalizeRemoteThemeConfig } from './scheme.js';
+export type { RemoteThemeConfig } from './scheme.js';
+/**
+ * 主题域清单（主题目录里那份 `theme.config.ts` 的契约）：调试开关
+ *
+ * 它是**主题域自带**的配置（跟主题包一起走）；「主题目录在哪」不在这里 ——
+ * 那是宿主的部署事实，由宿主的 env 提供，换目录不必改代码也不必改这个包。
+ */
+export { defineThemeManifest, isThemeDebugVisible, resolveThemeManifest, installThemeManifest, themeManifest } from './manifest.js';
+export type { ResolvedThemeDebug, ResolvedThemeManifest, ThemeDebugMode, ThemeManifest } from './manifest.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACjF,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAChF,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzF,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACtB,gBAAgB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnF,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAClF,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzF,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACzE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EACL,UAAU,EACR,YAAY,EACd,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EACL,UAAU,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvE;;;GAGG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExF;;;;GAIG;AACH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;GAKG;AACH,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,aAAa,EACd,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -11,7 +11,7 @@
  *   • **构建器耦合**（`import.meta.glob` / `import.meta.env`）→ 由宿主适配器提供
  *   • **路由**（vue-router）→ 应用自己的世界观
  *   • **业务资产**（`themes/**` 的版式与配色实现）→ 随应用走
- * 见 `docs/frontend/theme-package-extraction.md` 的「〇、一条原则」与「五、四个注入点契约」。
+ * 见 `docs/standards/theme-package-extraction.md` 的「〇、一条原则」与「五、四个注入点契约」。
  *
  * === 为什么用显式具名导出，而不是 `export *` ===
  * 立项文档 §四 有一张"公开 API 面"的表，本文件就是那张表的**落地**：表里没有的名字
@@ -29,9 +29,30 @@
  *
  * @author yijiu2025
  */
-export { THEME_ID_RE, DEFAULT_THEME_ID, DEFAULT_THEME_PACKAGE, DEFAULT_THEME_PAGE, DEFAULT_THEME_COLOR, DEFAULT_THEME_DARK_COLOR, BASE_VIEW_ID } from './constants.js';
-export { THEME_TONES, TONE_LABELS, isThemeTone, normalizeTone } from './tone.js';
-export { MODE_CYCLE, MODE_LABELS, isThemeMode, normalizeMode } from './mode.js';
+export { THEME_ID_RE, DEFAULT_THEME_ID, DEFAULT_THEME_PACKAGE, DEFAULT_THEME_PAGE, DEFAULT_THEME_COLOR, DEFAULT_THEME_DARK_COLOR, THEME_DIR_LEVELS, THEME_COLORS_SEGMENT, THEME_COLOR_DEF_FILE, THEME_COLOR_STYLE_FILE, THEME_PACKAGE_DEF_FILE } from './constants.js';
+export { THEME_TONES, TONE_LABELS, isThemeTone, normalizeTone } from './scheme.js';
+export { MODE_CYCLE, MODE_LABELS, isThemeMode, normalizeMode } from './scheme.js';
 export { isSafeTokenName, isSafeTokenValue, isSafeTokenEntry, sanitizeOverrides } from './tokens.js';
+export { buildThemeRegistry, installThemeRegistry } from './registry.js';
+export { listThemes, listColorsOf, toneOfColor, toneOfAnyScope, listColorIdsOfTone, resolveThemeId, getThemeRecord, getDefaultThemeId, isKnownTheme, listColorViews } from './registry.js';
 export { DEVICE_SCOPED_PARAMS, readDeviceParam } from './views/params.js';
+export { asDeviceId, containersOf, deviceContext, deviceLabel, pickDeviceId } from './views/device.js';
+/**
+ * 设备注册表工厂：一份 `DeviceDef[]` 清单 → 全套已绑定的判定机制。
+ * 宿主不再逐个转发判定函数，只写清单、调一次工厂。
+ */
+export { createDeviceRegistry } from './views/device-registry.js';
+/**
+ * 外部下发的主题配置：**只归一形状，不碰网络**
+ *
+ * 取数（超时 / 重试 / cookie 策略）属于宿主，故不在此。
+ */
+export { normalizeRemoteThemeConfig } from './scheme.js';
+/**
+ * 主题域清单（主题目录里那份 `theme.config.ts` 的契约）：调试开关
+ *
+ * 它是**主题域自带**的配置（跟主题包一起走）；「主题目录在哪」不在这里 ——
+ * 那是宿主的部署事实，由宿主的 env 提供，换目录不必改代码也不必改这个包。
+ */
+export { defineThemeManifest, isThemeDebugVisible, resolveThemeManifest, installThemeManifest, themeManifest } from './manifest.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGjF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGhF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACtB,gBAAgB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGnF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGlF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEzE,OAAO,EACL,UAAU,EACR,YAAY,EACd,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG1E,OAAO,EACL,UAAU,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAG3B;;;GAGG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAGlE;;;;GAIG;AACH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAGzD;;;;;GAKG;AACH,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,eAAe,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 主题域清单（manifest）—— 主题目录里那份 `theme.config.ts` 的契约
+ *
+ * === 它只回答一个问题 ===
+ * 调试面板**什么时候出现**（`debug`）
+ *
+ * === 为什么不再声明「路径 → 页面」投影（routes）===
+ * 早先清单里有一份 `routes`（哪条路径算哪个页面），理由是「配色与版式的查找范围是
+ * 包 × 设备 × 页面」。但页面身份如今由 `<ThemeView page="...">` **显式传入**（容器
+ * 文件位置即身份），并由 `setActivePageView` 维护进 store 的 `activePage` —— 不再
+ * 需要「从路径反推页面」。而「路径 → 页面」的映射本身是 **router 的职责**（路由表
+ * 由 `listPageViews()` 自动生成，页面名就编码在 path 里），主题清单再声明一份就是
+ * 第二个真相，两处不一致时只有「面板认不出页面」这种无从归因的静默症状。
+ *
+ * 于是清单收敛为**只声明一件事**，其余全部由机制推导：
+ *   · 主题根目录在哪 → `.env` 的 `VITE_THEME_DIR`
+ *   · 有哪些设备     → `defineThemeDevice` 声明（设备域）
+ *   · 有哪些页面     → `defineThemePage` 声明（页面域）
+ *   · 有哪些配色     → 主题包目录结构（扫出来的，不在这里声明）
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（2026-10-18 移除 routes 投影：页面身份由 ThemeView 显式传入）
+ */
+/**
+ * 调试面板开关
+ *
+ *   `off`    永不出现（产物里也不下载面板，见宿主的异步加载入口）
+ *   `url`    带触发参数才出现 —— **生产缺省**：真机没有 DevTools，
+ *            线上排查"这个租户颜色不对"时能直接切主题看效果是刚需
+ *   `always` 首次渲染就出现（演示 / 联调环境）
+ */
+export type ThemeDebugMode = 'off' | 'url' | 'always';
+/** 清单的输入形态（`defineThemeManifest` 的参数，字段全可省） */
+export interface ThemeManifest {
+    debug?: {
+        enabled?: ThemeDebugMode;
+        /** 触发参数名，缺省 `debug` */
+        query?: string;
+        /** 触发参数值，缺省 `theme`（即 `?debug=theme`） */
+        value?: string;
+    };
+}
+/** 补全默认值后的清单 */
+export interface ResolvedThemeManifest {
+    debug: {
+        enabled: ThemeDebugMode;
+        query: string;
+        value: string;
+    };
+}
+/** 调试开关的补全值（供 `isThemeDebugVisible` 的参数类型使用） */
+export type ResolvedThemeDebug = ResolvedThemeManifest['debug'];
+/**
+ * 声明并校验主题清单
+ *
+ * 与白名单常量同一口径：配置写错是开发者错误，应该在启动时就炸，
+ * 而不是等到"面板不出现"这种无从归因的现象。
+ */
+export declare function defineThemeManifest(manifest?: ThemeManifest): ResolvedThemeManifest;
+/**
+ * 调试面板此刻是否该出现
+ *
+ * `url` 档用 `query` 里的 `query` 键比对 `value`（缺省 `?debug=theme`）。
+ * 参数表只要求"能按键取值"的形态（vue-router 的 `route.query`、`URLSearchParams`
+ * 转出来的普通对象都满足），库不绑定任何一种 —— 它不碰路由。
+ *
+ * ⚠️ 值可能是数组（`?debug=theme&debug=other`）：任一元素命中即算命中，
+ *    与 vue-router 的 `LocationQuery` 形态一致。
+ */
+export declare function isThemeDebugVisible(debug: ResolvedThemeDebug, query: Readonly<Record<string, unknown>>): boolean;
+/**
+ * 解析运行时拿到的清单（构建插件扫出来的 `theme.config.ts`）
+ *
+ * 目录里没写清单时用机制默认值（面板退回 `url` 档），而不是让页面起不来。
+ * 这是「从构建产物到运行时单例」的收口点：清单写错在 `defineThemeManifest` 求值期就炸，
+ * 缺失则在这里兜底。
+ */
+export declare function resolveThemeManifest(manifest: ResolvedThemeManifest | null | undefined): ResolvedThemeManifest;
+/** 装入已解析的清单（`virtual:theme` 自动装配时调一次） */
+export declare function installThemeManifest(manifest: ResolvedThemeManifest): void;
+/** 当前清单单例（调试面板可见性用） */
+export declare function themeManifest(): ResolvedThemeManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEtD,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,cAAc,CAAC;QACzB,uBAAuB;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,yCAAyC;QACzC,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,gBAAgB;AAChB,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE;QAAE,OAAO,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AAED,gDAAgD;AAChD,MAAM,MAAM,kBAAkB,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAIhE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,aAAkB,GAAG,qBAAqB,CAevF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,OAAO,CAMT;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GACjD,qBAAqB,CAEvB;AAYD,yCAAyC;AACzC,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAE1E;AAED,uBAAuB;AACvB,wBAAgB,aAAa,IAAI,qBAAqB,CAErD"}

package/dist/manifest.js

@@ -0,0 +1,90 @@
+/**
+ * 主题域清单（manifest）—— 主题目录里那份 `theme.config.ts` 的契约
+ *
+ * === 它只回答一个问题 ===
+ * 调试面板**什么时候出现**（`debug`）
+ *
+ * === 为什么不再声明「路径 → 页面」投影（routes）===
+ * 早先清单里有一份 `routes`（哪条路径算哪个页面），理由是「配色与版式的查找范围是
+ * 包 × 设备 × 页面」。但页面身份如今由 `<ThemeView page="...">` **显式传入**（容器
+ * 文件位置即身份），并由 `setActivePageView` 维护进 store 的 `activePage` —— 不再
+ * 需要「从路径反推页面」。而「路径 → 页面」的映射本身是 **router 的职责**（路由表
+ * 由 `listPageViews()` 自动生成，页面名就编码在 path 里），主题清单再声明一份就是
+ * 第二个真相，两处不一致时只有「面板认不出页面」这种无从归因的静默症状。
+ *
+ * 于是清单收敛为**只声明一件事**，其余全部由机制推导：
+ *   · 主题根目录在哪 → `.env` 的 `VITE_THEME_DIR`
+ *   · 有哪些设备     → `defineThemeDevice` 声明（设备域）
+ *   · 有哪些页面     → `defineThemePage` 声明（页面域）
+ *   · 有哪些配色     → 主题包目录结构（扫出来的，不在这里声明）
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（2026-10-18 移除 routes 投影：页面身份由 ThemeView 显式传入）
+ */
+const DEBUG_MODES = ['off', 'url', 'always'];
+/**
+ * 声明并校验主题清单
+ *
+ * 与白名单常量同一口径：配置写错是开发者错误，应该在启动时就炸，
+ * 而不是等到"面板不出现"这种无从归因的现象。
+ */
+export function defineThemeManifest(manifest = {}) {
+    const debug = manifest.debug ?? {};
+    const enabled = debug.enabled ?? 'url';
+    if (!DEBUG_MODES.includes(enabled)) {
+        throw new Error(`[theme] debug.enabled 只能是 ${DEBUG_MODES.join(' / ')}，收到「${String(enabled)}」。`);
+    }
+    const query = debug.query ?? 'debug';
+    const value = debug.value ?? 'theme';
+    if (!query.trim() || !value.trim()) {
+        throw new Error('[theme] debug.query / debug.value 必须是非空字符串。');
+    }
+    return { debug: { enabled, query, value } };
+}
+/**
+ * 调试面板此刻是否该出现
+ *
+ * `url` 档用 `query` 里的 `query` 键比对 `value`（缺省 `?debug=theme`）。
+ * 参数表只要求"能按键取值"的形态（vue-router 的 `route.query`、`URLSearchParams`
+ * 转出来的普通对象都满足），库不绑定任何一种 —— 它不碰路由。
+ *
+ * ⚠️ 值可能是数组（`?debug=theme&debug=other`）：任一元素命中即算命中，
+ *    与 vue-router 的 `LocationQuery` 形态一致。
+ */
+export function isThemeDebugVisible(debug, query) {
+    if (debug.enabled === 'off')
+        return false;
+    if (debug.enabled === 'always')
+        return true;
+    const raw = query[debug.query];
+    const values = Array.isArray(raw) ? raw : [raw];
+    return values.some(item => typeof item === 'string' && item === debug.value);
+}
+/**
+ * 解析运行时拿到的清单（构建插件扫出来的 `theme.config.ts`）
+ *
+ * 目录里没写清单时用机制默认值（面板退回 `url` 档），而不是让页面起不来。
+ * 这是「从构建产物到运行时单例」的收口点：清单写错在 `defineThemeManifest` 求值期就炸，
+ * 缺失则在这里兜底。
+ */
+export function resolveThemeManifest(manifest) {
+    return manifest ?? defineThemeManifest({});
+}
+/**
+ * 模块级清单单例 —— 「清单从哪来」的收口点
+ *
+ * 与配色注册表（`installThemeRegistry`）同一范式：`virtual:theme` 虚拟模块被 import 的
+ * 那一刻（模块求值期副作用）把 resolve 后的清单装进来，之后内核各处（调试面板可见性）
+ * 直接读本单例，**无需宿主 import `virtual:theme` 再转发**。
+ * 未装入时为机制默认（面板 `url` 档），而不是让应用起不来。
+ */
+let themeManifestSingleton = defineThemeManifest({});
+/** 装入已解析的清单（`virtual:theme` 自动装配时调一次） */
+export function installThemeManifest(manifest) {
+    themeManifestSingleton = manifest;
+}
+/** 当前清单单例（调试面板可见性用） */
+export function themeManifest() {
+    return themeManifestSingleton;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA+BH,MAAM,WAAW,GAA8B,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAA0B,EAAE;IAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC;IACvC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,6BAA6B,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAC/E,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAyB,EACzB,KAAwC;IAExC,IAAI,KAAK,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,KAAK,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAkD;IAElD,OAAO,QAAQ,IAAI,mBAAmB,CAAC,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,IAAI,sBAAsB,GAA0B,mBAAmB,CAAC,EAAE,CAAC,CAAC;AAE5E,yCAAyC;AACzC,MAAM,UAAU,oBAAoB,CAAC,QAA+B;IAClE,sBAAsB,GAAG,QAAQ,CAAC;AACpC,CAAC;AAED,uBAAuB;AACvB,MAAM,UAAU,aAAa;IAC3B,OAAO,sBAAsB,CAAC;AAChC,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,73 @@
+import type { MauthThemeColor, MauthThemeMeta, MauthThemePackage, MauthThemeRecord } from './types.js';
+import { type ThemeTone } from './scheme.js';
+/**
+ * 虚拟模块 `virtual:theme` 产出的三个加载表（由 `skinsuite/vite` 的 `themeAssets()`
+ * 在构建期扫描生成）。键相对主题包目录 `themes/`（`./<包>/...`）。
+ */
+export interface ThemeAssetModules {
+    /** 包定义：`./<包>/index.ts` */
+    packages: Record<string, {
+        default: MauthThemePackage;
+    }>;
+    /** 配色元信息 + tokens：`./<包>/<设备>/<页面>/colors/<配色>/index.ts` */
+    colors: Record<string, {
+        default: MauthThemeColor;
+    }>;
+    /** 附加样式（惰性，取编译后的 CSS 字符串）：`.../theme.scss` */
+    styles: Record<string, () => Promise<string>>;
+}
+/**
+ * 把三个加载表构建成一张配色注册表
+ *
+ * @param modules 虚拟模块 `virtual:theme` 的三个加载表
+ * @param onWarn  构建期告警回调（可选；内核默认静默以保持零依赖，宿主传 `console.warn`）
+ */
+export declare function buildThemeRegistry(modules: ThemeAssetModules, onWarn?: (msg: string) => void): Map<string, MauthThemeRecord>;
+/** 装入一张已构建好的配色注册表（宿主在启动时调一次） */
+export declare function installThemeRegistry(registry: Map<string, MauthThemeRecord>): void;
+/** 当前有哪些配色（可选按设备过滤；不传则返回全部） */
+export declare function listThemes(device?: string): MauthThemeMeta[];
+/**
+ * 列出某个包下的全部配色（按 id 去重、按目录名排序）
+ *
+ * 🔴 排序只按 id 字母序（`black < blue < cyan < rainbow < white`），不给黑白特权。
+ * 🔴 view ≡ pkg，所以本函数只列「当前包」下的配色。
+ */
+export declare function listColorsOf(device: string, page: string, pkg: string): MauthThemeMeta[];
+/** 某配色在指定归属下的明暗系别；未登记返回 null */
+export declare function toneOfColor(id: string, device: string, page: string, pkg: string): ThemeTone | null;
+/** 某配色的系别（任意登记处）；给"槽归位"这类没有明确范围的场景用 */
+export declare function toneOfAnyScope(id: string): ThemeTone | null;
+/** 某个版式下、指定系别的全部配色 id（按目录名排序） */
+export declare function listColorIdsOfTone(device: string, page: string, pkg: string, tone: ThemeTone): string[];
+/** 归一化并校验外部传入的配色 id（URL 参数 / 后端下发） */
+export declare function resolveThemeId(raw: unknown, device?: string, page?: string, pkg?: string): string | null;
+/**
+ * 取配色记录
+ *
+ * 回退链：指定 id（四段都匹配）→ 同系别首套 → 该范围兜底 → 空记录。
+ *
+ * 🔴 内核不设「默认设备」（默认设备是哪台是宿主的词汇表），所以 `device` **必填**
+ *    （无默认值）。宿主在 re-export 壳里补齐自己的默认设备。
+ *
+ * 🔴 命名参数对象（2026-10-17 收口）：此前 `(id, device, pkg, page)` 与宿主
+ *    `themeRecordFor(pkg, device, page)` 参数顺序不一致（中间三段对着，但首尾互换），
+ *    调用点传错只会有「配色找错范围」这种无从归因的症状。现在改为对象，名字即语义。
+ */
+export declare function getThemeRecord(params: {
+    id: string;
+    device: string;
+    pkg?: string;
+    page?: string;
+}): MauthThemeRecord;
+/** 该范围内默认用哪套配色；无配色时返回 null */
+export declare function getDefaultThemeId(params: {
+    device: string;
+    page?: string;
+    pkg?: string;
+}): string | null;
+/** 该配色是否登记过（限定哪几段就要求哪几段匹配） */
+export declare function isKnownTheme(id: unknown, device?: string, page?: string, pkg?: string): boolean;
+/** 某设备某页面下有哪些包登记了配色（面板要按包分组） */
+export declare function listColorViews(device: string, page: string): string[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAM5D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAC;IACzD,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,eAAe,CAAA;KAAE,CAAC,CAAC;IACrD,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;CAC/C;AA2DD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAe,GACvC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAiE/B;AAcD,gCAAgC;AAChC,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,IAAI,CAElF;AAmDD,+BAA+B;AAC/B,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CAG5D;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,CAQxF;AAED,gCAAgC;AAChC,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,SAAS,GAAG,IAAI,CAElB;AAED,uCAAuC;AACvC,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAK3D;AAED,iCAAiC;AACjC,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,GACd,MAAM,EAAE,CAQV;AAED,sCAAsC;AACtC,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,gBAAgB,CAgBnB;AAED,8BAA8B;AAC9B,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,GAAG,IAAI,CAEhB;AAED,8BAA8B;AAC9B,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/F;AAGD,gCAAgC;AAChC,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQrE"}