@orbit-work/ui 0.1.2-preview.0 → 0.1.3

package/src/theme/core/skin.ts

@@ -1,605 +0,0 @@
-/**
- * Orbitwork skin protocol — aligned with Design project architecture.
- * A skin is a validated JSON document that overrides --ow-* CSS variables
- * at runtime. This module is framework-agnostic.
- */
-
-export type Theme = "light" | "dark" | "system"
-export type ResolvedTheme = "light" | "dark"
-
-/**
- * DS2 皮肤白名单（COMPONENT-RULES §15 · 2026-08-31 裁决）：
- * - 可覆盖：中性表面/边框/文字梯度、chat/composer/sidebar 背景类、
- *   btn-primary 族（唯一开放的租户品牌色位）。
- * - 已移除（禁覆盖）：primary 族（--ow-primary 暗档=荧黄行动极）、link、
- *   switchActive（--ow-control-on 无彩选中）、功能色四族、cardRadius/buttonRadius
- *   （圆角是品牌定稿）。
- */
-export type OrbitworkSkinTokens = {
-  backgroundPrimary?: string
-  backgroundSecondary?: string
-  backgroundTertiary?: string
-  backgroundPanel?: string
-  foregroundPrimary?: string
-  foregroundSecondary?: string
-  foregroundMuted?: string
-  foregroundHint?: string
-  borderSubtle?: string
-  borderDefault?: string
-  borderStrong?: string
-  buttonPrimaryBackground?: string
-  buttonPrimaryForeground?: string
-  chatBackground?: string
-  chatBackgroundImage?: string
-  chatBackgroundOverlay?: string
-  chatBackgroundMaskColor?: string
-  chatBackgroundPosition?:
-    | "center"
-    | "top"
-    | "bottom"
-    | "left"
-    | "right"
-    | "top left"
-    | "top right"
-    | "bottom left"
-    | "bottom right"
-  chatBackgroundSize?: "cover" | "contain" | "auto"
-  userBubbleBackground?: string
-  userBubbleForeground?: string
-  userBubbleBorder?: string
-  composerBackground?: string
-  composerBorder?: string
-  sidebarBackground?: string
-  sidebarSelectedBackground?: string
-}
-
-/** L2/L3 逃生通道登记项：每条高级样式须登记目标与用途（§15，长期目标清零）。 */
-export type OrbitworkSkinRegistryEntry = {
-  target: string
-  reason: string
-}
-
-export type OrbitworkSkin = {
-  version: 1
-  id: string
-  name: string
-  description?: string
-  /**
-   * @deprecated DS2 §15：圆角是品牌定稿，皮肤不再开放 cardRadius/buttonRadius。
-   * 字段仅为旧代码类型兼容保留（空对象），解析路径一律拒绝 common。
-   */
-  common?: Record<string, never>
-  modes: {
-    light?: OrbitworkSkinTokens
-    dark?: OrbitworkSkinTokens
-  }
-  contributes?: {
-    /** L2: 语义选择器样式（精准定制组件部件） */
-    semanticStyles?: string
-    /** L3: 自由补丁（高级用户，需谨慎使用） */
-    patches?: string
-    /** L2/L3 登记表：存在 semanticStyles/patches 时必须逐条登记（validate-skin 强制） */
-    registry?: OrbitworkSkinRegistryEntry[]
-  }
-}
-
-export type SkinValidationResult = { ok: true; skin: OrbitworkSkin } | { ok: false; error: string }
-
-const COLOR_KEYS = [
-  "backgroundPrimary",
-  "backgroundSecondary",
-  "backgroundTertiary",
-  "backgroundPanel",
-  "foregroundPrimary",
-  "foregroundSecondary",
-  "foregroundMuted",
-  "foregroundHint",
-  "borderSubtle",
-  "borderDefault",
-  "borderStrong",
-  "buttonPrimaryBackground",
-  "buttonPrimaryForeground",
-  "chatBackground",
-  "chatBackgroundOverlay",
-  "userBubbleBackground",
-  "userBubbleForeground",
-  "userBubbleBorder",
-  "composerBackground",
-  "composerBorder",
-  "sidebarBackground",
-  "sidebarSelectedBackground",
-] as const
-const IMAGE_KEYS = ["chatBackgroundImage"] as const
-const MASK_COLOR_KEYS = ["chatBackgroundMaskColor"] as const
-const POSITION_KEYS = ["chatBackgroundPosition"] as const
-const SIZE_KEYS = ["chatBackgroundSize"] as const
-const TOKEN_KEYS = [...COLOR_KEYS, ...MASK_COLOR_KEYS, ...IMAGE_KEYS, ...POSITION_KEYS, ...SIZE_KEYS] as const
-const ROOT_KEYS = new Set(["version", "id", "name", "description", "modes", "contributes"])
-const MODE_KEYS = new Set(["light", "dark"])
-const TOKEN_KEY_SET = new Set<string>(TOKEN_KEYS)
-const CONTRIBUTES_KEYS = new Set(["semanticStyles", "patches", "registry"])
-const REGISTRY_ENTRY_KEYS = new Set(["target", "reason"])
-export const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i
-const MASK_HEX_COLOR = /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/i
-const DATA_IMAGE = /^data:image\/(png|jpeg|webp);base64,([A-Za-z0-9+/]+={0,2})$/
-const BACKGROUND_POSITIONS = new Set([
-  "center",
-  "top",
-  "bottom",
-  "left",
-  "right",
-  "top left",
-  "top right",
-  "bottom left",
-  "bottom right",
-])
-const BACKGROUND_SIZES = new Set(["cover", "contain", "auto"])
-export const MAX_ORBITWORK_SKIN_IMAGE_BYTES = 5 * 1024 * 1024
-const INLINE_SKIN_IMAGE_MAX_BYTES = 128 * 1024
-const CHAT_BACKGROUND_MASK_DERIVED_PROPERTIES = [
-  "--ow-chat-bg-mask-start-opacity",
-  "--ow-chat-bg-mask-end-opacity",
-] as const
-
-export type OrbitworkSkinChatBackgroundMask = {
-  color: string
-  strength: number
-  startOpacity: number
-  endOpacity: number
-}
-
-/** Six-digit colors retain the original 80% → 50% mask; explicit alpha controls final strength. */
-export function resolveOrbitworkSkinChatBackgroundMask(value: string): OrbitworkSkinChatBackgroundMask {
-  const normalized = MASK_HEX_COLOR.test(value) ? value.toLowerCase() : "#000000"
-  const strength = normalized.length === 9 ? Math.round((Number.parseInt(normalized.slice(7), 16) / 255) * 100) : 80
-  const startOpacity = strength
-  const endOpacity = strength <= 80 ? strength * 0.625 : 50 + (strength - 80) * 2.5
-  return { color: normalized.slice(0, 7), strength, startOpacity, endOpacity }
-}
-
-export function orbitworkSkinChatBackgroundMaskColor(color: string, strength: number): string {
-  const normalizedColor = /^#[0-9a-f]{6}$/i.test(color) ? color.toLowerCase() : "#000000"
-  const alpha = Math.round((Math.min(100, Math.max(0, strength)) / 100) * 255)
-  return `${normalizedColor}${alpha.toString(16).padStart(2, "0")}`
-}
-
-export const ORBITWORK_SKIN_CSS_VARIABLES: Readonly<Record<keyof OrbitworkSkinTokens, string>> = {
-  backgroundPrimary: "--ow-bg",
-  backgroundSecondary: "--ow-surface",
-  backgroundTertiary: "--ow-surface-2",
-  backgroundPanel: "--ow-bg",
-  foregroundPrimary: "--ow-text",
-  foregroundSecondary: "--ow-text-2",
-  foregroundMuted: "--ow-text-3",
-  // 2.0 文字梯度只有三档，hint 与 muted 同落 text-3
-  foregroundHint: "--ow-text-3",
-  borderSubtle: "--ow-border",
-  // 2.0 边框只有两档，subtle 与 default 同落 border
-  borderDefault: "--ow-border",
-  borderStrong: "--ow-border-strong",
-  buttonPrimaryBackground: "--ow-btn-primary-bg",
-  buttonPrimaryForeground: "--ow-btn-primary-fg",
-  chatBackground: "--ow-chat-bg",
-  chatBackgroundImage: "--ow-chat-bg-image",
-  chatBackgroundOverlay: "--ow-chat-bg-overlay",
-  chatBackgroundMaskColor: "--ow-chat-bg-mask-color",
-  chatBackgroundPosition: "--ow-chat-bg-position",
-  chatBackgroundSize: "--ow-chat-bg-size",
-  // 三件用户气泡钩子由 domain/chat/UserTurn 消费；未覆盖时兜底 DS2 井色配方
-  // （bg=--ow-bubble-user / fg=--ow-text / border=--ow-border），不再兜底透明。
-  userBubbleBackground: "--ow-chat-user-bubble-bg",
-  userBubbleForeground: "--ow-chat-user-bubble-fg",
-  userBubbleBorder: "--ow-chat-user-bubble-border",
-  composerBackground: "--ow-composer-bg",
-  composerBorder: "--ow-composer-border",
-  sidebarBackground: "--ow-sidebar-bg",
-  sidebarSelectedBackground: "--ow-sidebar-selected-bg",
-}
-
-/**
- * DS2 皮肤禁覆盖清单（COMPONENT-RULES §15 · 2026-08-31 裁决）。
- * 条目以 `*` 结尾表示前缀匹配；其余为精确名（含其 `-` 后缀派生，如
- * `--ow-control-on` 同时覆盖 `--ow-control-on-glyph`）。
- *
- * ⚠️ 同步义务：.claude/skills/ui-theme-skin/scripts/check-skin-ds2.mjs 持有
- * 本清单的副本，两处必须同步修改。
- */
-export const DS2_SKIN_DENYLIST = [
-  // 三极 token
-  "--ow-beacon",
-  "--ow-beacon-idle",
-  "--ow-accent-dot",
-  "--ow-data-today",
-  // 行动极族（租户品牌色只经 btn-primary 族开放，--ow-primary 落点不可写）
-  "--ow-primary*",
-  // 无彩选中原则
-  "--ow-control-on",
-  // focus-ring
-  "--ow-focus-ring",
-  // 功能色四族全档
-  "--ow-info*",
-  "--ow-success*",
-  "--ow-warning*",
-  "--ow-error*",
-  // 功能色别名：--ow-mention-bg/-text 直挂 --ow-info-tint/-on-tint，
-  // 不封别名等于给 L2/L3 皮肤留了一道绕开功能色禁覆盖的后门。
-  "--ow-mention*",
-  // 恒定域
-  "--ow-paper",
-  "--ow-stage-*",
-  "--ow-term-*",
-  "--ow-ansi-*",
-  // 圆角（形状表是品牌定稿）
-  "--ow-radius-*",
-] as const
-
-/**
- * DS2 皮肤禁覆盖 **CSS 属性** 清单（COMPONENT-RULES §5/§7/§9 · W5 终扫补闸）。
- *
- * 背景：`DS2_SKIN_DENYLIST` 是 token 名维度的闸，只认 `--ow-*`。L2/L3 的
- * semanticStyles / patches 里裸写的 `box-shadow: 0 0 20px …`、`border-radius: 18px`、
- * `transform: translateY(-2px)`、`animation: neon-pulse 2s infinite` 完全绕开它——
- * 而这四类恰恰是 2.0 明令收口的三层：贴地零影（§5）、形状表定稿（§7）、
- * 唯一动效语汇＝信标（§9）。故对属性维度另立一闸：命中即整块剥除。
- *
- * 条目为属性名前缀（连字符边界）：`border-radius` 同时覆盖
- * `border-top-left-radius` 等长写；`transition` 覆盖 `transition-property` 等。
- *
- * ⚠️ 同步义务：.claude/skills/ui-theme-skin/scripts/check-skin-ds2.mjs 持有本清单副本。
- */
-export const DS2_SKIN_DENIED_PROPERTIES = [
-  "border-radius",
-  "border-top-left-radius",
-  "border-top-right-radius",
-  "border-bottom-left-radius",
-  "border-bottom-right-radius",
-  "box-shadow",
-  "transform",
-  "animation",
-  "transition",
-  "backdrop-filter",
-  "-webkit-backdrop-filter",
-] as const
-
-/**
- * 判断某个 CSS 属性名是否命中属性维度禁覆盖清单。
- * 只按连字符边界做前缀匹配，避免 `animation` 误伤自定义属性 `--animation-x`
- * （自定义属性由 token 维度那一闸单独管）。
- */
-export function isDs2SkinDeniedProperty(propertyName: string): boolean {
-  const name = propertyName.trim().toLowerCase()
-  if (name.startsWith("--")) return false
-  return DS2_SKIN_DENIED_PROPERTIES.some((entry) => name === entry || name.startsWith(`${entry}-`))
-}
-
-/**
- * 在一段 CSS 文本里找出第一处命中属性维度禁覆盖清单的声明。
- * 只在「声明位置」匹配（块首/`;`/`{` 之后的标识符 + `:`），选择器与值里的同名词不算。
- */
-export function findDs2DeniedCssProperty(css: string): string | null {
-  const declaration = /(?:^|[{;])\s*(-{0,2}[a-z][a-z0-9-]*)\s*:/gi
-  let match: RegExpExecArray | null = declaration.exec(css)
-  while (match) {
-    const property = match[1] ?? ""
-    if (isDs2SkinDeniedProperty(property)) return property.toLowerCase()
-    match = declaration.exec(css)
-  }
-  return null
-}
-
-/**
- * 值维度禁覆盖（DS2 判据 7「品牌外渐变一律清除」）。
- *
- * ⚠️ 同步义务：与 .claude|.agents/skills/ui-theme-skin/scripts/check-skin-ds2.mjs 的
- * DENIED_VALUE_PATTERNS 为同一清单的副本（见 SkinDenylistSyncSource.test.mjs）。
- *
- * 为什么不是往 DS2_SKIN_DENIED_PROPERTIES 里加 `background`：皮肤本来就该能改底色，
- * 按属性名封会把整类合法覆盖一起封掉。要拦的是**值的形态**——任何 *-gradient()。
- * R2 之前这一层完全没有：glass.ts 的 `body { background: linear-gradient(135deg,
- * rgba(59,130,246,.1), rgba(139,92,246,.1)) }`（V1 蓝紫）是整份皮肤里唯二穿过闸口的
- * 块之一；cyberpunk.ts 的 `userBubbleBackground: "linear-gradient(135deg,#E91E63,#9C27B0)"`
- * 更是走 mode token 直接落到用户气泡上——两条路都得拦。
- */
-export const DS2_SKIN_DENIED_VALUE_PATTERNS = ["-gradient("] as const
-
-/** 判断某个 CSS 值是否命中值维度禁覆盖（渐变）。 */
-export function isDs2SkinDeniedValue(value: string): boolean {
-  const v = value.toLowerCase()
-  return DS2_SKIN_DENIED_VALUE_PATTERNS.some((entry) => v.includes(entry))
-}
-
-/**
- * 在一段 CSS 文本里找出第一处命中值维度禁覆盖的声明值。
- * 只看声明的**值**侧，选择器与注释里的同名词不算（调用方已剥注释）。
- */
-export function findDs2DeniedCssValue(css: string): string | null {
-  const declaration = /(?:^|[{;])\s*-{0,2}[a-z][a-z0-9-]*\s*:([^;{}]*)/gi
-  let match: RegExpExecArray | null = declaration.exec(css)
-  while (match) {
-    const value = match[1] ?? ""
-    if (isDs2SkinDeniedValue(value)) {
-      const hit = /[a-z-]*-gradient\(/i.exec(value)
-      return hit ? hit[0].slice(0, -1) : "gradient"
-    }
-    match = declaration.exec(css)
-  }
-  return null
-}
-
-/** 锁定件 data-slot 选择器初始清单：L2/L3 内容命中即剥除（字符串匹配）。 */
-export const DS2_LOCKED_SLOT_SELECTORS = ["beacon-spinner", "orbitwork-mark", "orbitwork-lockup"] as const
-
-/** 判断某个 CSS 自定义属性名是否命中 DS2 禁覆盖清单。 */
-export function isDs2SkinDeniedToken(tokenName: string): boolean {
-  const name = tokenName.trim()
-  return DS2_SKIN_DENYLIST.some((entry) =>
-    entry.endsWith("*") ? name.startsWith(entry.slice(0, -1)) : name === entry || name.startsWith(`${entry}-`),
-  )
-}
-
-/** WCAG 2.x 相对亮度 → 对比度实算（输入为 3/4/6/8 位 hex；alpha 忽略，按不透明计算）。 */
-export function ds2ContrastRatio(hexA: string, hexB: string): number {
-  const la = relativeLuminance(hexA)
-  const lb = relativeLuminance(hexB)
-  const lighter = Math.max(la, lb)
-  const darker = Math.min(la, lb)
-  return (lighter + 0.05) / (darker + 0.05)
-}
-
-function relativeLuminance(hex: string): number {
-  const [r, g, b] = hexToRgb(hex)
-  const toLinear = (channel: number) => {
-    const c = channel / 255
-    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
-  }
-  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b)
-}
-
-function hexToRgb(hex: string): [number, number, number] {
-  let value = hex.replace(/^#/, "")
-  if (value.length === 3 || value.length === 4) {
-    value = value
-      .slice(0, 3)
-      .split("")
-      .map((c) => c + c)
-      .join("")
-  }
-  return [
-    Number.parseInt(value.slice(0, 2), 16),
-    Number.parseInt(value.slice(2, 4), 16),
-    Number.parseInt(value.slice(4, 6), 16),
-  ]
-}
-
-/** 中性梯度整组闸：命中任一触发键即要求整组提交并过对比度实算。 */
-const NEUTRAL_TRIGGER_KEYS = [
-  "backgroundPrimary",
-  "backgroundSecondary",
-  "backgroundTertiary",
-  "backgroundPanel",
-  "foregroundPrimary",
-  "foregroundSecondary",
-  "foregroundMuted",
-  "foregroundHint",
-] as const
-const NEUTRAL_REQUIRED_KEYS = [
-  "backgroundPrimary",
-  "backgroundSecondary",
-  "backgroundTertiary",
-  "foregroundPrimary",
-  "foregroundSecondary",
-] as const
-const NEUTRAL_CONTRAST_PAIRS: ReadonlyArray<readonly [keyof OrbitworkSkinTokens, keyof OrbitworkSkinTokens]> = [
-  ["foregroundPrimary", "backgroundPrimary"],
-  ["foregroundPrimary", "backgroundSecondary"],
-  ["foregroundPrimary", "backgroundTertiary"],
-  ["foregroundSecondary", "backgroundPrimary"],
-  ["foregroundSecondary", "backgroundSecondary"],
-]
-const MIN_NEUTRAL_CONTRAST = 4.5
-
-/** 闸 (a)：覆盖项落点命中禁覆盖清单即拒绝（白名单收敛后属兜底防线）。 */
-function assertTokensNotDenied(tokens: OrbitworkSkinTokens, path: string): void {
-  for (const [key, value] of Object.entries(tokens)) {
-    const cssVar = ORBITWORK_SKIN_CSS_VARIABLES[key as keyof OrbitworkSkinTokens]
-    if (cssVar && isDs2SkinDeniedToken(cssVar)) {
-      throw new Error(`${path}.${key} 的落点 ${cssVar} 命中 DS2 禁覆盖清单，拒绝该皮肤`)
-    }
-    // 值维度：token 值本身是渐变时，属性闸与 token 闸都拦不住（落点名合法、属性名合法），
-    // 直接落到气泡/侧栏底上——判据 7「品牌外渐变一律清除」在这里收口。
-    // chatBackgroundImage 例外：它本来就是一张图/图案的落点，由 orbitwork-skin-image 单独校验。
-    if (key !== "chatBackgroundImage" && typeof value === "string" && isDs2SkinDeniedValue(value)) {
-      throw new Error(`${path}.${key} 的值是渐变（${value}），DS2 判据 7 品牌外渐变一律清除，拒绝该皮肤`)
-    }
-  }
-}
-
-/** 闸 (b)：中性梯度整组提交 + WCAG 对比度实算（text-on-bg / text-on-surface ≥ 4.5:1）。 */
-function assertNeutralGroupContrast(tokens: OrbitworkSkinTokens, path: string): void {
-  const touched = NEUTRAL_TRIGGER_KEYS.some((key) => tokens[key] !== undefined)
-  if (!touched) return
-  const missing = NEUTRAL_REQUIRED_KEYS.filter((key) => tokens[key] === undefined)
-  if (missing.length > 0) {
-    throw new Error(`${path} 中性梯度须整组提交（text 系与 bg/surface 系同批），缺少：${missing.join("、")}`)
-  }
-  for (const [textKey, bgKey] of NEUTRAL_CONTRAST_PAIRS) {
-    const text = tokens[textKey]
-    const bg = tokens[bgKey]
-    if (!text || !bg) continue
-    const ratio = ds2ContrastRatio(text, bg)
-    if (ratio < MIN_NEUTRAL_CONTRAST) {
-      throw new Error(
-        `${path} 对比度不达标：${textKey}(${text}) 在 ${bgKey}(${bg}) 上为 ${ratio.toFixed(2)}:1，要求 ≥ ${MIN_NEUTRAL_CONTRAST}:1`,
-      )
-    }
-  }
-}
-
-export function hasOrbitworkSkinChatBackground(skin: OrbitworkSkin | null | undefined, mode: ResolvedTheme): boolean {
-  return Boolean(skin?.modes?.[mode]?.chatBackgroundImage)
-}
-
-export function parseOrbitworkSkin(input: unknown): SkinValidationResult {
-  try {
-    if (!isRecord(input)) throw new Error("主题必须是 JSON 对象")
-    if ("common" in input)
-      throw new Error("common（cardRadius/buttonRadius）已随 DS2 皮肤边界取消：圆角是品牌定稿，不开放自由值")
-    assertKnownKeys(input, ROOT_KEYS, "主题")
-    if (input.version !== 1) throw new Error("仅支持 version: 1")
-    if (typeof input.id !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(input.id) || input.id.length > 64)
-      throw new Error("id 必须是最多 64 字符的小写短横线标识")
-    if (typeof input.name !== "string" || !input.name.trim() || input.name.length > 48)
-      throw new Error("name 必须是 1–48 个字符")
-    if (input.description !== undefined && (typeof input.description !== "string" || input.description.length > 160))
-      throw new Error("description 最多 160 个字符")
-    if (!isRecord(input.modes)) throw new Error("modes 必须是对象")
-    assertKnownKeys(input.modes, MODE_KEYS, "modes")
-    const light =
-      input.modes.light === undefined ? undefined : parseTokens(input.modes.light, TOKEN_KEY_SET, "modes.light")
-    const dark = input.modes.dark === undefined ? undefined : parseTokens(input.modes.dark, TOKEN_KEY_SET, "modes.dark")
-    if (!light && !dark) throw new Error("modes 至少需要 light 或 dark")
-
-    // DS2 两道闸：禁覆盖清单拦截 + 中性梯度整组对比度实算
-    if (light) {
-      assertTokensNotDenied(light, "modes.light")
-      assertNeutralGroupContrast(light, "modes.light")
-    }
-    if (dark) {
-      assertTokensNotDenied(dark, "modes.dark")
-      assertNeutralGroupContrast(dark, "modes.dark")
-    }
-
-    // Parse contributes (L2/L3)
-    let contributes: OrbitworkSkin["contributes"] | undefined
-    if (input.contributes !== undefined) {
-      if (!isRecord(input.contributes)) throw new Error("contributes 必须是对象")
-      assertKnownKeys(input.contributes, CONTRIBUTES_KEYS, "contributes")
-      const semanticStyles = input.contributes.semanticStyles
-      const patches = input.contributes.patches
-      if (semanticStyles !== undefined && typeof semanticStyles !== "string")
-        throw new Error("contributes.semanticStyles 必须是字符串")
-      if (patches !== undefined && typeof patches !== "string") throw new Error("contributes.patches 必须是字符串")
-      const registry = parseRegistry(input.contributes.registry)
-      if (semanticStyles || patches || registry) {
-        contributes = {
-          ...(semanticStyles ? { semanticStyles } : {}),
-          ...(patches ? { patches } : {}),
-          ...(registry ? { registry } : {}),
-        }
-      }
-    }
-
-    return {
-      ok: true,
-      skin: {
-        version: 1,
-        id: input.id,
-        name: input.name.trim(),
-        ...(input.description ? { description: input.description.trim() } : {}),
-        modes: { ...(light ? { light } : {}), ...(dark ? { dark } : {}) },
-        ...(contributes ? { contributes } : {}),
-      },
-    }
-  } catch (error) {
-    return { ok: false, error: error instanceof Error ? error.message : "主题格式无效" }
-  }
-}
-
-function parseTokens(input: unknown, allowed: Set<string>, path: string): OrbitworkSkinTokens {
-  if (!isRecord(input)) throw new Error(`${path} 必须是对象`)
-  assertKnownKeys(input, allowed, path)
-  const result: OrbitworkSkinTokens = {}
-  for (const [key, value] of Object.entries(input)) {
-    if (typeof value !== "string") throw new Error(`${path}.${key} 必须是字符串`)
-    if (COLOR_KEYS.includes(key as (typeof COLOR_KEYS)[number])) {
-      if (!HEX_COLOR.test(value)) throw new Error(`${path}.${key} 必须是十六进制颜色`)
-      ;(result as Record<string, string>)[key] = value.toLowerCase()
-    } else if (MASK_COLOR_KEYS.includes(key as (typeof MASK_COLOR_KEYS)[number])) {
-      if (!MASK_HEX_COLOR.test(value)) throw new Error(`${path}.${key} 必须是六位或八位十六进制颜色`)
-      ;(result as Record<string, string>)[key] = value.toLowerCase()
-    } else if (IMAGE_KEYS.includes(key as (typeof IMAGE_KEYS)[number])) {
-      assertSafeDataImage(value, `${path}.${key}`)
-      ;(result as Record<string, string>)[key] = value
-    } else if (POSITION_KEYS.includes(key as (typeof POSITION_KEYS)[number])) {
-      const normalized = value.toLowerCase()
-      if (!BACKGROUND_POSITIONS.has(normalized)) throw new Error(`${path}.${key} 不是支持的背景位置`)
-      ;(result as Record<string, string>)[key] = normalized
-    } else if (SIZE_KEYS.includes(key as (typeof SIZE_KEYS)[number])) {
-      const normalized = value.toLowerCase()
-      if (!BACKGROUND_SIZES.has(normalized)) throw new Error(`${path}.${key} 不是支持的背景尺寸`)
-      ;(result as Record<string, string>)[key] = normalized
-    } else {
-      throw new Error(`${path} 包含不支持的字段：${key}`)
-    }
-  }
-  return result
-}
-
-function parseRegistry(input: unknown): OrbitworkSkinRegistryEntry[] | undefined {
-  if (input === undefined) return undefined
-  if (!Array.isArray(input)) throw new Error("contributes.registry 必须是数组")
-  if (input.length === 0) return undefined
-  return input.map((entry, index) => {
-    if (!isRecord(entry)) throw new Error(`contributes.registry[${index}] 必须是 { target, reason } 对象`)
-    assertKnownKeys(entry, REGISTRY_ENTRY_KEYS, `contributes.registry[${index}]`)
-    const { target, reason } = entry
-    if (typeof target !== "string" || !target.trim() || target.length > 200)
-      throw new Error(`contributes.registry[${index}].target 必须是 1–200 字符的字符串`)
-    if (typeof reason !== "string" || !reason.trim() || reason.length > 200)
-      throw new Error(`contributes.registry[${index}].reason 必须是 1–200 字符的字符串`)
-    return { target: target.trim(), reason: reason.trim() }
-  })
-}
-
-function assertSafeDataImage(value: string, path: string): void {
-  const match = DATA_IMAGE.exec(value)
-  if (!match) throw new Error(`${path} 必须是 PNG、JPEG 或 WebP 的 base64 data URL`)
-  const format = match[1]
-  const payload = match[2]
-  if (!format || !payload) throw new Error(`${path} 包含无效的图片数据`)
-  if (payload.length % 4 !== 0) throw new Error(`${path} 包含无效的 base64 数据`)
-  const padding = payload.endsWith("==") ? 2 : payload.endsWith("=") ? 1 : 0
-  const decodedBytes = (payload.length / 4) * 3 - padding
-  if (decodedBytes > MAX_ORBITWORK_SKIN_IMAGE_BYTES) throw new Error(`${path} 解码后不能超过 5 MiB`)
-  let bytes: number[]
-  try {
-    const decoded = globalThis.atob(payload)
-    bytes = Array.from(decoded.slice(0, 12), (char) => char.charCodeAt(0))
-  } catch {
-    throw new Error(`${path} 包含无效的 base64 数据`)
-  }
-  const validMagic =
-    format === "png"
-      ? [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a].every((byte, index) => bytes[index] === byte)
-      : format === "jpeg"
-        ? bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff
-        : bytes[0] === 0x52 &&
-          bytes[1] === 0x49 &&
-          bytes[2] === 0x46 &&
-          bytes[3] === 0x46 &&
-          bytes[8] === 0x57 &&
-          bytes[9] === 0x45 &&
-          bytes[10] === 0x42 &&
-          bytes[11] === 0x50
-  if (!validMagic) throw new Error(`${path} 的内容与图片格式不匹配`)
-}
-
-/** Convert a validated embedded image into a CSS value without accepting arbitrary CSS or URLs. */
-export function orbitworkSkinImageCssValue(value: string | undefined): string | undefined {
-  if (!value) return undefined
-  try {
-    assertSafeDataImage(value, "chatBackgroundImage")
-    return `url("${value}")`
-  } catch {
-    return undefined
-  }
-}
-
-export function assertKnownKeys(value: Record<string, unknown>, allowed: Set<string>, path: string) {
-  const unknown = Object.keys(value).find((key) => !allowed.has(key))
-  if (unknown) throw new Error(`${path} 包含不支持的字段：${unknown}`)
-}
-
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-}