skinsuite 0.1.0 → 0.2.0

package/src/vue/theme-store.ts

@@ -0,0 +1,58 @@
+/**
+ * 主题 store 的**结构类型**（库侧约定）+ provide / inject 键
+ *
+ * 库（skinsuite/vue）不能 import 宿主的 Pinia store（边界），所以只约定一个**结构类型**：
+ * 宿主的 `useThemeStore()` 只要结构兼容这几项，就能直接传给 `<ThemeRoot :themeStore>`。
+ * `<ThemeRoot>` 再 `provide` 出去，`<ThemeView>` / `<ThemeDebugPanel>` 用 `inject` 拿到 ——
+ * 这是「库不依赖宿主、但宿主事实要注入」的标准手法。
+ *
+ * === 为什么是这些字段 ===
+ *   · `isDark`             → ThemeRoot 挂 `.dark` 类（纯外观）
+ *   · `packageId`          → ThemeView / 面板选版式的「在哪个包里找」
+ *   · `viewFor(page)`      → 主题包声明档（`views.<page>`）这一档
+ *   · `setActivePageView`  → ThemeView 告知 store「当前页 + 版式」（配色挂在版式下）
+ *   · `activePage`         → 面板展示当前页
+ *   · `themeId` / `mode`   → 面板展示 / 切换配色与明暗
+ *   · `themeRecordFor`     → 面板算「生效配色」（含 URL 设备覆盖，device 参数化）
+ *   · `setTheme` / `setMode` → 面板写侧（点色卡 / 切明暗）
+ *
+ * 字段用**只读标量**（非 ref）：宿主 Pinia store 返回的 ref/computed 会被 Pinia 自动解包，
+ * 在 store 实例上直接读值即可，且读进 computed/watch 时仍保持响应式追踪。
+ * 方法用**方法签名**（method shorthand）而非函数类型属性：这样 TS 对参数做双变检查，
+ * 宿主的窄类型（如 `ThemeDevice`）能直接兼容库声明的宽类型（`string`）。
+ *
+ * @author yijiu2025
+ * @since 2026-10-18
+ */
+import type { InjectionKey } from 'vue';
+import type { ThemeMode } from '../scheme';
+
+/** 主题 store 的结构契约（宿主 store 结构兼容即可传） */
+export interface ThemeStoreLike {
+  /** 当前生效主题包名（= 版式 id，一个包一种版式） */
+  readonly packageId: string;
+  /** 当前是否深色（= 生效配色的系别） */
+  readonly isDark: boolean;
+  /** 当前生效页面名 */
+  readonly activePage: string;
+  /** 全局配色意图（用户显式选过的 id） */
+  readonly themeId: string;
+  /** 明暗意图 */
+  readonly mode: ThemeMode;
+  /** 某页当前声明式版式 id（主题包 `views.<page>` 声明；无声明返回 undefined） */
+  viewFor(page: string, device?: string): string | undefined;
+  /** 告知 store「当前是哪一页、哪套版式」（配色挂在版式下，token 注入依赖它） */
+  setActivePageView(page: string, viewId: string): void;
+  /** 按包/设备/页解析生效配色记录（含 URL 设备覆盖；面板只要 `meta.id` 与 `tone`） */
+  themeRecordFor(pkg?: string, device?: string, page?: string): {
+    meta: { id: string };
+    tone?: string;
+  };
+  /** 设置配色（落盘；面板点色卡用） */
+  setTheme(id: string): void;
+  /** 设置明暗意图（面板切明暗用） */
+  setMode(mode: ThemeMode): void;
+}
+
+/** `provide`/`inject` 用的键（`<ThemeRoot>` provide，`<ThemeView>` / `<ThemeDebugPanel>` inject） */
+export const themeStoreKey: InjectionKey<ThemeStoreLike> = Symbol('mauth.themeStore');

package/src/vue/theme-views.ts

@@ -0,0 +1,39 @@
+/**
+ * 版式加载表（`themeViews`）的**运行时单例** —— 构建产物 → 运行时的手递手收口点
+ *
+ * === 它解决什么 ===
+ * 页面契约文件（`views/<page>.ts`）需要「本页有哪些版式组件」才能建注册表，而这份清单
+ * 来自构建期插件扫出的虚拟模块 `virtual:theme` 的 `themeViews`。若页面文件直接
+ * `import { themeViews } from 'virtual:theme'`，则「页面契约 → virtual:theme」这一条依赖
+ * 会在 `virtual:theme` 反过来副作用 import 页面契约时形成循环（页面文件在 `themeViews`
+ * 求值前读到 undefined）。
+ *
+ * 所以这里采用与配色注册表（`installThemeRegistry`）、清单（`installThemeManifest`）同一
+ * 范式：`virtual:theme` 模块体把 `themeViews` **装入本单例**，`defineThemePage` 只在**取名
+ * 的那一刻**（渲染期）从这里取 loader —— 注册时零依赖、永不踩循环。
+ *
+ * === 为什么不在纯内核 `skinsuite`，而在 `skinsuite/vue` ===
+ * `themeViews` 的装载器返回 Vue `Component`，纯内核零 Vue 依赖，装不下这份类型。
+ *
+ * @author yijiu2025
+ * @since 2026-10-18
+ */
+import type { ViewModuleMap } from './view-registry';
+
+/** 模块级版式加载表单例（`virtual:theme` 装入；未装入时为空表，查询走空兜底） */
+let themeViewsSingleton: Record<string, ViewModuleMap> = {};
+
+/** 装入版式加载表（`virtual:theme` 自动装配时调一次） */
+export function installThemeViews(views: Record<string, ViewModuleMap>): void {
+  themeViewsSingleton = views;
+}
+
+/** 按页面名取该页的版式加载表；未装入 / 未登记返回空表（建空注册表，不抛错） */
+export function themeViewsFor(page: string): ViewModuleMap {
+  return themeViewsSingleton[page] ?? {};
+}
+
+/** 重置模块级单例（单测 / HMR 用） */
+export function resetThemeViews(): void {
+  themeViewsSingleton = {};
+}

package/src/vue/token-runtime.ts

@@ -0,0 +1,81 @@
+/**
+ * 主题 token 运行时（**DOM 注入半边**）—— 把分层 token 校验后注入为 CSS 变量（内核版）
+ *
+ * === 分层与优先级（低 → 高）===
+ *   1. SCSS 基线          :root / html.dark / 断点块
+ *   2. 主题包 tokens      getThemeRecord(...).tokens
+ *   3. 外部覆写 tokens    后端下发 / 父应用同步
+ * 第 2、3 层都写在根节点的 inline style 上，层间顺序靠**写入顺序**保证。
+ *
+ * === 为什么校验（细节见 `skinsuite` 的 `tokens.ts`）===
+ * CSS 自定义属性能直接改变渲染，未校验就 `setProperty` 等于把 CSS 注入的口子交给
+ * 后端或父页面。所以走白名单（`sanitizeOverrides`，纯函数已在内核 `skinsuite`）。
+ *
+ * === 为什么本文件在 Vue 绑定层、而非纯内核 ===
+ * 它操作 `document.documentElement`（DOM），纯内核 `skinsuite` 刻意零 DOM。
+ * 校验函数（`sanitizeOverrides`）已在纯内核，这里只保留「往 DOM 写」这个动作本身。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（从 oauth21/src/theme/runtime.ts 下沉）
+ */
+import { sanitizeOverrides } from '../tokens';
+import type { ThemeTokenLayers, ThemeTokenOverrides } from '../tokens';
+
+/** 上一次注入到 inline style 的变量名，用于下次注入前清理 */
+let injectedNames: string[] = [];
+
+/** 清掉上一次注入的所有主题变量 */
+export function clearThemeTokens(): void {
+  const root = document.documentElement;
+  for (const name of injectedNames) root.style.removeProperty(name);
+  injectedNames = [];
+}
+
+/**
+ * 应用分层 token（主题包 + 外部覆写）
+ *
+ * 每次调用都是「把两层重算一遍，再与上一轮的变量名做差集清理」：
+ *   · 换配色时不会残留上一轮的值
+ *   · 只动自己写过的变量名，不碰别人留在 html 上的 inline style
+ * 层内顺序：先 theme 后 external，同名后者胜（「后端覆写压过主题默认」）。
+ */
+export function applyThemeLayers(layers: ThemeTokenLayers): string[] {
+  const theme = sanitizeOverrides(layers.theme);
+  const external = sanitizeOverrides(layers.external);
+
+  const root = document.documentElement;
+  const nextNames = new Set([...Object.keys(theme.tokens), ...Object.keys(external.tokens)]);
+  for (const name of injectedNames) {
+    if (!nextNames.has(name)) root.style.removeProperty(name);
+  }
+
+  // 🔴 去重：theme 层与 external 层**同名** token 时（external 压过 theme），
+  //    同一变量会被 setProperty 两次（后者胜是设计行为），但注入名单里不该有重复名。
+  const applied = new Set<string>();
+  for (const [name, value] of Object.entries(theme.tokens)) {
+    root.style.setProperty(name, value);
+    applied.add(name);
+  }
+  for (const [name, value] of Object.entries(external.tokens)) {
+    root.style.setProperty(name, value);
+    applied.add(name);
+  }
+  injectedNames = [...applied];
+
+  return [...theme.rejected, ...external.rejected];
+}
+
+/** 只应用外部覆写（等价于 applyThemeLayers({ external })） */
+export function applyThemeTokens(overrides: ThemeTokenOverrides | null): string[] {
+  return applyThemeLayers({ external: overrides });
+}
+
+/** 当前已注入的变量名（供验收脚本与单测断言注入是否真的发生） */
+export function getInjectedTokenNames(): readonly string[] {
+  return injectedNames;
+}
+
+/** 重置模块级状态（HMR / 单测用） */
+export function resetThemeRuntime(): void {
+  clearThemeTokens();
+}

package/src/vue/types.ts

@@ -0,0 +1,67 @@
+/**
+ * 调试面板的**数据契约**
+ *
+ * 面板被抽进主题库后，就不能再自己 `useRoute()` / `useThemeStore()` 了 ——
+ * 那是宿主的框架与业务。现在它只认这份契约：**宿主算好模型、给出动作**，
+ * 面板负责渲染与交互。于是：
+ *   • 任何前端（乃至别的框架包壳）都能复用同一个面板；
+ *   • 面板的行为可以在单测里用一组假数据完整覆盖，不需要起真路由。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17
+ */
+import type { ThemeMode, ThemeTone } from '../scheme';
+
+/** 一张色卡 */
+export interface ThemeDebugColor {
+  /** 配色 id（目录名） */
+  id: string;
+  /** 中文显示名 */
+  name: string;
+  /** 系别（白系 / 黑系） */
+  tone: ThemeTone;
+  /** 色卡底色（`#rrggbb`）；缺省用中性灰兜底 */
+  preview?: string;
+}
+
+/** 面板要渲染的**全部**状态 */
+export interface ThemeDebugModel {
+  /** 当前页面名；该页未接入版式机制时留空（面板不显示版式行） */
+  page?: string;
+  /** 可选设备清单（宿主声明） */
+  devices: readonly string[];
+  /** 设备显示名；缺省直接用 id */
+  deviceLabels?: Readonly<Record<string, string>>;
+  /** 当前**生效**设备（渲染形态决定的那个） */
+  device: string;
+  /** 面板手动覆盖的设备；`null` = 跟随页面 */
+  deviceOverride: string | null;
+  /** 当前页可选版式（= 可选主题包） */
+  views: string[];
+  /** 当前生效版式 */
+  view: string;
+  /** 该页还有哪些版式挂了配色（用于提示"切过去颜色会变"） */
+  viewsWithColors?: string[];
+  /** 当前版式支持的配色 */
+  colors: ThemeDebugColor[];
+  /** 当前**生效**配色 id */
+  color: string;
+  /** 用户显式选过、但当前作用域落不到它时用于「选择 → 生效」提示 */
+  selectedColor?: string;
+  /** 明暗意图 */
+  mode: ThemeMode;
+}
+
+/** 面板能触发的**全部**动作 */
+export interface ThemeDebugActions {
+  /** 覆盖设备；传 `null` 表示跟随页面 */
+  pickDevice(device: string | null): void;
+  /** 切换版式（宿主负责改 URL，面板不碰路由） */
+  pickView(id: string): void;
+  /** 切换配色 */
+  pickColor(id: string): void;
+  /** 切换明暗意图 */
+  pickMode(mode: ThemeMode): void;
+  /** 恢复默认 */
+  reset(): void;
+}

package/src/vue/useParentThemeSync.ts

@@ -0,0 +1,99 @@
+/**
+ * 父应用主题同步（iframe 嵌入场景）
+ *
+ * 父应用（posecraft / firewall）切主题时，通过 `postMessage` 通知子应用
+ * （被嵌在 iframe 里的登录页）同步切换，解决 iframe 隔离导致的父子主题不同步。
+ *
+ * === 消息协议 ===
+ * ```
+ * { type: 'THEME_CHANGE', isDark: boolean }                        // 旧版：只同步明暗
+ * { type: 'THEME_CHANGE', isDark?, theme?, skin?, tokens? }        // 新版：可同时换主题
+ * ```
+ * `theme` 是配色 id；`skin` 是它的旧字段名（两者等价）。
+ * `tokens` 是一组**扁平**的 CSS 变量覆写表，实现「父应用给子页面定制每个组件」。
+ * 旧的 `{ light, dark }` 两档结构不再接受 —— 配色自带完整底色，明暗档已取消。
+ *
+ * ⚠️ `tokens` 的每一项都会过白名单校验（token 名 + 取值形态），不合规的丢弃并告警。
+ *    父页面虽然是受信来源，但 postMessage 的载荷在浏览器里终究是外部输入，
+ *    未校验就写进 CSS 变量等于开了 CSS 注入的口子（`url()` 一律被拒）。
+ *    校验发生在宿主的 store / runtime 层，本模块只做**协议解析与分发**。
+ *
+ * === 为什么 origin 白名单是宿主的参数 ===
+ * 「哪些父应用可信」是部署事实（域名、端口、是否 https），库无从知道。
+ * 所以这里只调用宿主给的 `isAllowedOrigin`；库负责的是「什么时候问、问什么」。
+ *
+ * @example
+ * ```ts
+ * useParentThemeSync({
+ *   isAllowedOrigin: isAllowedParentOrigin,
+ *   apply: config => themeStore.applyThemeConfig(config),
+ *   applyDark: dark => themeStore.applyTheme(dark)
+ * });
+ * ```
+ *
+ * @author yijiu2025
+ * @since 2026-08-30
+ */
+import type { RemoteThemeConfig } from '../scheme';
+
+/** 宿主适配器 */
+export interface ParentThemeSyncOptions {
+  /** 该 origin 是否可信（宿主维护白名单） */
+  isAllowedOrigin(origin: string): boolean;
+  /** 收到配色 / tokens 变更 */
+  apply(config: RemoteThemeConfig): void;
+  /**
+   * 收到明暗变更（旧协议兼容）
+   *
+   * 不传则忽略旧协议的 `isDark` 字段 —— 宿主若已把明暗纳入 `apply({mode})`，
+   * 可以只实现一个入口。
+   */
+  applyDark?(dark: boolean): void;
+}
+
+/**
+ * 监听父应用的主题同步消息（**立即注册**，返回 cleanup）
+ *
+ * 仅在 iframe 嵌入时生效（`handleMessage` 内判断顶层窗口无父则忽略）。
+ * 不依赖组件生命周期（`onMounted`/`onUnmounted`）：来源同步已归主题运行时
+ * （宿主 store 的 runtime），那里没有组件实例，改用「立即 addEventListener +
+ * 返回 cleanup」，由宿主在 store 的 dispose 里调 cleanup。
+ */
+export function useParentThemeSync(options: ParentThemeSyncOptions): () => void {
+  function handleMessage(event: MessageEvent): void {
+    // 顶层窗口无父，忽略（非 iframe 场景）
+    if (!(window.parent && window.parent !== window)) return;
+
+    // origin 校验：只接受白名单父应用的消息（防恶意嵌入伪造主题切换）
+    if (!options.isAllowedOrigin(event.origin)) return;
+
+    const { type, isDark, theme, skin, tokens } = (event.data ?? {}) as {
+      type?: unknown;
+      isDark?: unknown;
+      theme?: unknown;
+      skin?: unknown;
+      tokens?: unknown;
+    };
+    if (type !== 'THEME_CHANGE') return;
+
+    // 明暗：新旧协议都支持
+    if (typeof isDark === 'boolean' && options.applyDark) {
+      options.applyDark(isDark);
+    }
+
+    // 主题与组件级覆写（新协议）。`skin` 是 `theme` 的旧字段名，历史父应用仍能生效。
+    const wanted = typeof theme === 'string' ? theme : typeof skin === 'string' ? skin : undefined;
+    if (wanted !== undefined || (tokens && typeof tokens === 'object')) {
+      options.apply({
+        theme: wanted,
+        tokens:
+          tokens && typeof tokens === 'object'
+            ? (tokens as RemoteThemeConfig['tokens'])
+            : undefined
+      });
+    }
+  }
+
+  window.addEventListener('message', handleMessage);
+  return () => window.removeEventListener('message', handleMessage);
+}

package/src/vue/useThemeDebugPanel.ts

@@ -0,0 +1,192 @@
+/**
+ * 调试面板的**适配器**（无参）—— 把应用状态翻译成面板的 `model` / `actions`
+ *
+ * === 无 host：一切从「域」自动取 ===
+ * 面板主体（`ThemeDebugPanelBody.vue`）是纯展示：不读路由、不读 store。但「当前是哪一页、
+ * 有哪些版式、点了之后改哪个 URL」需要宿主的 store / 路由 / 页面机制。早先这些事实靠
+ * 宿主写一个 `host` 对象注入；现在它们都已收进库内「域」，本文件**无参**地从域取：
+ *
+ *   · store       → `<ThemeRoot :themeStore>` provide，`inject`（`ThemeStoreLike`）
+ *   · 设备        → 设备域 `registeredDevices()` / `currentDevice()`（`defineThemeDevice` 自动注册）
+ *   · 页面        → 页面域 `pageOf()`（`defineThemePage` 自动注册）+ store `activePage`（ThemeView 维护）
+ *   · 配色查询    → 内核注册表单例（`listColorsOf` / `toneOfColor` / `listColorViews`）
+ *   · 路由        → 设备域（`app.use(theme, { router })` 传入）：`currentQuery()` / `replaceQuery()`
+ *
+ * 于是宿主**零接线**：App.vue 里一行 `<ThemeDebugPanel />`，其余全在库内自动完成。
+ *
+ * ⚠️ 可见性判断（清单 `debug` 开关 + `?debug=theme`）**不在本文件** —— 已移到门卫
+ *    `ThemeDebugPanel.vue`（它算 `visible` 再异步加载面板主体）。本文件只负责「显示什么」。
+ *
+ * === 为什么「生效配色」走 `store.themeRecordFor` 而不是内核 registry ===
+ * `themeRecordFor` 的语义包含「URL 设备覆盖 + 用户显式操作清除覆盖」，这是宿主的运行时
+ * 状态（`deviceTheme` 初始自 URL、之后 `setTheme` 会清掉），不是实时读 URL 能还原的。
+ * 内核 registry 只能查「给定 id 有没有、什么系别」，算不出「当前生效哪套」，所以这一处
+ * 从 store 读（其余配色清单 / 系别都走内核 registry）。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（2026-10-18 无 host 化：删 host 注入，改从域自动取）
+ */
+import { computed, inject, ref } from 'vue';
+import type { ComputedRef } from 'vue';
+import { listColorViews, listColorsOf, toneOfColor } from '../registry';
+import { readDeviceParam } from '../views/params';
+import type { ThemeDebugActions, ThemeDebugColor, ThemeDebugModel } from './types';
+import { currentDevice, currentQuery, replaceQuery } from './device-domain';
+import { pageOf } from './view-page';
+import { registeredDevices, urlKeyOf } from './define-theme-device';
+import { themeStoreKey } from './theme-store';
+import type { ThemeStoreLike } from './theme-store';
+
+/** 只把「非空字符串」当有效参数 —— query 值可能是数组 */
+function asText(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+export function useThemeDebugPanel(): {
+  model: ComputedRef<ThemeDebugModel>;
+  actions: ThemeDebugActions;
+} {
+  const store = inject<ThemeStoreLike>(themeStoreKey);
+  if (!store) {
+    throw new Error('[ThemeDebugPanel] 未注入主题 store —— 请通过 <ThemeRoot :themeStore> 提供');
+  }
+
+  /** 面板上手动指定的设备（覆盖页面判定），用于在**同一台电脑**预览另一端的配色 */
+  const deviceOverride = ref<string | null>(null);
+
+  /** 可选设备清单 + 显示名（来自设备域 `defineThemeDevice` 自动注册） */
+  const devices = registeredDevices().map(d => d.id);
+  const deviceLabels: Record<string, string> = Object.fromEntries(
+    registeredDevices().map(d => [d.id, d.label])
+  );
+
+  /** 当前生效设备：面板覆盖优先，否则用设备域判定的 */
+  const device = computed<string>(() => deviceOverride.value ?? currentDevice().value);
+
+  /** 当前生效页面：由 `<ThemeView>` 的 `setActivePageView` 维护（不再从路径反推） */
+  const activePage = computed(() => store.activePage);
+
+  /**
+   * 当前生效的**版式 id**
+   *
+   * 🔴 这个 computed 必须定义在 `viewOptions` 之前：后者求值时读它，顺序颠倒会在
+   *    首次求值时踩 TDZ（现象是面板整个不渲染）。fallback 是 `store.packageId`
+   *    而不是 `'base'`：新版式架构下 `view ≡ pkg`，`'base'` 已不是合法 view 名。
+   */
+  const activeViewId = computed(() => {
+    const registry = activePage.value ? pageOf(activePage.value)?.views : undefined;
+    if (!registry) return store.packageId;
+    const pkg = store.packageId;
+    const dev = device.value;
+    // 设备维度参数：`th_<urlKey>` 优先于 `th`（与容器 pick 同一套读取规则）
+    const fromUrl = asText(readDeviceParam(currentQuery(), 'th', urlKeyOf(dev)));
+    if (fromUrl && fromUrl !== 'base') {
+      const inCurrent = registry.resolve(fromUrl, pkg, dev);
+      if (inCurrent) return inCurrent;
+      if (registry.has(fromUrl, fromUrl, dev)) return fromUrl;
+      return pkg;
+    }
+    const declared = activePage.value ? store.viewFor(activePage.value, dev) : undefined;
+    return (declared ? registry.resolve(declared, pkg, dev) : null) ?? pkg;
+  });
+
+  /**
+   * 当前页的**可选版式**（= 可选主题包）。一个主题包 = 一种版式，所以版式清单
+   * 就是主题包清单：枚举注册表里当前设备的每个包，包名即版式 id。
+   */
+  const viewOptions = computed<string[]>(() => {
+    const registry = activePage.value ? pageOf(activePage.value)?.views : undefined;
+    if (!registry || !activePage.value) return [];
+    const seen = new Set<string>();
+    for (const { pkg, device: pkgDevice } of registry.packages()) {
+      if (pkgDevice !== device.value) continue;
+      seen.add(pkg);
+    }
+    // 当前生效 view 一定在列（即使该范围内没扫到它，例如外部强制写了未知 id）
+    if (!seen.has(activeViewId.value)) seen.add(activeViewId.value);
+    return [...seen].sort();
+  });
+
+  /** **当前版式**支持的颜色 —— 切版式后这份清单会变，正是"每版式各自选色"的落点 */
+  const colors = computed<ThemeDebugColor[]>(() => {
+    const active = activePage.value;
+    if (!active) return [];
+    return listColorsOf(device.value, active, activeViewId.value).map(meta => ({
+      id: meta.id,
+      name: meta.name,
+      tone: toneOfColor(meta.id, device.value, active, activeViewId.value) ?? 'light',
+      preview: meta.preview?.primary
+    }));
+  });
+
+  /** 该页在该设备下挂了配色的版式清单（提示"这页还有哪些版式有颜色"） */
+  const viewsWithColors = computed<string[]>(() =>
+    activePage.value ? listColorViews(device.value, activePage.value) : []
+  );
+
+  /**
+   * 当前**生效**的配色 id（含 URL 设备覆盖 + 用户显式清除覆盖的语义）——
+   * 🔴 传 `activeViewId` 作为 pkg：view ≡ pkg，否则会把 compact 包点的 blue 又落回 default 包。
+   */
+  const activeColorId = computed(
+    () => store.themeRecordFor(activeViewId.value, device.value, activePage.value).meta.id
+  );
+
+  const model = computed<ThemeDebugModel>(() => ({
+    page: activePage.value,
+    devices,
+    deviceLabels,
+    device: device.value,
+    deviceOverride: deviceOverride.value,
+    views: viewOptions.value,
+    view: activeViewId.value,
+    viewsWithColors: viewsWithColors.value,
+    colors: colors.value,
+    color: activeColorId.value,
+    selectedColor: store.themeId,
+    mode: store.mode
+  }));
+
+  const actions: ThemeDebugActions = {
+    pickDevice(id) {
+      // 面板发来的是 `devices` 里的值，这里再收一次口：越界值按"跟随页面"处理。
+      deviceOverride.value = id !== null && devices.includes(id) ? id : null;
+    },
+
+    /**
+     * 切换版式（**只改 URL 的版式键，path 不动**）
+     *
+     * 🔴 设备维度参数：版式键可能是 `th` 也可能是 `th_<urlKey>`（设备专属优先）。
+     *    必须改**当前设备实际由哪条键决定**的那一条，否则带 `?th_std=compact` 时
+     *    点面板会写 `th=xxx` 而被设备专属键盖住 —— 表现是"点了没反应"。
+     * 选回当前生效版式时把参数**删掉**（URL 干净，与容器「无参数即默认 view」一致）。
+     */
+    pickView(id) {
+      const scopedKey = `th_${urlKeyOf(device.value)}`;
+      const key = scopedKey in currentQuery() ? scopedKey : 'th';
+      if (id === activeViewId.value) replaceQuery({ [key]: undefined });
+      else replaceQuery({ [key]: id });
+    },
+
+    /**
+     * 选颜色：**只换色，不碰明暗**（两者正交）。不改 URL：配色是运行时状态
+     * （store + localStorage），面板改的是当前会话观感。
+     */
+    pickColor(id) {
+      store.setTheme(id);
+    },
+
+    pickMode(mode) {
+      store.setMode(mode);
+    },
+
+    /** 一键回默认：清掉落盘的配色与明暗偏好 */
+    reset() {
+      store.setMode('system');
+      const first = colors.value[0];
+      if (first) store.setTheme(first.id);
+    }
+  };
+
+  return { model, actions };
+}

package/src/vue/useThemeSources.ts

@@ -0,0 +1,74 @@
+/**
+ * 主题意图**来源同步** —— 拉后端配色 + 父应用主题同步（都读 env，宿主零传参）
+ *
+ * === 为什么归这里（而非 ThemeRoot）===
+ * 后端下发与父应用 postMessage 都是**主题意图来源**（与 URL / 用户操作 / localStorage
+ * 同类，见 6.2 来源优先级），不是「外观外壳」的职责。ThemeRoot 退化为纯外观壳后，
+ * 这两条「来源」由主题运行时（宿主的 `useThemeRuntime`）调用本 composable 接入，
+ * 落地动作（`applyThemeConfig` / `applyTheme`）由宿主 store 注入 —— 库不 import 宿主 store。
+ *
+ * === 为什么读 env ===
+ * 端点（`VITE_THEME_ENDPOINT`）与父 origin 白名单（`VITE_ALLOWED_PARENT_ORIGINS`）都是
+ * 主题域的部署事实，库直接读这两个约定好的 env 变量 —— 宿主配好 env 即生效，不再传参。
+ *
+ * === 为什么不依赖组件生命周期 ===
+ * 主题运行时（store）没有组件实例，`onMounted`/`onUnmounted` 在那里会失效（静默 bug）。
+ * 所以这里「立即注册父同步 + 立即发起后端拉取」，返回 cleanup，由宿主在 store 的
+ * dispose 里调用 cleanup（父同步 removeEventListener）。
+ *
+ * @author yijiu2025
+ * @since 2026-10-18
+ */
+import { useParentThemeSync } from './useParentThemeSync';
+import { fetchRemoteThemeConfig } from './remote-fetch';
+import type { RemoteThemeConfig } from '../scheme';
+
+export interface ThemeSourcesOptions {
+  /** 把外部配置落到宿主 store（含 null = 撤销外部覆写） */
+  applyThemeConfig(config: RemoteThemeConfig | null): void;
+  /** 把明暗落到宿主 store（父应用旧协议 `isDark`） */
+  applyTheme(dark: boolean): void;
+}
+
+/** 从 env 读父 origin 白名单（逗号分隔）；空 = 无父同步 */
+function allowedParentOrigins(): string[] {
+  const raw = import.meta.env.VITE_ALLOWED_PARENT_ORIGINS as string | undefined;
+  return typeof raw === 'string' ? raw.split(',').map(s => s.trim()).filter(Boolean) : [];
+}
+
+/** 从 env 读后端配色端点；空 = 不拉远程 */
+function remoteEndpoint(): string {
+  return (import.meta.env.VITE_THEME_ENDPOINT as string | undefined) ?? '';
+}
+
+/**
+ * 接入两条主题意图来源（父同步 + 后端配色），返回 cleanup
+ *
+ * 宿主 `useThemeRuntime` 里调一次：`const disposeSources = useThemeSources({ applyThemeConfig, applyTheme })`，
+ * 并在 store 的 dispose 里调 `disposeSources()`。
+ */
+export function useThemeSources(options: ThemeSourcesOptions): () => void {
+  const cleanups: Array<() => void> = [];
+
+  // 父主题同步（iframe 嵌入时父切主题子跟着切）
+  const allowed = allowedParentOrigins();
+  if (allowed.length > 0) {
+    cleanups.push(
+      useParentThemeSync({
+        isAllowedOrigin: origin => allowed.includes(origin),
+        apply: config => options.applyThemeConfig(config),
+        applyDark: dark => options.applyTheme(dark)
+      })
+    );
+  }
+
+  // 拉后端配色（异步发起，失败静默，不阻塞首屏）
+  const endpoint = remoteEndpoint();
+  void (async () => {
+    const clientId = new URLSearchParams(window.location.search).get('client_id') || undefined;
+    const config = await fetchRemoteThemeConfig(clientId, { endpoint });
+    if (config) options.applyThemeConfig(config);
+  })();
+
+  return () => cleanups.forEach(fn => fn());
+}