@orbit-work/ui 0.1.0

package/src/theme/core/skin.ts

@@ -0,0 +1,605 @@
+/**
+ * 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)
+}