skinsuite 0.1.0 → 0.2.0

package/src/vue/remote-fetch.ts

@@ -0,0 +1,74 @@
+/**
+ * 后端主题配置取数（**参数化内核版**）—— 拉取后端下发的主题配置并归一形状
+ *
+ * === 为什么取数也能下沉 ===
+ * 「fetch + 超时 + 失败静默 + 归一形状」这个骨架是通用的；只有「端点 / 超时上限 /
+ * cookie 策略」是宿主的部署事实。所以把它们参数化，内核提供取数骨架，宿主编好参数即可。
+ *
+ * === 形状归一见 `skinsuite` 的 `normalizeRemoteThemeConfig` ===
+ * 「哪些字段算数、`skin` 是不是旧名字、tokens 为什么必须扁平」是契约，已收进纯内核；
+ * 这里只负责「怎么拿到 JSON 再交给它归一」。
+ *
+ * === 失败策略 ===
+ * 超时 / 非 200 / 结构不符 一律静默返回 null（用内置配色继续）。主题是锦上添花，
+ * 绝不能因为拉不到配色而挡住登录。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（从 oauth21/src/theme/remote.ts 下沉）
+ */
+import { normalizeRemoteThemeConfig } from '../scheme';
+import type { RemoteThemeConfig } from '../scheme';
+
+export interface RemoteThemeFetchOptions {
+  /** 端点 URL（宿主 `VITE_THEME_ENDPOINT`）；空串 = 机制关闭，直接返回 null */
+  endpoint: string;
+  /** 超时上限（毫秒） */
+  timeoutMs?: number;
+  /** 是否不带 cookie（默认 true，避免把登录态发到第三方域名） */
+  omitCredentials?: boolean;
+}
+
+/** 后端换配色是否启用（端点非空） */
+export function isRemoteThemeEnabled(endpoint: string | undefined): boolean {
+  return typeof endpoint === 'string' && endpoint.trim().length > 0;
+}
+
+/**
+ * 拉取后端主题配置
+ *
+ * @param clientId 接入应用的 client_id（决定用哪套品牌配色），可为空
+ * @param options  见 `RemoteThemeFetchOptions`
+ * @returns 配置对象；未启用 / 失败 / 无有效内容时返回 null
+ */
+export async function fetchRemoteThemeConfig(
+  clientId: string | undefined,
+  options: RemoteThemeFetchOptions
+): Promise<RemoteThemeConfig | null> {
+  const endpoint = options.endpoint;
+  if (!isRemoteThemeEnabled(endpoint)) return null;
+
+  let url: URL;
+  try {
+    url = new URL(endpoint, window.location.origin);
+  } catch {
+    return null; // endpoint 写了个非法 URL
+  }
+  if (clientId) url.searchParams.set('client_id', clientId);
+
+  const controller = new AbortController();
+  const timer = window.setTimeout(() => controller.abort(), options.timeoutMs ?? 3000);
+  try {
+    const res = await fetch(url.toString(), {
+      signal: controller.signal,
+      credentials: options.omitCredentials === false ? 'include' : 'omit',
+      headers: { Accept: 'application/json' }
+    });
+    if (!res.ok) return null;
+    return normalizeRemoteThemeConfig(await res.json());
+  } catch {
+    // 网络错误 / 超时 / JSON 解析失败：一律静默
+    return null;
+  } finally {
+    window.clearTimeout(timer);
+  }
+}

package/src/vue/theme-intent.ts

@@ -0,0 +1,157 @@
+/**
+ * 主题意图（intent）—— 明暗意图 + 会话级记忆槽 + 「明暗 ≡ 配色系别」联动
+ *
+ * 从 `oauth21/src/stores/theme-intent.ts` 下沉（2026-10-19）。本文件只负责「用户**想**要什么明暗」：
+ *   · `mode` 三态意图（light / dark / system）；
+ *   · 白系 / 黑系两侧的会话级记忆槽（只记「切走前正在用的那套」，不持久化）；
+ *   · `syncColorToTone` —— 从意图推导并切到匹配系别的配色（联动）；
+ *   · 用户显式操作：`setTheme` / `setMode` / `cycleMode` / `toggleTheme`。
+ *
+ * === 依赖方向 ===
+ *   intent 只依赖 scope（activeDevice/activePage/activeView/themeId + 清 URL 覆盖），
+ *   不依赖 runtime —— 它不碰 token 注入、不碰 DOM。
+ *
+ * @author yijiu2025
+ * @since 2026-10-19（从 oauth21/src/stores/theme-intent.ts 下沉，keys 参数化）
+ */
+import { ref, watch } from 'vue';
+import { DEFAULT_THEME_COLOR, DEFAULT_THEME_DARK_COLOR } from '../constants';
+import { MODE_CYCLE } from '../scheme';
+import type { ThemeMode, ThemeTone } from '../scheme';
+import { isKnownTheme, listColorIdsOfTone, resolveThemeId, toneOfAnyScope } from '../registry';
+import { readInitialMode, safeSet } from './theme-persistence';
+import type { ThemeStorageKeys } from './theme-persistence';
+import type { ThemeScope } from './theme-scope';
+
+export function useThemeIntent(scope: ThemeScope, keys: ThemeStorageKeys) {
+  const mode = ref<ThemeMode>(readInitialMode(keys));
+
+  /** 系统偏好（始终跟踪，是否采用由 mode 决定） */
+  const systemDark = ref(false);
+  const mediaQuery =
+    typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+      ? window.matchMedia('(prefers-color-scheme: dark)')
+      : null;
+  if (mediaQuery) systemDark.value = mediaQuery.matches;
+
+  const onSystemChange = (e: MediaQueryListEvent) => {
+    systemDark.value = e.matches;
+  };
+  mediaQuery?.addEventListener('change', onSystemChange);
+
+  /**
+   * 白系 / 黑系两侧的会话级记忆槽：只记「切走前正在用的那套」，不持久化。
+   * 点色卡不写槽；只有「明暗切换」这个动作才写。
+   */
+  const lightColor = ref<string | null>(null);
+  const darkColor = ref<string | null>(null);
+
+  /**
+   * 把配色切到与目标明暗匹配的系别（**明暗 → 配色**，单向）。
+   * 三种情况什么都不做（都刻意）：同系别 / 该版式没有目标系别（绝不跨系别回落）/
+   * 目标与当前相同。槽只记「切走前」的会话级值，不落盘。
+   */
+  function syncColorToTone(dark: boolean): void {
+    const target: ThemeTone = dark ? 'dark' : 'light';
+    const device = scope.activeDevice.value;
+    const page = scope.activePage.value;
+    // view ≡ pkg：activeView 的值就是当前包名，配色查找按它（= 包）过滤
+    const pkg = scope.activeView.value;
+
+    // ① 已经同系别 —— 按**任意登记处**查系别，不只看当前作用域。
+    if (toneOfAnyScope(scope.themeId.value) === target) return;
+
+    // 记住「切走前」当前系别正在用的那套（切回时恢复它）。只有明暗切换才写槽。
+    const curTone = toneOfAnyScope(scope.themeId.value);
+    if (curTone === 'light') lightColor.value = scope.themeId.value;
+    else if (curTone === 'dark') darkColor.value = scope.themeId.value;
+
+    // 优先取该系别槽里那套；它在当前包下不存在时弃用
+    const slot = dark ? darkColor.value : lightColor.value;
+    const fromSlot = slot && isKnownTheme(slot, device, page, pkg) ? slot : null;
+    // 目标系别配色：优先标配白/黑，没有时退回该系别第一套。
+    const standard = target === 'dark' ? DEFAULT_THEME_DARK_COLOR : DEFAULT_THEME_COLOR;
+    const ids = listColorIdsOfTone(device, page, pkg, target);
+    const next = fromSlot ?? (ids.includes(standard) ? standard : ids[0]) ?? null;
+
+    // ② / ③
+    if (!next || next === scope.themeId.value) return;
+
+    scope.themeId.value = next;
+  }
+
+  /**
+   * 首屏对齐：按当前「系别意图」把配色校正到匹配的系别。
+   * 该设备被判 URL 锁定时不干预（部署方/用户的明确意图必须压过联动）。
+   */
+  if (!scope.urlLockedThemeOf(scope.activeDevice.value)) {
+    syncColorToTone(mode.value === 'system' ? systemDark.value : mode.value === 'dark');
+  }
+
+  /** 明暗意图变化 → 联动切配色（唯一运行时入口）；首屏那一次已由上面的显式调用处理 */
+  watch(mode, m => syncColorToTone(m === 'system' ? systemDark.value : m === 'dark'));
+  watch(systemDark, dark => {
+    if (mode.value === 'system') syncColorToTone(dark);
+  });
+
+  /**
+   * 设置明暗意图（底层写入口，**不清** URL 覆盖）。
+   * 用户的显式操作请走 cycleMode / toggleTheme —— 它们会先清掉当前设备的覆盖。
+   */
+  function setMode(next: ThemeMode): void {
+    mode.value = next;
+    safeSet(keys.mode, next);
+  }
+
+  /** 循环切换明暗意图（跟随系统 → 明 → 暗 → 跟随系统）；显式操作 → 先清 URL 覆盖 */
+  function cycleMode(): void {
+    scope.clearDeviceThemeOverride();
+    const idx = MODE_CYCLE.indexOf(mode.value);
+    setMode(MODE_CYCLE[(idx + 1) % MODE_CYCLE.length]);
+  }
+
+  /** 在明/暗之间切换（= 白系 ↔ 黑系）；纯反色，不进 'system' */
+  function toggleTheme(): void {
+    scope.clearDeviceThemeOverride();
+    setMode(scope.isDark.value ? 'light' : 'dark');
+  }
+
+  /**
+   * 设置配色（开发者/部署方调用 → 落盘）。
+   * 会清掉当前设备的 URL 覆盖（点色卡是显式操作，必须能压过部署方链接）。
+   * 点色卡同步把 mode 设成该配色的系别，并打断「切走前」记忆链（清空对侧槽）。
+   */
+  function setTheme(id: string): boolean {
+    const resolved = resolveThemeId(id);
+    if (!resolved) return false;
+    scope.clearDeviceThemeOverride();
+    scope.themeId.value = resolved;
+    safeSet(keys.theme, resolved);
+    const tone = toneOfAnyScope(resolved);
+    if (tone === 'dark') lightColor.value = null;
+    else if (tone === 'light') darkColor.value = null;
+    if (tone) {
+      const next: ThemeMode = tone === 'dark' ? 'dark' : 'light';
+      if (mode.value !== next) {
+        mode.value = next;
+        safeSet(keys.mode, next);
+      }
+    }
+    return true;
+  }
+
+  /** 应用外部明暗（父应用旧协议兼容） */
+  function applyTheme(dark: boolean): void {
+    setMode(dark ? 'dark' : 'light');
+  }
+
+  /** 清理系统主题监听（HMR / 单测场景） */
+  function dispose(): void {
+    mediaQuery?.removeEventListener('change', onSystemChange);
+  }
+
+  return { mode, systemDark, lightColor, darkColor, setMode, cycleMode, toggleTheme, setTheme, applyTheme, dispose };
+}
+
+/** intent 的公开面（供 runtime / store 引用；类型由 `useThemeIntent` 返回处推断） */
+export type ThemeIntent = ReturnType<typeof useThemeIntent>;

package/src/vue/theme-persistence.ts

@@ -0,0 +1,136 @@
+/**
+ * 主题状态的**持久化与 URL 解析层**（localStorage 安全读写 + 旧数据迁移 + URL 多设备意图）
+ *
+ * 从 `oauth21/src/stores/theme-persistence.ts` 下沉（2026-10-19）。
+ *
+ * === 为什么下沉 ===
+ * 这些是「明暗 ≡ 配色系别」状态机的**纯函数半边**：不依赖 store 实例、无闭包、无副作用顺序。
+ * 它配合 scope / intent / runtime 一起构成完整状态机，五个前端（oauth21 / retroweb / firewall /
+ * admin / posecraft）都应复用同一份，而不是各抄一遍。键名与 URL 参数是**主题机制的约定**，
+ * 下沉后作为默认值，允许宿主通过 `ThemeStateOptions.storageKeys` / `colorParam` 覆盖（与自身
+ * 存储冲突时）。
+ *
+ * ⚠️ 这些函数**不自带 DOM 守卫**（如 `typeof window !== 'undefined'`）：SPA 场景下
+ *    window 必然存在。下沉不改变这一点。
+ *
+ * @author yijiu2025
+ * @since 2026-10-19（从 oauth21/src/stores/theme-persistence.ts 下沉，参数化键名/参数前缀）
+ */
+import { DEFAULT_THEME_ID } from '../constants';
+import { getDefaultThemeId, resolveThemeId } from '../registry';
+import type { ThemeMode } from '../scheme';
+import { deviceIds, fallbackDevice, urlKeyOf } from './define-theme-device';
+
+/** localStorage 键名集合（主题机制约定；与宿主存储冲突时通过 `ThemeStateOptions` 覆盖） */
+export interface ThemeStorageKeys {
+  /** 明暗意图键（三态 'system' / 'light' / 'dark'） */
+  mode: string;
+  /** 配色 id 键 */
+  theme: string;
+  /** 旧版本存配色 id 的键，只读不写（迁移用） */
+  legacySkin: string;
+  /** 旧版本标记「用户手动选过明暗」的键，只读不写（迁移用） */
+  legacyManual: string;
+}
+
+/** 默认键名（沿用旧键，让老用户的手动选择可以平滑迁移） */
+export const DEFAULT_STORAGE_KEYS: ThemeStorageKeys = {
+  mode: 'theme',
+  theme: 'theme-id',
+  legacySkin: 'theme-skin',
+  legacyManual: 'theme-manual'
+};
+
+/** URL 配色意图的参数前缀（配合设备 urlKey 组成 `th_color_<urlKey>`） */
+export const DEFAULT_COLOR_PARAM = 'th_color';
+
+/** 安全读 localStorage：隐私模式 / 禁用存储时会抛错，不能让它把应用带崩 */
+export function safeGet(key: string): string | null {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+/** 安全写 localStorage：存不了就算了，本次会话内仍正常工作 */
+export function safeSet(key: string, value: string): void {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+    /* 存不了就算了，本次会话内仍正常工作 */
+  }
+}
+
+/**
+ * 初始化明暗模式（含旧数据迁移）
+ *
+ * 旧版本把明暗写成 'light'/'dark'，另用 `legacyManual` 标记是否手动选过。
+ * 迁移规则：
+ *   • 存的是三态值 'system' → 直接用
+ *   • 存的是 'light'/'dark' 且有 manual 标记（用户真的手动选过）→ 保留其选择
+ *   • 存的是 'light'/'dark' 但没有 manual 标记 → 那只是旧版跟随系统的副产物，算 'system'
+ */
+export function readInitialMode(keys: ThemeStorageKeys = DEFAULT_STORAGE_KEYS): ThemeMode {
+  const saved = safeGet(keys.mode);
+  if (saved === 'system') return 'system';
+  if (saved === 'light' || saved === 'dark') {
+    return safeGet(keys.legacyManual) === 'true' ? saved : 'system';
+  }
+  return 'system';
+}
+
+/**
+ * 初始化主题：旧键 `legacySkin` 兜底
+ *
+ * 未登记 / 非法一律回**兜底设备 × 默认页面 × 默认包**里的兜底配色 ——
+ * 即 `DEFAULT_THEME_COLOR`（`white`）。这里不按具体设备判：落盘的只是一个
+ * "用户/部署方选过的配色"，它在哪端可用由各调用点按自己的设备解析（见 scope）。
+ *
+ * ⚠️ 最后兜底是 `DEFAULT_THEME_ID`（`'default'`）而**不是**设备名：拿设备名当配色 id
+ *    会得到一个永远查不到的 id，排查时极具误导性。
+ */
+export function readInitialTheme(keys: ThemeStorageKeys = DEFAULT_STORAGE_KEYS): string {
+  return (
+    resolveThemeId(safeGet(keys.theme) ?? safeGet(keys.legacySkin)) ??
+    getDefaultThemeId({ device: fallbackDevice() }) ??
+    DEFAULT_THEME_ID
+  );
+}
+
+/** URL 上按设备解析出的配色意图：只记"这台设备被**显式**指定了哪套色" */
+export type DeviceThemeIntent = Partial<Record<string, string>>;
+
+/**
+ * 读取 URL 上的主题意图（**含设备维度**）
+ *
+ * === 每台设备各一条取值链 ===
+ *   `?<colorParam>_<urlKey>`  →  `?<colorParam>`  → （缺则不算命中）
+ * 即"**设备专属优先，缺了退到通用键**"。缺了这台设备就走落盘偏好 / 该范围默认色。
+ *
+ * 设备专属键的后缀是**缩写名（urlKey）**（下划线连接）。明暗（`?mode=`）URL 入口已删。
+ * 非法值一律折成 null —— 不抛错、不锁项，让后端配置与本地存储照常参与。
+ *
+ * 🔴 **空串 = 未指定**：`?<colorParam>_<urlKey>=` 不能把 `?<colorParam>=blue` 顶掉。
+ */
+export function readUrlIntent(
+  colorParam: string = DEFAULT_COLOR_PARAM
+): { deviceTheme: DeviceThemeIntent } {
+  const deviceTheme: DeviceThemeIntent = {};
+  try {
+    const params = new URLSearchParams(window.location.search);
+    /** 空串 / 纯空白视为**未指定** —— 与 `readDeviceParam` 的 `isPresent()` 同一口径 */
+    const present = (raw: string | null): string | null =>
+      raw && raw.trim() !== '' ? raw : null;
+    // 无设备前缀的通用键：三端共用，任一设备没有专属键时用它
+    const anyScope = present(params.get(colorParam));
+    for (const device of deviceIds()) {
+      const scoped = present(params.get(`${colorParam}_${urlKeyOf(device)}`));
+      const resolved = resolveThemeId(scoped ?? anyScope);
+      if (resolved) deviceTheme[device] = resolved;
+    }
+    return { deviceTheme };
+  } catch {
+    return { deviceTheme };
+  }
+}

package/src/vue/theme-runtime.ts

@@ -0,0 +1,163 @@
+/**
+ * 主题运行时（runtime）—— token 注入 + 附加样式 + 明暗类 + 外部配置
+ *
+ * 从 `oauth21/src/stores/theme-runtime.ts` 下沉（2026-10-19）。本文件只负责「把生效配色**作用到 DOM/副作用**」：
+ *   · token 分层注入（`applyThemeLayers` → html inline 变量）+ `html.dark` 类；
+ *   · 附加样式 `theme.scss` 的惰性加载（带 epoch 防串台）；
+ *   · `data-mauth-theme` 属性写入；
+ *   · 切版式自动重置配色；
+ *   · 外部配置（后端 / 父应用）合入。
+ *
+ * === 依赖方向 ===
+ *   runtime 依赖 scope（themeRecordFor / activeDevice / isDark / themeId / deviceTheme）
+ *   和 intent（mode 的写入口），不反向 —— 它是编排链的最末端。
+ *
+ * === 🔴 TDZ 顺序（拆分后仍必须严格保持）===
+ *   `styleEpoch` 与 `loadThemeStyle` 必须声明在 `watch([themeId…], {immediate})` **之前**：
+ *   immediate watcher 会在 `watch()` 当场同步跑一遍 loadThemeStyle，若 `let styleEpoch`
+ *   还未求值就踩 TDZ，抛出的 ReferenceError 被 async 转成 rejected promise 又 `void` 丢掉，
+ *   现象是「只有首屏那次附加样式加载不到，之后手动切主题都正常」—— 极难从表象定位。
+ *
+ * @author yijiu2025
+ * @since 2026-10-19（从 oauth21/src/stores/theme-runtime.ts 下沉，签名不变）
+ */
+import { ref, watch } from 'vue';
+import { getDefaultThemeId, getThemeRecord, resolveThemeId, toneOfAnyScope } from '../registry';
+import type { ThemeTokenOverrides } from '../tokens';
+import { applyThemeLayers } from './token-runtime';
+import { useThemeSources } from './useThemeSources';
+import type { ThemeScope } from './theme-scope';
+import type { ThemeIntent } from './theme-intent';
+
+/** 承载主题附加样式（theme.scss）的 <style> 元素 id，切换主题时整体替换 */
+const STYLE_ELEMENT_ID = 'mauth-theme-css';
+
+export function useThemeRuntime(scope: ThemeScope, intent: ThemeIntent) {
+  /** 主题包自带 token（按当前生效作用域解析；一组扁平值，不分明暗档） */
+  const themeTokens = ref<ThemeTokenOverrides | null>(scope.themeRecordFor().tokens ?? null);
+  /** 外部覆写 token（后端下发 / 父应用 postMessage）；优先级高于主题包 */
+  const externalTokens = ref<ThemeTokenOverrides | null>(null);
+
+  /**
+   * 统一注入入口：配色 token、外部覆写、生效范围任一变化都重算。
+   * 注入的是 html 上的 inline style（整份文档唯一），所以只用一个设备的 token（activeDevice）。
+   * isDark 只负责给 <html> 挂/摘 dark 类（基线 SCSS 用），与注入挂在同一个 watch。
+   */
+  watch(
+    [themeTokens, externalTokens, scope.activeDevice, scope.isDark],
+    ([, , , dark]) => {
+      document.documentElement.classList.toggle('dark', dark);
+      const rejected = applyThemeLayers({
+        theme: themeTokens.value,
+        external: externalTokens.value
+      });
+      if (rejected.length > 0) {
+        console.warn(`[theme] 忽略了 ${rejected.length} 条不合规的主题变量：${rejected.join('、')}`);
+      }
+    },
+    { immediate: true }
+  );
+
+  /**
+   * 加载主题附加样式（theme.scss，惰性动态 import），带递增 epoch 防串台。
+   * 失败静默：附加样式拿不到只是少个背景图，绝不能挡住登录。
+   */
+  let styleEpoch = 0;
+  async function loadThemeStyle(id: string, pkg: string, device: string, page: string): Promise<void> {
+    const epoch = ++styleEpoch;
+    const loader = getThemeRecord({ id, device, pkg, page }).loadStyle;
+
+    if (!loader) {
+      document.getElementById(STYLE_ELEMENT_ID)?.remove();
+      return;
+    }
+    try {
+      const css = await loader();
+      if (epoch !== styleEpoch) return; // 期间又切了主题，丢弃本次结果
+      let node = document.getElementById(STYLE_ELEMENT_ID) as HTMLStyleElement | null;
+      if (!node) {
+        node = document.createElement('style');
+        node.id = STYLE_ELEMENT_ID;
+        document.head.appendChild(node);
+      }
+      node.textContent = css;
+    } catch {
+      /* 主题附加样式加载失败不影响登录 */
+    }
+  }
+
+  /**
+   * 承载配色标识 + 同步 token / 附加样式。
+   * 生效 id 按设备取 URL 覆盖（与 themeRecordFor 同口径）。
+   * 仅当"该设备没有这套配色、用了回落档"（record.meta.id !== id）时才 delete 属性。
+   */
+  watch(
+    [scope.themeId, scope.deviceTheme, scope.activeDevice, scope.activePage, scope.activeView],
+    ([, , device, page, view]) => {
+      const id = scope.deviceTheme.value[device] ?? scope.themeId.value;
+      // view ≡ pkg —— 用 activeView 充当 pkg
+      const record = getThemeRecord({ id, device, pkg: view, page });
+      const root = document.documentElement;
+      if (record.meta.id === id) root.dataset.mauthTheme = id;
+      else delete root.dataset.mauthTheme;
+
+      themeTokens.value = record.tokens ?? null;
+      void loadThemeStyle(id, view, device, page);
+    },
+    { immediate: true }
+  );
+
+  /**
+   * 切版式 → 自动重置配色（让用户立刻感受到新版的视觉特征）。
+   * 守门：仅新版式触发、仅 activeView 真的变了、该设备被 URL 锁定时不动、不落盘、不动 mode/槽。
+   */
+  watch(scope.activeView, (newView, oldView) => {
+    if (!newView || newView === oldView) return;
+    // 用旧 view（= 旧包）查 themeId 当前解析到的包
+    const currentPkg = scope.themeRecordFor(oldView, scope.activeDevice.value, scope.activePage.value).pkg;
+    if (currentPkg === newView) return;
+    if (scope.urlLockedThemeOf(scope.activeDevice.value)) return;
+    const fallback = getDefaultThemeId({ device: scope.activeDevice.value, page: scope.activePage.value, pkg: newView });
+    if (!fallback || fallback === scope.themeId.value) return;
+    scope.themeId.value = fallback;
+  });
+
+  /** 应用外部配色配置（后端下发 / 父应用同步）；不写 localStorage（后端默认值不覆盖用户偏好） */
+  function applyThemeConfig(config: {
+    theme?: string;
+    skin?: string;
+    mode?: 'light' | 'dark' | 'system';
+    tokens?: ThemeTokenOverrides;
+  } | null): void {
+    if (!config) {
+      externalTokens.value = null;
+      return;
+    }
+
+    const wanted = config.theme ?? config.skin;
+    if (wanted !== undefined && !scope.urlLockedThemeOf(scope.activeDevice.value)) {
+      const resolved = resolveThemeId(wanted);
+      if (resolved) {
+        scope.themeId.value = resolved;
+        const tone = toneOfAnyScope(resolved);
+        if (tone) {
+          const next = tone === 'dark' ? 'dark' : 'light';
+          if (intent.mode.value !== next) intent.mode.value = next;
+        }
+      }
+    }
+    if (config.mode) intent.mode.value = config.mode;
+    if (config.tokens) externalTokens.value = config.tokens;
+  }
+
+  // 主题意图来源同步：父主题同步 + 拉后端配色（读 env，宿主零传参）
+  const disposeSources = useThemeSources({
+    applyThemeConfig,
+    applyTheme: dark => intent.applyTheme(dark)
+  });
+
+  return { themeTokens, externalTokens, applyThemeConfig, disposeSources };
+}
+
+/** runtime 的公开面（类型由 `useThemeRuntime` 返回处推断） */
+export type ThemeRuntime = ReturnType<typeof useThemeRuntime>;

package/src/vue/theme-scope.ts

@@ -0,0 +1,148 @@
+/**
+ * 主题作用域（scope）—— 设备 / 页面 / 版式三个查找维度 + 配色解析入口
+ *
+ * 从 `oauth21/src/stores/theme-scope.ts` 下沉（2026-10-19）。
+ * 本文件只负责「作用域」这件事：
+ *   · 设备身份 `activeDevice`：订阅库内设备域判定结果；
+ *   · 页面 / 版式 `activePage` / `activeView`：由容器在 setup 里告知；
+ *   · `themeRecordFor`：把「配色意图（themeId / deviceTheme）+ 作用域」解析成可渲染配色；
+ *   · 派生值：`isDark`（= 生效配色 tone）、`activeTone`、`packageId`、`device`。
+ *
+ * === 依赖方向（拆分的骨架）===
+ *   scope ← intent（明暗意图，读 activeDevice/activePage/activeView/themeId）
+ *   scope ← runtime（token 注入 / 附加样式，读 themeRecordFor/isDark/activeDevice/themeId/deviceTheme）
+ * 本文件**不反向依赖** intent / runtime —— 它是唯一的共享基础。
+ *
+ * @author yijiu2025
+ * @since 2026-10-19（从 oauth21/src/stores/theme-scope.ts 下沉，keys/colorParam 参数化）
+ */
+import { computed, ref, watch } from 'vue';
+import { DEFAULT_THEME_PACKAGE, DEFAULT_THEME_PAGE } from '../constants';
+import { getThemeRecord, listThemes } from '../registry';
+import { currentDevice } from './device-domain';
+import { fallbackDevice } from './define-theme-device';
+import { readInitialTheme, readUrlIntent } from './theme-persistence';
+import type { DeviceThemeIntent, ThemeStorageKeys } from './theme-persistence';
+
+export function useThemeScope(keys: ThemeStorageKeys, colorParam: string) {
+  const urlIntent = readUrlIntent(colorParam);
+
+  /**
+   * URL 按设备指定的配色（**响应式**）
+   * 做成 ref 而非普通常量，是**用户显式操作会清掉当前设备那一条**（见 `clearDeviceThemeOverride`）。
+   */
+  const deviceTheme = ref<DeviceThemeIntent>({ ...urlIntent.deviceTheme });
+
+  /**
+   * 某设备的配色是否被 URL **显式**指定 → 该设备"锁定"。
+   * 锁定只挡**自动**改写，不挡用户显式操作；逐设备判定是必须的。
+   */
+  function urlLockedThemeOf(device: string): boolean {
+    return deviceTheme.value[device] !== undefined;
+  }
+
+  /**
+   * 清掉某设备被 URL 写下的配色 —— **只该由用户的显式操作调用**。
+   */
+  function clearDeviceThemeOverride(device: string = activeDevice.value): void {
+    if (deviceTheme.value[device] === undefined) return;
+    const next = { ...deviceTheme.value };
+    delete next[device];
+    deviceTheme.value = next;
+  }
+
+  /**
+   * **全局**配色 —— 只被"URL 没有覆盖这台设备"的那些设备采用。
+   * 设备专属 URL 值在 `themeRecordFor` 里优先于它。
+   */
+  const themeId = ref<string>(urlIntent.deviceTheme[fallbackDevice()] ?? readInitialTheme(keys));
+
+  /** 当前**生效设备** —— 决定把哪一套配色 token 注入 html；是"当前渲染视图属于哪种设备" */
+  const activeDevice = ref<string>(fallbackDevice());
+
+  /**
+   * 从**设备域**订阅当前生效设备（设备判定已收进库内设备域，这里只读）。
+   * `app.use(theme, { router })` 里设备域监听路由 + 视口 → `pickDeviceId` 判定 → `activeDevice`，
+   * 这里把它同步进作用域（`immediate` 覆盖 store 实例化时设备域已判好的值）。
+   */
+  watch(
+    currentDevice(),
+    device => {
+      if (device && device !== activeDevice.value) {
+        activeDevice.value = device;
+      }
+    },
+    { immediate: true }
+  );
+
+  function setActiveDevice(device: string): void {
+    if (activeDevice.value !== device) activeDevice.value = device;
+  }
+
+  /** 当前生效页面 / 版式（配色归属 = 包 × 设备 × 页面） */
+  const activePage = ref<string>(DEFAULT_THEME_PAGE);
+  const activeView = ref<string>(DEFAULT_THEME_PACKAGE);
+
+  function setActivePageView(page: string, view: string): void {
+    if (page && activePage.value !== page) activePage.value = page;
+    const next = view || DEFAULT_THEME_PACKAGE;
+    if (activeView.value !== next) activeView.value = next;
+  }
+
+  /**
+   * 按设备 + 页面 + 版式解析出**实际生效**的配色记录。
+   * 🔴 设备专属 URL 配色优先于全局 themeId：`deviceTheme[device] ?? themeId`。
+   * 🔴 接收 pkg 参数：view ≡ pkg，配色查找必须按当前包。
+   */
+  function themeRecordFor(
+    pkg: string = DEFAULT_THEME_PACKAGE,
+    device: string = activeDevice.value,
+    page: string = activePage.value
+  ): ReturnType<typeof getThemeRecord> {
+    const id = deviceTheme.value[device] ?? themeId.value;
+    return getThemeRecord({ id, device, pkg, page });
+  }
+
+  /** 最终是否深色 = 当前**生效配色**的系别（明暗 ≡ 色系） */
+  const isDark = computed(() => themeRecordFor().tone === 'dark');
+
+  /** 当前生效配色的系别 */
+  const activeTone = computed(() => themeRecordFor().tone ?? 'light');
+
+  /** 当前生效主题包（做成 computed 让容器的 watch 能当响应源） */
+  const packageId = computed(() => themeRecordFor().pkg);
+
+  /** 当前生效设备（只读别名） */
+  const device = computed(() => activeDevice.value);
+
+  /** 可选主题列表（注册表静态，取一次） */
+  const themes = listThemes();
+
+  /** 取当前配色为某页面声明的版式 id（只取值不校验） */
+  function viewFor(page: string, dev: string = activeDevice.value): string | undefined {
+    return themeRecordFor(packageId.value, dev, page).views?.[page];
+  }
+
+  return {
+    urlIntent,
+    deviceTheme,
+    themeId,
+    activeDevice,
+    activePage,
+    activeView,
+    isDark,
+    activeTone,
+    packageId,
+    device,
+    themes,
+    urlLockedThemeOf,
+    clearDeviceThemeOverride,
+    setActiveDevice,
+    setActivePageView,
+    themeRecordFor,
+    viewFor
+  };
+}
+
+/** scope 的公开面（供 intent / runtime 引用；类型由 `useThemeScope` 返回处推断） */
+export type ThemeScope = ReturnType<typeof useThemeScope>;