skinsuite 0.1.0 → 0.2.1

package/src/constants.ts

@@ -1,100 +1,141 @@
-/**
- * 主题内核的**常量与白名单** —— 设备 / 页面 / 包 / 配色的取值集合
- *
- * 这些值原先散在 `oauth21/src/theme/index.ts`，2026-09-26 抽包 Stage 1 移到这里。
- * 它们是**跨层共享的词汇表**：配色注册表、版式注册表工厂、参数读取、store、
- * 以及目录口径关卡（`.tmp-probe/verify-theme-dirs.mjs`）全部按这几个常量对齐，
- * 所以必须**只有一个来源** —— 改这里，其余各处跟着变。
- *
- * ⚠️ 本文件**零依赖**（不 import 任何东西），也不碰 DOM / 构建器 / 路由：
- *    这是 `skinsuite` 能被任意前端复用的前提（见
- *    docs/frontend/theme-package-extraction.md 的「〇、一条原则」）。
- *
- * @author yijiu2025
- */
-
-/**
- * 目录名 / id 的白名单正则
- *
- * 同时作用于**主题包名**、**配色 id**、**版式 id**、**页面名** —— 它们都会进
- * `data-*` 属性与 CSS 属性选择器，因此只允许小写字母、数字、短横线。
- * 不合规的目录**静默跳过**（一个写坏的目录不该让整页起不来），所以排查
- * "加了主题没生效"时，第一件事就是核这条正则。
- */
-export const THEME_ID_RE = /^[a-z0-9-]+$/;
-
-/**
- * 空记录（registered 目录尚未产出任何记录）的占位配色 id
- *
- * ⚠️ 它**不再**表示"默认配色"：自 2026-09-24 起黑白是各设备下**具名的正式配色**
- * （`<页面>/colors/{black,white}/`）。**默认配色**是下面的 `DEFAULT_THEME_COLOR`。
- * 这里只用于空记录占位。
- */
-export const DEFAULT_THEME_ID = 'default';
-
-/**
- * 内置默认**主题包** id
- *
- * 它用在版式侧：该包的版式由容器**静态引入**（首屏零请求），其它包才需要惰性加载。
- * 见 `theme/views/registry.ts`。
- */
-export const DEFAULT_THEME_PACKAGE = 'default';
-
-/**
- * 设备维度：**取值集合由宿主的设备清单声明**，内核不再自带一份
- *
- * === 为什么从这里搬走（2026-09-27）===
- * 内核原先写着 `THEME_DEVICES = ['mobile','standard','mini']` —— 那是**某个应用的**
- * 词汇表，不是机制的一部分。它带来的实际代价是"加一种设备要改好几处"，而其中一处
- * 在包里、另外几处在宿主（判定、容器、路由、面板），漏一处就是静默的半生效。
- * 现在：
- *   • 内核只留「设备名是个 `[a-z0-9-]` 字符串」这一条**形态**约定；
- *   • 取值集合、中文名、判定规则、容器位置，全部在宿主的设备清单里声明
- *     （本仓 = `oauth21/src/theme/devices.ts`）。
- * 内核因此可以在任何前端被复用 —— 那个前端有几台设备、叫什么，与内核无关。
- *
- * ⚠️ 内核里所有"需要知道设备取值集合"的函数都已改成**接收它**（而不是查常量）：
- *    白名单校验在宿主（`asThemeDevice`），设备维度参数读取只需要"当前设备是谁"。
- */
-
-/**
- * 兜底页面：注册表类函数在调用点没给页面时的默认值
- *
- * 取 `login` 是因为它是认证流程的默认入口（未指定页面时最可能问的就是它）。
- * 有明确页面的调用点（容器、面板）都应显式传 `page`，不要依赖这个兜底。
- */
-export const DEFAULT_THEME_PAGE = 'login';
-
-/**
- * 兜底**配色** id：该范围内没有更具体的指定时用它（2026-09-26 定）
- *
- * 用户口径：**默认版式 = `default` 包，默认配色 = `white`**。
- * 配色注册表先找它；只有该范围里根本没有这套色（如以后某个版式只提供一套自命名的
- * 配色）才退回「该范围 id 字母序第一」。
- *
- * ⚠️ 在它之前，兜底口径是"字母序第一"，而 `black < blue < cyan < rainbow < white`
- *    → "默认外观"实际落在**黑系**，再靠首屏系别对齐纠正成白系。"两步走"有两个坑：
- *      ① 语义撕裂：基线 SCSS 的 `:root` 是浅底，兜底却是深色配色；
- *      ② **静默事故**：新增一个比 `black` 更靠前的配色 id（如 `amber`）会改掉默认外观。
- *    写死成 `white` 后，"默认"是一个**可读的显式值**，不再依赖命名巧合。
- */
-export const DEFAULT_THEME_COLOR = 'white';
-
-/**
- * 兜底**暗系**配色 id：明暗联动切到「暗」时的标配
- *
- * 与 `DEFAULT_THEME_COLOR` 成对（用户 2026-09-25 定：切「明」→白系、切「暗」→黑系）。
- * 该范围内没有它时退回**该系别**字母序第一套，绝不跨系别硬凑。
- */
-export const DEFAULT_THEME_DARK_COLOR = 'black';
-
-/**
- * 基础版式的**逻辑** id（与版式注册表工厂的默认 `baseId` 是同一约定值）
- *
- * ⚠️ 它**不是**配色注册表里的 view 值：配色记录里的 view 段恒等于包名
- * （一个主题包 = 一种版式），`'base'` 永远不会出现在配色键里。
- * 外部 `?view=base` 由版式选择器归一化到当前包名，到不了配色注册表。
- *
- * 保留它只是为了版式工厂的默认值；新增代码不要拿它当配色查找的 view 参数。
- */
-export const BASE_VIEW_ID = 'base';
+/**
+ * 主题内核的**常量与白名单** —— 设备 / 页面 / 包 / 配色的取值集合
+ *
+ * 这些值原先散在 `oauth21/src/theme/index.ts`，2026-09-26 抽包 Stage 1 移到这里。
+ * 它们是**跨层共享的词汇表**：配色注册表、版式注册表工厂、参数读取、store、
+ * 以及目录口径关卡（`.tmp-probe/verify-theme-dirs.mjs`）全部按这几个常量对齐，
+ * 所以必须**只有一个来源** —— 改这里，其余各处跟着变。
+ *
+ * ⚠️ 本文件**零依赖**（不 import 任何东西），也不碰 DOM / 构建器 / 路由：
+ *    这是 `skinsuite` 能被任意前端复用的前提（见
+ *    docs/standards/theme-package-extraction.md 的「〇、一条原则」）。
+ *
+ * @author yijiu2025
+ */
+
+/**
+ * 目录名 / id 的白名单正则
+ *
+ * 同时作用于**主题包名**、**配色 id**、**版式 id**、**页面名** —— 它们都会进
+ * `data-*` 属性与 CSS 属性选择器，因此只允许小写字母、数字、短横线。
+ * 不合规的目录**静默跳过**（一个写坏的目录不该让整页起不来），所以排查
+ * "加了主题没生效"时，第一件事就是核这条正则。
+ */
+export const THEME_ID_RE = /^[a-z0-9-]+$/;
+
+/**
+ * 空记录（registered 目录尚未产出任何记录）的占位配色 id
+ *
+ * ⚠️ 它**不再**表示"默认配色"：自 2026-09-24 起黑白是各设备下**具名的正式配色**
+ * （`<页面>/colors/{black,white}/`）。**默认配色**是下面的 `DEFAULT_THEME_COLOR`。
+ * 这里只用于空记录占位。
+ */
+export const DEFAULT_THEME_ID = 'default';
+
+/**
+ * 内置默认**主题包** id
+ *
+ * 它用在版式侧：该包的版式由容器**静态引入**（首屏零请求），其它包才需要惰性加载。
+ * 见 `theme/views/registry.ts`。
+ */
+export const DEFAULT_THEME_PACKAGE = 'default';
+
+/**
+ * 设备维度：**取值集合由宿主的设备清单声明**，内核不再自带一份
+ *
+ * === 为什么从这里搬走（2026-09-27）===
+ * 内核原先写着 `THEME_DEVICES = ['mobile','standard','mini']` —— 那是**某个应用的**
+ * 词汇表，不是机制的一部分。它带来的实际代价是"加一种设备要改好几处"，而其中一处
+ * 在包里、另外几处在宿主（判定、容器、路由、面板），漏一处就是静默的半生效。
+ * 现在：
+ *   • 内核只留「设备名是个 `[a-z0-9-]` 字符串」这一条**形态**约定；
+ *   • 取值集合、中文名、判定规则、容器位置，全部在宿主的设备清单里声明
+ *     （本仓 = `oauth21/src/theme/devices.ts`）。
+ * 内核因此可以在任何前端被复用 —— 那个前端有几台设备、叫什么，与内核无关。
+ *
+ * ⚠️ 内核里所有"需要知道设备取值集合"的函数都已改成**接收它**（而不是查常量）：
+ *    白名单校验在宿主（`asThemeDevice`），设备维度参数读取只需要"当前设备是谁"。
+ */
+
+/**
+ * 兜底页面：注册表类函数在调用点没给页面时的默认值
+ *
+ * 取 `login` 是因为它是认证流程的默认入口（未指定页面时最可能问的就是它）。
+ * 有明确页面的调用点（容器、面板）都应显式传 `page`，不要依赖这个兜底。
+ */
+export const DEFAULT_THEME_PAGE = 'login';
+
+/**
+ * 兜底**配色** id：该范围内没有更具体的指定时用它（2026-09-26 定）
+ *
+ * 用户口径：**默认版式 = `default` 包，默认配色 = `white`**。
+ * 配色注册表先找它；只有该范围里根本没有这套色（如以后某个版式只提供一套自命名的
+ * 配色）才退回「该范围 id 字母序第一」。
+ *
+ * ⚠️ 在它之前，兜底口径是"字母序第一"，而 `black < blue < cyan < rainbow < white`
+ *    → "默认外观"实际落在**黑系**，再靠首屏系别对齐纠正成白系。"两步走"有两个坑：
+ *      ① 语义撕裂：基线 SCSS 的 `:root` 是浅底，兜底却是深色配色；
+ *      ② **静默事故**：新增一个比 `black` 更靠前的配色 id（如 `amber`）会改掉默认外观。
+ *    写死成 `white` 后，"默认"是一个**可读的显式值**，不再依赖命名巧合。
+ */
+export const DEFAULT_THEME_COLOR = 'white';
+
+/**
+ * 兜底**暗系**配色 id：明暗联动切到「暗」时的标配
+ *
+ * 与 `DEFAULT_THEME_COLOR` 成对（用户 2026-09-25 定：切「明」→白系、切「暗」→黑系）。
+ * 该范围内没有它时退回**该系别**字母序第一套，绝不跨系别硬凑。
+ */
+export const DEFAULT_THEME_DARK_COLOR = 'black';
+
+/**
+ * 主题包目录的**结构契约** —— 「目录长什么样」的唯一来源
+ *
+ * === 为什么要有它（2026-10-17）===
+ * 目录骨架原先是一份**隐式约定**，散在三个形态各异的实现里：
+ *   • 构建插件的 `scan()`：嵌套 for 循环 + 写死的 `'colors'` 字符串
+ *   • 注册表的 `colorFromKey()`：正则 `\./([^/]+)/([^/]+)/([^/]+)/colors/([^/]+)/…`
+ *   • `types.ts` 的注释 ASCII 树
+ * 三处各自维护对同一件事的认知。改目录结构（比如配色下再分 `tone` 层、或
+ * `colors` 改名）时，只要漏改一处，就出现**静默扫不到主题**这种无从归因的脱节
+ * （扫描是"读不到就跳过"，不报错）——与「设备词汇表散落四处」是同一类坑。
+ *
+ * 现在收敛成下面这一组常量：**段序列 + 固定字面段 + 叶子文件名**。构建插件扫描
+ * 目录、注册表解析键，都从这里派生，不再各自手写。
+ *
+ * === 它**只**承诺「结构形态」，不承诺「取值集合」===
+ * 段里 `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 THEME_DIR_LEVELS = ['pkg', 'device', 'page', 'colorId'] as const;

package/src/index.ts

@@ -1,65 +1,128 @@
-/**
- * `skinsuite` 的**唯一公开出口**
- *
- * === 这里装什么 ===
- * 主题机制里**与业务、与框架都无关**的那一半：取值白名单、契约类型、系别/明暗取值、
- * 设备维度参数读取、token 形态与校验。它是纯函数 + 数据，可以在任何前端（Vue / React /
- * 单测 / 将来的 SSR）里被同一套代码驱动。
- *
- * ### 不在这里装什么（重要）
- *   • **DOM 与注入**（`documentElement`、`localStorage`、`matchMedia`）→ 由宿主适配器提供
- *   • **构建器耦合**（`import.meta.glob` / `import.meta.env`）→ 由宿主适配器提供
- *   • **路由**（vue-router）→ 应用自己的世界观
- *   • **业务资产**（`themes/**` 的版式与配色实现）→ 随应用走
- * 见 `docs/frontend/theme-package-extraction.md` 的「〇、一条原则」与「五、四个注入点契约」。
- *
- * === 为什么用显式具名导出，而不是 `export *` ===
- * 立项文档 §四 有一张"公开 API 面"的表，本文件就是那张表的**落地**：表里没有的名字
- * 就不该从这里出去（如内部用的正则、解析器）。用 `export *` 会让"包到底承诺了什么"
- * 变成一份隐式清单，加一个内部导出就悄悄扩大了对外承诺。
- * 代价是新增导出要手工补一行 —— 这是刻意的摩擦。
- *
- * ⚠️ 相对 import **必须带 `.js` 后缀**（`from './tone.js'` 而不是 `'./tone'`）：
- *    包以 `moduleResolution: NodeNext` 编译到 `dist/`，TS 会把 `.js` 映射回 `.ts` 源码，
- *    而**产物**里的相对说明符是原样保留的 —— 不带后缀的话浏览器与 Node 的原生 ESM
- *    都解析不到。Vite / webpack 侧的别名消费源码时同样认这条 TS 约定，所以不用改两遍。
- *
- * ⚠️ 公开面一旦发出就是承诺：改名/删名要先想清楚下游（当前只有 `oauth21` 一个消费者，
- *    所以现在改是免费的，见立项文档 §八）。
- *
- * @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 {
-  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 { DEVICE_SCOPED_PARAMS, readDeviceParam } from './views/params.js';
-export type { DeviceScopedParam } from './views/params.js';
+/**
+ * `skinsuite` 的**唯一公开出口**
+ *
+ * === 这里装什么 ===
+ * 主题机制里**与业务、与框架都无关**的那一半：取值白名单、契约类型、系别/明暗取值、
+ * 设备维度参数读取、token 形态与校验。它是纯函数 + 数据，可以在任何前端（Vue / React /
+ * 单测 / 将来的 SSR）里被同一套代码驱动。
+ *
+ * ### 不在这里装什么（重要）
+ *   • **DOM 与注入**（`documentElement`、`localStorage`、`matchMedia`）→ 由宿主适配器提供
+ *   • **构建器耦合**（`import.meta.glob` / `import.meta.env`）→ 由宿主适配器提供
+ *   • **路由**（vue-router）→ 应用自己的世界观
+ *   • **业务资产**（`themes/**` 的版式与配色实现）→ 随应用走
+ * 见 `docs/standards/theme-package-extraction.md` 的「〇、一条原则」与「五、四个注入点契约」。
+ *
+ * === 为什么用显式具名导出，而不是 `export *` ===
+ * 立项文档 §四 有一张"公开 API 面"的表，本文件就是那张表的**落地**：表里没有的名字
+ * 就不该从这里出去（如内部用的正则、解析器）。用 `export *` 会让"包到底承诺了什么"
+ * 变成一份隐式清单，加一个内部导出就悄悄扩大了对外承诺。
+ * 代价是新增导出要手工补一行 —— 这是刻意的摩擦。
+ *
+ * ⚠️ 相对 import **必须带 `.js` 后缀**（`from './tone.js'` 而不是 `'./tone'`）：
+ *    包以 `moduleResolution: NodeNext` 编译到 `dist/`，TS 会把 `.js` 映射回 `.ts` 源码，
+ *    而**产物**里的相对说明符是原样保留的 —— 不带后缀的话浏览器与 Node 的原生 ESM
+ *    都解析不到。Vite / webpack 侧的别名消费源码时同样认这条 TS 约定，所以不用改两遍。
+ *
+ * ⚠️ 公开面一旦发出就是承诺：改名/删名要先想清楚下游（当前只有 `oauth21` 一个消费者，
+ *    所以现在改是免费的，见立项文档 §八）。
+ *
+ * @author yijiu2025
+ */
+
+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';

package/src/manifest.ts

@@ -0,0 +1,131 @@
+/**
+ * 主题域清单（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'];
+
+const DEBUG_MODES: readonly ThemeDebugMode[] = ['off', 'url', 'always'];
+
+/**
+ * 声明并校验主题清单
+ *
+ * 与白名单常量同一口径：配置写错是开发者错误，应该在启动时就炸，
+ * 而不是等到"面板不出现"这种无从归因的现象。
+ */
+export function defineThemeManifest(manifest: ThemeManifest = {}): ResolvedThemeManifest {
+  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: ResolvedThemeDebug,
+  query: Readonly<Record<string, unknown>>
+): boolean {
+  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: ResolvedThemeManifest | null | undefined
+): ResolvedThemeManifest {
+  return manifest ?? defineThemeManifest({});
+}
+
+/**
+ * 模块级清单单例 —— 「清单从哪来」的收口点
+ *
+ * 与配色注册表（`installThemeRegistry`）同一范式：`virtual:theme` 虚拟模块被 import 的
+ * 那一刻（模块求值期副作用）把 resolve 后的清单装进来，之后内核各处（调试面板可见性）
+ * 直接读本单例，**无需宿主 import `virtual:theme` 再转发**。
+ * 未装入时为机制默认（面板 `url` 档），而不是让应用起不来。
+ */
+let themeManifestSingleton: ResolvedThemeManifest = defineThemeManifest({});
+
+/** 装入已解析的清单（`virtual:theme` 自动装配时调一次） */
+export function installThemeManifest(manifest: ResolvedThemeManifest): void {
+  themeManifestSingleton = manifest;
+}
+
+/** 当前清单单例（调试面板可见性用） */
+export function themeManifest(): ResolvedThemeManifest {
+  return themeManifestSingleton;
+}