skinsuite 0.1.0 → 0.2.0

package/src/vue/create-theme-state.ts

@@ -0,0 +1,116 @@
+/**
+ * 主题状态机装配入口 —— `createThemeState(options)`（宿主一行 `defineStore` 包起来）
+ *
+ * 从 `oauth21/src/stores/theme.ts` 的编排逻辑下沉（2026-10-19）。
+ *
+ * === 为什么下沉编排、但**不**下沉 pinia ===
+ * 状态机的三块 composable（scope / intent / runtime）+ 持久化层都不依赖 pinia（只用
+ * `ref`/`computed`/`watch`），所以「下沉状态机」不需要把 pinia 传给包 —— 只要把**编排**
+ * 收成一个纯函数，宿主用一行 `defineStore('theme', () => createThemeState())` 包成 store。
+ * pinia 只是把 composable 注册成 store 实例的一层壳，不值得为它给库加 peer 依赖。
+ *
+ * === 宿主策略怎么收口（`ThemeStateOptions`）===
+ * 状态机里唯一可能因宿主而异的，是**持久化契约**：localStorage 键名、URL 配色参数前缀。
+ * 这两样下沉后作为默认值（对齐主题机制约定），宿主与之冲突时通过 options 覆盖。
+ * 后端配色端点 / 父应用 origin 白名单已通过 env 注入（`useThemeSources` 读
+ * `VITE_THEME_ENDPOINT` / `VITE_ALLOWED_PARENT_ORIGINS`），不进 options。
+ *
+ * === 调试探针 ===
+ * dev + `?debug=theme` 时把只读快照挂到 `window.__MAUTH_STORE__`（getter 形态，随 store 实时）。
+ * 探针需要访问 scope/intent 的内部 ref，所以随编排一起下沉（而不是留在宿主壳里）。
+ *
+ * @author yijiu2025
+ * @since 2026-10-19（从 oauth21/src/stores/theme.ts 下沉编排，pinia 留在宿主）
+ */
+import { useThemeScope } from './theme-scope';
+import { useThemeIntent } from './theme-intent';
+import { useThemeRuntime } from './theme-runtime';
+import { DEFAULT_COLOR_PARAM, DEFAULT_STORAGE_KEYS } from './theme-persistence';
+import type { ThemeStorageKeys } from './theme-persistence';
+
+/** 宿主策略收口点（全可选，默认 = 主题机制约定，oauth21 即默认值本身） */
+export interface ThemeStateOptions {
+  /** localStorage 键名（与宿主已有存储冲突时可覆盖） */
+  storageKeys?: Partial<ThemeStorageKeys>;
+  /** URL 配色意图参数前缀（配合设备 urlKey 组成 `th_color_<urlKey>`） */
+  colorParam?: string;
+}
+
+/**
+ * 装配主题状态机，返回与「主题 store」一致的公开面。
+ *
+ * 用法（宿主就这么多）：
+ * ```ts
+ * import { defineStore } from 'pinia';
+ * import { createThemeState } from 'skinsuite/vue';
+ * import 'virtual:theme'; // 副作用：装版式加载表 + 注册表 + 清单 + 拉齐 views/*.ts 声明
+ *
+ * export const useThemeStore = defineStore('theme', () => createThemeState());
+ * ```
+ *
+ * 返回对象里的 ref 会被 pinia 自动解包（与 `defineStore(() => ({ ...refs }))` 同形）。
+ */
+export function createThemeState(options: ThemeStateOptions = {}) {
+  const keys: ThemeStorageKeys = { ...DEFAULT_STORAGE_KEYS, ...options.storageKeys };
+  const colorParam = options.colorParam ?? DEFAULT_COLOR_PARAM;
+
+  // ① 作用域（共享基础：activeDevice / activePage / activeView / themeRecordFor / isDark 等）
+  const scope = useThemeScope(keys, colorParam);
+  // ② 意图（明暗三态 + 记忆槽 + 色系联动 + 用户操作入口）
+  const intent = useThemeIntent(scope, keys);
+  // ③ 运行时（token 注入 + 附加样式 + 明暗类 + 外部配置）；必须最后创建（内部 watch immediate 依赖前两步）
+  const runtime = useThemeRuntime(scope, intent);
+
+  // -------------------------------------------------------------------------
+  // 调试探针（仅 dev + ?debug=theme）：getter 形态随 store 实时取最新值
+  // -------------------------------------------------------------------------
+  if (import.meta.env.DEV && typeof window !== 'undefined' && new URLSearchParams(location.search).get('debug') === 'theme') {
+    (window as unknown as Record<string, unknown>).__MAUTH_STORE__ = {
+      get themeId() { return scope.themeId.value; },
+      get deviceTheme() { return { ...scope.deviceTheme.value }; },
+      get mode() { return intent.mode.value; },
+      get packageId() { return scope.packageId.value; },
+      get activeDevice() { return scope.activeDevice.value; },
+      get activePage() { return scope.activePage.value; },
+      get activeView() { return scope.activeView.value; },
+      get activeThemeId() { return scope.themeRecordFor().meta.id; },
+      get activeTone() { return scope.themeRecordFor().tone; }
+    };
+  }
+
+  return {
+    // ---- 来自 scope ----
+    mode: intent.mode,
+    isDark: scope.isDark,
+    themeId: scope.themeId,
+    packageId: scope.packageId,
+    device: scope.device,
+    activeDevice: scope.activeDevice,
+    activePage: scope.activePage,
+    activeView: scope.activeView,
+    activeTone: scope.activeTone,
+    themes: scope.themes,
+    systemDark: intent.systemDark,
+    themeTokens: runtime.themeTokens,
+    externalTokens: runtime.externalTokens,
+    lightColor: intent.lightColor,
+    darkColor: intent.darkColor,
+    themeRecordFor: scope.themeRecordFor,
+    setActiveDevice: scope.setActiveDevice,
+    setActivePageView: scope.setActivePageView,
+    // ---- 来自 intent ----
+    setMode: intent.setMode,
+    cycleMode: intent.cycleMode,
+    toggleTheme: intent.toggleTheme,
+    setTheme: intent.setTheme,
+    viewFor: scope.viewFor,
+    // ---- 来自 runtime ----
+    applyThemeConfig: runtime.applyThemeConfig,
+    applyTheme: intent.applyTheme,
+    // 销毁：intent 的系统偏好监听 + runtime 的来源同步（父同步 removeEventListener）
+    dispose: () => {
+      intent.dispose();
+      runtime.disposeSources();
+    }
+  };
+}

package/src/vue/define-theme-device.ts

@@ -0,0 +1,157 @@
+/**
+ * 设备声明工厂 —— `defineThemeDevice`（声明式，自动注册进设备域）
+ *
+ * 宿主只写一条声明（`id` / `label` / `urlKey` / `containers` 三参数 / `routePath` /
+ * 声明式 `match`），机制全在库内：`pageContainers` 建容器表、声明式 `match` → 判定函数、
+ * 自动注册进设备域。宿主不再写 `createDeviceRegistry` 装配、不再手动组数组、不再转发
+ * `asKnownDevice`。
+ *
+ * === 声明式 match 的优先级规则（库内唯一实现）===
+ * 字段间 OR；`explicitMobile` 是**全局最高优先信号** —— 一旦 `ctx.explicitMobile=true`，
+ * 带 `from`/`fromLogin`/`pathSegment` 的条目直接跳过，落到 `explicitMobile: true` 的条目
+ * （mobile）。宿主不再手写「排除显式手机意图」的 `!explicitMobile`。
+ *
+ * @author yijiu2025
+ * @since 2026-10-18（从 oauth21/src/theme/views/devices.ts 的声明下沉）
+ */
+import { pickDeviceId as pickDeviceIdOf } from '../views/device';
+import type { DeviceDef, DeviceMatchContext } from '../views/device';
+import { pageContainers, resolveContainerOf as resolveContainerOfWith } from './device-containers';
+import type { DeviceContainerLoader } from './device-containers';
+
+/** 声明式 match：字段间 OR；`fallback` 与其它互斥 */
+export interface DeclarativeMatch {
+  /** `?isMobile=true` 显式手机意图（全局最高优先信号） */
+  explicitMobile?: boolean;
+  /** 视口/UA 判为手机 */
+  viewportMobile?: boolean;
+  /** `?from=` 命中任一值 */
+  from?: string[];
+  /** `?fromLogin=` 命中任一值 */
+  fromLogin?: string[];
+  /** 路径含某整段/前缀 */
+  pathSegment?: string;
+  /** 兜底（无条件命中；必须是清单末条） */
+  fallback?: boolean;
+}
+
+/** `defineThemeDevice` 的输入（声明式） */
+export interface ThemeDeviceOptions {
+  /** 设备 id = 主题包内目录名，只允许 `[a-z0-9-]` */
+  id: string;
+  /** 中文名（调试面板 / 日志用） */
+  label: string;
+  /** 缩写名（URL 专属参数后缀用） */
+  urlKey: string;
+  /** 容器三参数：工厂内部自动执行 `pageContainers(glob, fileRe, idRe)` */
+  containers: {
+    /** `import.meta.glob(...)` 的返回值（必须字面量调用） */
+    glob: Record<string, DeviceContainerLoader>;
+    /** 文件名匹配正则（哪个文件算容器入口） */
+    fileRe: RegExp;
+    /** 页面名白名单（统一 `THEME_ID_RE`） */
+    idRe: RegExp;
+  };
+  /** 该设备在路由表占的 path（`{page}` 由页面名替换） */
+  routePath(page: string): string;
+  /** 声明式 match（不再手写闭包） */
+  match: DeclarativeMatch;
+}
+
+/** 路径是否含某整段/前缀（`mini` 匹配 `/mini/login` 或旧 `mini-login`） */
+function pathHasDeviceSegment(path: string, prefix: string): boolean {
+  return path
+    .split('/')
+    .filter(Boolean)
+    .some(seg => seg === prefix || seg.startsWith(`${prefix}-`));
+}
+
+/**
+ * 声明式 match → 判定函数
+ *
+ * 字段间 OR；`explicitMobile` 是全局最高优先信号。
+ */
+function normalizeMatch(m: DeclarativeMatch): (ctx: DeviceMatchContext) => boolean {
+  if (m.fallback) return () => true;
+  return (ctx: DeviceMatchContext) => {
+    // 显式手机意图下，带 from/fromLogin/pathSegment 的条目跳过（落到 explicitMobile 条目）
+    if (ctx.explicitMobile && (m.from || m.fromLogin || m.pathSegment)) return false;
+    return (
+      (m.explicitMobile === true && ctx.explicitMobile) ||
+      (m.viewportMobile === true && ctx.viewportIsMobile) ||
+      (m.from !== undefined && m.from.includes(ctx.from)) ||
+      (m.fromLogin !== undefined && m.fromLogin.includes(ctx.fromLogin)) ||
+      (m.pathSegment !== undefined && pathHasDeviceSegment(ctx.path, m.pathSegment))
+    );
+  };
+}
+
+/** 已自动注册的设备清单（顺序 = 优先级，末条必须 fallback 兜底） */
+const registeredDefs: DeviceDef<DeviceContainerLoader>[] = [];
+
+/**
+ * 声明一台设备并自动注册进设备域
+ *
+ * 内部做三件事：`pageContainers(glob, fileRe, idRe)` 建容器表、声明式 `match` → 判定函数、
+ * 注册进设备域。
+ */
+export function defineThemeDevice(options: ThemeDeviceOptions): DeviceDef<DeviceContainerLoader> {
+  const def: DeviceDef<DeviceContainerLoader> = {
+    id: options.id,
+    label: options.label,
+    urlKey: options.urlKey,
+    containers: pageContainers(
+      options.containers.glob,
+      options.containers.fileRe,
+      options.containers.idRe
+    ),
+    routePath: options.routePath,
+    match: normalizeMatch(options.match)
+  };
+  registeredDefs.push(def);
+  return def;
+}
+
+/** 已注册的设备清单（设备域运行时 / URL 参数解析用） */
+export function registeredDevices(): readonly DeviceDef<DeviceContainerLoader>[] {
+  return registeredDefs;
+}
+
+/** 外部传入的设备名是否在设备域白名单里（归一化校验用；替代旧 `asThemeDevice` 转发） */
+export function isKnownDevice(raw: unknown): raw is string {
+  return typeof raw === 'string' && registeredDefs.some(d => d.id === raw);
+}
+
+/** 设备 id → 缩写名（urlKey，URL 专属参数后缀用）；未声明缩写时回落 id */
+export function urlKeyOf(deviceId: string): string {
+  return registeredDefs.find(d => d.id === deviceId)?.urlKey ?? deviceId;
+}
+
+/* ---------------------------------------------------------------------------
+ * 用设备域单例的查询 / 派生（替代宿主「传 registeredDefs」的转发层）
+ * ------------------------------------------------------------------------- */
+
+/** 设备 id 清单（顺序即优先级，从已注册清单派生，不手写字面量） */
+export function deviceIds(): string[] {
+  return registeredDefs.map(d => d.id);
+}
+
+/** 兜底设备 = 末条 fallback 声明的 id（顺序即优先级，末条必须 fallback）；未声明设备时返回空串 */
+export function fallbackDevice(): string {
+  return registeredDefs[registeredDefs.length - 1]?.id ?? '';
+}
+
+/** 从外部输入判定「本次访问属于哪台设备」（用设备域单例 + 兜底设备） */
+export function pickDeviceId(ctx: DeviceMatchContext): string {
+  return pickDeviceIdOf(registeredDefs, ctx, fallbackDevice());
+}
+
+/** 取某设备在某页的容器加载器，**没写时兜底到 standard 设备**（用设备域单例） */
+export function resolveContainerOf(id: string, page: string): DeviceContainerLoader {
+  return resolveContainerOfWith(registeredDefs, id, page);
+}
+
+/** 重置模块级注册表（单测 / HMR 用） */
+export function resetDevices(): void {
+  registeredDefs.length = 0;
+}

package/src/vue/device-containers.ts

@@ -0,0 +1,73 @@
+/**
+ * 设备容器机制（**组件半边**）—— 「设备 id → 该页容器组件」的加载（内核版）
+ *
+ * 纯逻辑半边（设备判定 / 归一化 / 取容器表）在 `skinsuite` 的 `views/device.ts`；
+ * 本文件补上**组件**相关的一半：从 glob 结果建「页面 → 加载器」表、按设备取容器加载器。
+ *
+ * 之所以拆成两半：`import type { Component } from 'vue'` 让本文件只能住在 Vue 绑定层
+ * （`skinsuite/vue`），而判定逻辑是纯函数、值得被内核 tsc 独立检查、也能被非 Vue 前端复用。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（从 oauth21/src/theme/devices.ts 下沉）
+ */
+import type { Component } from 'vue';
+import type { DeviceDef } from '../views/device';
+import { containersOf } from '../views/device';
+
+/** 设备容器的惰性加载器（与 `import.meta.glob` 的取值形态一致） */
+export type DeviceContainerLoader = () => Promise<{ default: Component }>;
+
+/**
+ * 从「一批容器文件」建「页面 → 加载器」表
+ *
+ * 位置约定：`<...>/<页面名>/<文件名>.vue` —— **页面名 = 文件所在目录名**。
+ * 各设备用自己的 glob + 文件名规则调它，于是「容器放在哪、叫什么」是该设备自己的声明。
+ */
+export function pageContainers(
+  mods: Record<string, DeviceContainerLoader>,
+  fileRe: RegExp,
+  idRe: RegExp
+): ReadonlyMap<string, DeviceContainerLoader> {
+  const map = new Map<string, DeviceContainerLoader>();
+  for (const [key, loader] of Object.entries(mods)) {
+    const parts = key.split('/');
+    const file = parts[parts.length - 1];
+    // 页面名 = 文件上一级目录名（`/src/view/app/login/index.vue` → `login`）
+    const page = parts[parts.length - 2];
+    if (!page || !file || !fileRe.test(file)) continue;
+    // 页面名同样进 data-* / 路由，走同一份白名单；不合规目录静默跳过
+    if (!idRe.test(page)) continue;
+    if (!map.has(page)) map.set(page, loader);
+  }
+  return map;
+}
+
+/** 取某设备在某页的容器加载器；该设备没写这一页时返回 undefined */
+export function containerOf(
+  defs: readonly DeviceDef<DeviceContainerLoader>[],
+  id: string,
+  page: string
+): DeviceContainerLoader | undefined {
+  return containersOf(defs, id).get(page);
+}
+
+/**
+ * 取某设备在某页的容器加载器，**没写时兜底到 standard 设备**
+ *
+ * 分发器用它做「设备 id → 该页容器」的数据化映射：加一种设备时，只要给它写了容器，
+ * 分发器就能渲染；没写则该设备退到桌面容器 —— 不再写死「mobile ? X : mini ? Y : Standard」。
+ */
+export function resolveContainerOf(
+  defs: readonly DeviceDef<DeviceContainerLoader>[],
+  id: string,
+  page: string
+): DeviceContainerLoader {
+  return (
+    containerOf(defs, id, page) ??
+    containerOf(defs, 'standard', page) ??
+    (() =>
+      Promise.reject(
+        new Error(`[theme] 设备「${id}」在页面「${page}」没有容器，也没有 standard 兜底`)
+      ))
+  );
+}

package/src/vue/device-domain.ts

@@ -0,0 +1,149 @@
+/**
+ * 设备域运行时 —— 当前生效设备 `activeDevice` + matchMedia 视口判定 + 路由监听 → 判定
+ *
+ * 与 `define-theme-device`（声明工厂）配对：宿主在 `defineThemeDevice` 里声明设备清单
+ * （自动注册），本文件维护「当前属于哪台设备」这一运行时状态，供宿主 store 订阅、供
+ * token 注入 / 版式查找取用。
+ *
+ * === 信号来源 ===
+ * 设备判定只有「设备清单 `match`」一个来源，输入是 path / query（从 router 拿）+ 视口
+ * （`matchMedia`，阈值可配）。**不再有 `meta.device`** 这个冗余基线。
+ *
+ * === 为什么库只认 router 的最小结构 ===
+ * 库不 import vue-router（应用世界观），只认 `currentRoute.value.{ query, path, fullPath }`
+ * 这三个字段 —— 宿主把 router 传进来（`app.use(theme, { router })`）。
+ *
+ * @author yijiu2025
+ * @since 2026-10-18
+ */
+import { ref, watch } from 'vue';
+import { deviceContext, pickDeviceId } from '../views/device';
+import { registeredDevices } from './define-theme-device';
+import { DESKTOP_MIN_WIDTH, MOBILE_BREAKPOINT, detectMobileUA } from './viewport';
+
+/** 路由的最小结构（库不 import vue-router，只认这些字段） */
+export interface DeviceDomainRouter {
+  currentRoute: {
+    value: {
+      query: Record<string, unknown>;
+      path: string;
+      fullPath: string;
+    };
+  };
+  /** 替换当前路由（保留 path，只改 query；调试面板换版式 / 配色用） */
+  replace?(to: { query: Record<string, string | string[] | undefined> }): unknown;
+}
+
+export interface InstallThemeDomainOptions {
+  router: DeviceDomainRouter;
+  /**
+   * 宿主注入的「设备覆盖」解析：从当前 query 返回要**锁定**的设备 id，`null` = 不覆盖。
+   *
+   * 用于宿主自己的 URL 约定（如 `?device=mobile` 锁定手机端）——参数名是宿主词汇，
+   * 库不认、也不写死，只提供一个「显式覆盖自动判定」的通用注入点。命中合法设备时
+   * 优先于 `?isMobile` / `?from` / 视口；返回 null 或非法 id 则走自动判定。
+   */
+  resolveDeviceOverride?: (query: Record<string, unknown>) => string | null;
+}
+
+/** 当前生效设备（响应式；宿主 store 从这里订阅） */
+const activeDevice = ref<string>('');
+
+/** 视口是否判为手机（响应式；「1024 优先 + 768 窄 + UA 兜底」口径，见 viewport.ts） */
+const viewportMobile = ref(false);
+
+let routerRef: DeviceDomainRouter | null = null;
+let resolveDeviceOverride: InstallThemeDomainOptions['resolveDeviceOverride'] = undefined;
+
+/** 判定一次设备并写入 activeDevice */
+function judgeDevice(): void {
+  const defs = registeredDevices();
+  if (!routerRef || defs.length === 0) return;
+  const route = routerRef.currentRoute.value;
+
+  // 宿主注入的设备覆盖（如 ?device=）：命中合法设备直接锁定，压过自动判定
+  const override = resolveDeviceOverride?.(route.query) ?? null;
+  if (override && defs.some(d => d.id === override)) {
+    if (activeDevice.value !== override) activeDevice.value = override;
+    return;
+  }
+
+  const ctx = deviceContext(route.query, route.path, viewportMobile.value);
+  // 兜底 = 末条 fallback 设备的 id（默认设备的指定先不在这里定）
+  const fallback = defs[defs.length - 1].id;
+  const next = pickDeviceId(defs, ctx, fallback);
+  if (activeDevice.value !== next) activeDevice.value = next;
+}
+
+/**
+ * 装配设备域运行时（`app.use(theme, { router })` 时调用一次）
+ *
+ * 建立两条响应链：链接变动（`fullPath`）→ 判定；视口变化（两个 matchMedia + UA）→ 判定。
+ * 视口口径与宿主 `useDeviceDetect` 一致（宽视口优先 + 窄视口 + UA 兜底），保证设备域
+ * 判出的 `currentDevice` 与分发器渲染的形态同源。
+ */
+export function installThemeDomain(options: InstallThemeDomainOptions): void {
+  routerRef = options.router;
+  resolveDeviceOverride = options.resolveDeviceOverride;
+
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    const desktopMq = window.matchMedia(`(min-width: ${DESKTOP_MIN_WIDTH}px)`);
+    const mobileMq = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const syncViewport = (): void => {
+      // 宽视口优先：放得下桌面布局就一律电脑版，UA 说什么都不例外
+      if (desktopMq.matches || window.innerWidth >= DESKTOP_MIN_WIDTH) {
+        viewportMobile.value = false;
+        return;
+      }
+      // 窄视口直接移动端；中间段（768–1023）交给 UA 兜底（该区间可能是被缩放的桌面浏览器）
+      const narrow = mobileMq.matches || window.innerWidth < MOBILE_BREAKPOINT;
+      viewportMobile.value = narrow ? true : detectMobileUA();
+    };
+    syncViewport();
+    desktopMq.addEventListener('change', syncViewport);
+    mobileMq.addEventListener('change', syncViewport);
+  }
+
+  // 🔴 watch fullPath 而非整个路由对象：同路由 query/hash 变化不触发重判
+  watch(
+    () => options.router.currentRoute.value.fullPath,
+    () => judgeDevice(),
+    { immediate: true }
+  );
+
+  // 视口变化 → 重判
+  watch(viewportMobile, () => judgeDevice());
+}
+
+/** 当前生效设备（只读响应式，宿主 store 订阅它） */
+export function currentDevice(): Readonly<typeof activeDevice> {
+  return activeDevice;
+}
+
+/** 当前路由 query（`<ThemeView>` 读 URL 版式/配色参数用）；未装配 router 时返回空对象 */
+export function currentQuery(): Record<string, unknown> {
+  return routerRef?.currentRoute.value.query ?? {};
+}
+
+/**
+ * 替换当前路由的 query（**保留 `client_id` 等授权上下文**，只增删目标项）
+ *
+ * 与宿主旧接线壳 `replaceQuery` 同一语义：复制当前 query、应用 patch、`router.replace`。
+ * 库不 import vue-router，只认 `router.replace({ query })` 这个最小结构。
+ */
+export function replaceQuery(patch: Record<string, string | undefined>): void {
+  if (!routerRef?.replace) return;
+  const current = routerRef.currentRoute.value.query;
+  const query: Record<string, string | string[]> = {};
+  for (const [key, value] of Object.entries(current)) {
+    if (typeof value === 'string') query[key] = value;
+    else if (Array.isArray(value)) {
+      query[key] = value.filter((x): x is string => typeof x === 'string');
+    }
+  }
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) delete query[key];
+    else query[key] = value;
+  }
+  void routerRef.replace({ query });
+}

package/src/vue/index.ts

@@ -0,0 +1,98 @@
+/**
+ * `skinsuite/vue` —— **Vue 绑定层**的唯一公开出口
+ *
+ * 与 `skinsuite`（零依赖纯内核）分开成两个入口的理由：
+ *   • 只要纯机制的消费者（Node 脚本、另一套框架、单测）**不该被迫装 Vue**；
+ *   • `.vue` 与 `vue` 运行时只有这一个入口碰，依赖方向一眼可查。
+ *
+ * 这里只装「**机制**」，不装「**策略**」：
+ *   ✅ 面板长什么样、点一下发什么事件
+ *   ✅ postMessage 协议怎么解析
+ *   ❌ 路由怎么改、store 怎么实现、哪些 origin 可信 —— 那些是宿主参数
+ *
+ * @author yijiu2025
+ */
+
+export { default as ThemeDebugPanel } from './ThemeDebugPanel.vue';
+export { default as ThemeRoot } from './ThemeRoot.vue';
+export { default as ThemeView } from './ThemeView.vue';
+export { themeStoreKey } from './theme-store';
+export type { ThemeStoreLike } from './theme-store';
+export { useThemeSources } from './useThemeSources';
+export type { ThemeSourcesOptions } from './useThemeSources';
+export { useParentThemeSync } from './useParentThemeSync';
+export type { ParentThemeSyncOptions } from './useParentThemeSync';
+export { useThemeDebugPanel } from './useThemeDebugPanel';
+export type { ThemeDebugActions, ThemeDebugColor, ThemeDebugModel } from './types';
+
+// ---- 版式机制（「主题包 ⇄ Vue 组件」的桥接，2026-10-17 下沉）----
+// 🔴 公开面收敛（2026-10-17 末）：原 view-picker 并入 view-registry、view-pages 并入
+//    view-page；对外只留两个工厂。宿主只需 defineThemePage。
+export { createViewRegistry, createViewPicker } from './view-registry';
+export type {
+  PackageViews,
+  ViewModuleLoader,
+  ViewModuleMap,
+  ViewModuleProvider,
+  ViewRegistry,
+  ViewRegistryOptions,
+  ViewPicker,
+  ViewPickerOptions,
+  ViewPickerSource
+} from './view-registry';
+export { defineThemePage, isThemePage, pageOf, registeredPageNames, resetPages } from './view-page';
+export type { ThemePage, ThemePageOptions } from './view-page';
+export { installThemeViews, resetThemeViews, themeViewsFor } from './theme-views';
+
+// ---- 设备容器机制（「设备 id → 容器组件」的组件半边，2026-10-17 下沉）----
+// 🔴 containerOf / resolveContainerOf 的「传 defs」低层版不对外导出 —— 对外只留
+//    pageContainers（建容器表）与设备域单例版（见下），宿主不再写「传 registeredDefs」转发。
+export { pageContainers } from './device-containers';
+export type { DeviceContainerLoader } from './device-containers';
+
+// ---- 设备域（声明工厂 + 查询派生 + 运行时，2026-10-18 下沉）----
+export {
+  defineThemeDevice,
+  deviceIds,
+  fallbackDevice,
+  isKnownDevice,
+  pickDeviceId,
+  registeredDevices,
+  resetDevices,
+  resolveContainerOf,
+  urlKeyOf
+} from './define-theme-device';
+export type { DeclarativeMatch, ThemeDeviceOptions } from './define-theme-device';
+export { currentDevice, currentQuery, installThemeDomain, replaceQuery } from './device-domain';
+export type { DeviceDomainRouter, InstallThemeDomainOptions } from './device-domain';
+export { theme } from './plugin';
+export type { ThemePluginOptions } from './plugin';
+
+// ---- 视口 / UA 设备形态判定（2026-10-19 下沉，供设备域与宿主守卫/请求共用）----
+export {
+  DESKTOP_MIN_WIDTH,
+  MOBILE_BREAKPOINT,
+  detectMobileUA,
+  isDesktopViewport,
+  isMobileViewport
+} from './viewport';
+
+// ---- 主题状态机（scope/intent/runtime + 持久化，2026-10-19 下沉）----
+// 🔴 只导出 `createThemeState`（编排入口）—— scope/intent/runtime/persistence 是内部实现，
+//    对外只承诺「宿主一行 defineStore 包起来」。pinia **不进库**：编排返回的是纯 Vue 响应式，
+//    宿主自己决定是否用 defineStore 包装。
+export { createThemeState } from './create-theme-state';
+export type { ThemeStateOptions } from './create-theme-state';
+
+// ---- token 运行时（「分层 token → DOM」的注入半边，2026-10-17 下沉）----
+export {
+  applyThemeLayers,
+  applyThemeTokens,
+  clearThemeTokens,
+  getInjectedTokenNames,
+  resetThemeRuntime
+} from './token-runtime';
+
+// ---- 后端主题配置取数（「fetch + 超时 + 归一」骨架，2026-10-17 下沉）----
+export { fetchRemoteThemeConfig, isRemoteThemeEnabled } from './remote-fetch';
+export type { RemoteThemeFetchOptions } from './remote-fetch';

package/src/vue/panel.ts

@@ -0,0 +1,16 @@
+/**
+ * 面板的**独立入口** —— 供宿主做异步加载用
+ *
+ * 为什么单独开一条子路径：`skinsuite/vue` 里同时有同步的 composable 与懒加载的组件。
+ * 宿主若从同一个入口 `import()` 面板，打包器会把该入口的所有导出视为"已被静态引入"，
+ * 动态导入**不会**切出独立 chunk（Vite 报 `INEFFECTIVE_DYNAMIC_IMPORT`），
+ * 面板连同它的样式就回到了主包 —— 恰好破坏了"不带调试参数时不下载"的约定。
+ *
+ * 于是显式分成两条：
+ *   `skinsuite/vue`        → 同步（useParentThemeSync 等）
+ *   `skinsuite/vue/panel`  → 只导出面板组件，专供 `defineAsyncComponent`
+ *
+ * @author yijiu2025
+ */
+export { default as ThemeDebugPanel } from './ThemeDebugPanel.vue';
+export { default } from './ThemeDebugPanel.vue';

package/src/vue/plugin.ts

@@ -0,0 +1,35 @@
+/**
+ * 主题域的 Vue 插件 —— `app.use(theme, { router })` 一行启动设备域
+ *
+ * 与 Pinia / Router / i18n 同一套接入方式。`install` 在 `app.mount()` 之前**同步**执行，
+ * 设备域据此建立「链接变动 + 视口（matchMedia）→ 判定设备 → `activeDevice`」两条响应链，
+ * 首帧即终态（不闪基线色）。
+ *
+ * === 为什么只传 router ===
+ * 设备来源（path / query）从 router 拿、视口用库默认 `matchMedia`、判定结果存在设备域
+ * （宿主 store 订阅）——三件事都收进库，宿主只传一个 router，不写 `deviceSource`、不标
+ * `meta.device`、不手动 `setActiveDevice`。
+ *
+ * @author yijiu2025
+ * @since 2026-10-18
+ */
+import type { App, Plugin } from 'vue';
+import { installThemeDomain } from './device-domain';
+import type { DeviceDomainRouter, InstallThemeDomainOptions } from './device-domain';
+
+export interface ThemePluginOptions {
+  /** 宿主路由（库只认 `currentRoute.value.{ query, path, fullPath }` 最小结构） */
+  router: DeviceDomainRouter;
+  /** 宿主注入的设备覆盖解析（`?device=` 等宿主 URL 词汇），透传给设备域 */
+  resolveDeviceOverride?: InstallThemeDomainOptions['resolveDeviceOverride'];
+}
+
+/** Vue 插件：`app.use(theme, { router, resolveDeviceOverride? })` */
+export const theme: Plugin<[ThemePluginOptions]> = {
+  install(_app: App, options: ThemePluginOptions) {
+    installThemeDomain({
+      router: options.router,
+      resolveDeviceOverride: options.resolveDeviceOverride
+    });
+  }
+};