@orbit-work/ui 0.1.0

package/src/theme/core/skinScoped.ts

@@ -0,0 +1,289 @@
+/**
+ * Scoped skin application — inspired by design project
+ *
+ * 改进点：
+ * 1. 从内联样式改为 <style> 标签注入
+ * 2. 使用 html[data-ow-skin] 作用域选择器
+ * 3. CSS 层面真正隔离，可通过选择器精准控制
+ * 4. 支持 L2/L3 高级样式（语义选择器、自由补丁）
+ *
+ * 向后兼容：保持与原 applyOrbitworkSkin() 相同的签名和行为
+ */
+
+import { analyzeSkinCSS, sanitizeSkinCSSBasic } from "../utils/cssSafety.ts"
+import type { OrbitworkSkin, OrbitworkSkinTokens, ResolvedTheme } from "./skin.ts"
+import {
+  DS2_LOCKED_SLOT_SELECTORS,
+  ORBITWORK_SKIN_CSS_VARIABLES,
+  findDs2DeniedCssProperty,
+  findDs2DeniedCssValue,
+  isDs2SkinDeniedToken,
+  isDs2SkinDeniedValue,
+  orbitworkSkinImageCssValue,
+  resolveOrbitworkSkinChatBackgroundMask,
+} from "./skin.ts"
+
+const STYLE_ELEMENT_ID = "ow-skin-runtime"
+const SEMANTIC_STYLE_ELEMENT_ID = "ow-skin-semantic"
+const PATCH_STYLE_ELEMENT_ID = "ow-skin-patches"
+const CHAT_BACKGROUND_MASK_DERIVED_PROPERTIES = [
+  "--ow-chat-bg-mask-start-opacity",
+  "--ow-chat-bg-mask-end-opacity",
+] as const
+
+/** CSS 样式大小限制（256KB） */
+const MAX_CSS_SIZE = 256 * 1024
+
+/**
+ * 作用域化皮肤应用
+ *
+ * @example
+ * applyScopedOrbitworkSkin(document.documentElement, skin, 'light')
+ * // 生成: html[data-ow-skin="aurora"] { --ow-primary: #7c3aed; ... }
+ */
+export function applyScopedOrbitworkSkin(target: HTMLElement, skin: OrbitworkSkin | null, mode: ResolvedTheme): void {
+  // 清理旧的样式标签
+  let styleEl = document.getElementById(STYLE_ELEMENT_ID) as HTMLStyleElement | null
+
+  if (!skin || !skin.modes || !skin.modes[mode]) {
+    target.removeAttribute("data-ow-skin")
+    target.removeAttribute("data-chat-background-image")
+    styleEl?.remove()
+    removeScopedStyles(SEMANTIC_STYLE_ELEMENT_ID)
+    removeScopedStyles(PATCH_STYLE_ELEMENT_ID)
+    return
+  }
+
+  // 1. 设置作用域标记
+  target.setAttribute("data-ow-skin", skin.id)
+
+  // 2. 取当前模式 token（DS2：common/radius 已随皮肤边界取消）
+  const tokens = { ...skin.modes[mode] }
+
+  // 3. 生成 CSS 变量声明
+  const cssVariables: string[] = []
+  let hasChatBackgroundImage = false
+
+  for (const [key, value] of Object.entries(tokens)) {
+    const property = ORBITWORK_SKIN_CSS_VARIABLES[key as keyof OrbitworkSkinTokens]
+
+    if (key === "chatBackgroundMaskColor") {
+      const mask = resolveOrbitworkSkinChatBackgroundMask(value)
+      cssVariables.push(`  ${property}: ${mask.color};`)
+      cssVariables.push(`  --ow-chat-bg-mask-start-opacity: ${mask.startOpacity}%;`)
+      cssVariables.push(`  --ow-chat-bg-mask-end-opacity: ${mask.endOpacity}%;`)
+      continue
+    }
+
+    if (key === "chatBackgroundImage") {
+      const cssValue = orbitworkSkinImageCssValue(value)
+      if (cssValue) {
+        cssVariables.push(`  ${property}: ${cssValue};`)
+        hasChatBackgroundImage = true
+      }
+      continue
+    }
+
+    if (property && value) {
+      // DS2 闸 (a) 运行时兜底：落点命中禁覆盖清单的覆盖项直接丢弃
+      if (isDs2SkinDeniedToken(property)) {
+        console.warn(`[Orbitwork Skin] ${skin.id}: ${key} 的落点 ${property} 命中 DS2 禁覆盖清单，已忽略`)
+        continue
+      }
+      // 值维度兜底（判据 7 品牌外渐变一律清除）：落点名与属性名都合法、值是渐变的覆盖项，
+      // 此前两道闸都拦不住，直接落到气泡/侧栏底上。
+      if (isDs2SkinDeniedValue(value)) {
+        console.warn(`[Orbitwork Skin] ${skin.id}: ${key} 的值是渐变（${value}），DS2 禁品牌外渐变，已忽略`)
+        continue
+      }
+      cssVariables.push(`  ${property}: ${value};`)
+    }
+  }
+
+  // 4. 设置背景图标记（用于条件样式）
+  if (hasChatBackgroundImage) {
+    target.setAttribute("data-chat-background-image", "")
+  } else {
+    target.removeAttribute("data-chat-background-image")
+  }
+
+  // 5. 生成作用域样式
+  const scopedCss = `
+/* Orbitwork Skin: ${skin.name} (${mode}) */
+html[data-ow-skin="${skin.id}"] {
+${cssVariables.join("\n")}
+}
+`.trim()
+
+  // 6. 注入或更新样式
+  if (!styleEl) {
+    styleEl = document.createElement("style")
+    styleEl.id = STYLE_ELEMENT_ID
+    styleEl.setAttribute("data-ow-skin-mode", mode)
+    document.head.appendChild(styleEl)
+  } else {
+    styleEl.setAttribute("data-ow-skin-mode", mode)
+  }
+  styleEl.textContent = scopedCss
+
+  // 7. 应用 L2 语义样式（如果有）- 安全过滤
+  const scope = `html[data-ow-skin="${skin.id}"]`
+  if (skin.contributes?.semanticStyles) {
+    const report = analyzeSkinCSS(skin.contributes.semanticStyles)
+    if (!report.ok) {
+      console.warn(`[Orbitwork Skin] L2 语义样式存在安全风险 (${skin.id}):`, report.warnings)
+    }
+
+    const sanitized = stripDs2DeniedCSS(sanitizeSkinCSSBasic(skin.contributes.semanticStyles), skin.id, "L2")
+    const scopedSemanticCss = `
+/* Orbitwork Skin L2: ${skin.name} - Semantic Styles */
+${scopeSelectors(sanitized, scope)}
+`.trim()
+    injectScopedStyles(SEMANTIC_STYLE_ELEMENT_ID, scopedSemanticCss)
+  } else {
+    removeScopedStyles(SEMANTIC_STYLE_ELEMENT_ID)
+  }
+
+  // 8. 应用 L3 补丁样式（如果有）- 安全过滤
+  if (skin.contributes?.patches) {
+    const report = analyzeSkinCSS(skin.contributes.patches)
+    if (!report.ok) {
+      console.warn(`[Orbitwork Skin] L3 补丁样式存在安全风险 (${skin.id}):`, report.warnings)
+    }
+
+    const sanitized = stripDs2DeniedCSS(sanitizeSkinCSSBasic(skin.contributes.patches), skin.id, "L3")
+    const scopedPatchesCss = `
+/* Orbitwork Skin L3: ${skin.name} - Patches */
+${scopeSelectors(sanitized, scope)}
+`.trim()
+    injectScopedStyles(PATCH_STYLE_ELEMENT_ID, scopedPatchesCss)
+  } else {
+    removeScopedStyles(PATCH_STYLE_ELEMENT_ID)
+  }
+}
+
+/**
+ * 获取当前激活的皮肤 ID
+ */
+export function getActiveSkinId(): string | null {
+  return document.documentElement.getAttribute("data-ow-skin")
+}
+
+/**
+ * 检查是否有皮肤激活
+ */
+export function hasSkinActive(): boolean {
+  return getActiveSkinId() !== null
+}
+
+/**
+ * DS2 L2/L3 剥除闸（COMPONENT-RULES §15）：
+ * 整条规则命中以下任一即整块剥除，并 console.warn 报明细——
+ *  (a) 禁覆盖 token 名（设值或 var() 引用均算）；
+ *  (b) 锁定件 data-slot 选择器（字符串匹配）；
+ *  (c) 禁覆盖 CSS 属性（W5 补：box-shadow / border-radius / transform /
+ *      animation / transition / backdrop-filter）——贴地零影（§5）、
+ *      形状表定稿（§7）、唯一动效语汇＝信标（§9）三条不经 --ow-* 也要拦住；
+ *  (d) 禁覆盖**值形态**（R2 补：任何 *-gradient()）——判据 7「品牌外渐变一律清除」。
+ *      按属性名封 background 会把皮肤合法的改底一起封掉，要拦的是值的形态。
+ * @media/@keyframes 等 @ 块按整块判定（内部命中即整块剥除，宁严勿漏）。
+ */
+function stripDs2DeniedCSS(css: string, skinId: string, layer: "L2" | "L3"): string {
+  const removed: string[] = []
+  const result = filterTopLevelCssBlocks(css, (block) => {
+    const violation = findDs2CssViolation(block)
+    if (violation) removed.push(violation)
+    return !violation
+  })
+  if (removed.length > 0) {
+    console.warn(`[Orbitwork Skin] ${layer} 内容命中 DS2 禁覆盖，已剥除 (${skinId}):`, removed)
+  }
+  return result
+}
+
+function findDs2CssViolation(block: string): string | null {
+  for (const slot of DS2_LOCKED_SLOT_SELECTORS) {
+    if (block.includes(slot)) return `锁定件选择器 "${slot}"`
+  }
+  const tokenNames = block.match(/--ow-[a-z0-9-]+/gi) ?? []
+  for (const tokenName of tokenNames) {
+    if (isDs2SkinDeniedToken(tokenName)) return `禁覆盖 token ${tokenName}`
+  }
+  const property = findDs2DeniedCssProperty(block)
+  if (property) return `禁覆盖 CSS 属性 ${property}`
+  const gradient = findDs2DeniedCssValue(block)
+  if (gradient) return `禁覆盖值形态 ${gradient}()`
+  return null
+}
+
+/** 按顶层花括号块切分 CSS，逐块决定去留（无依赖的轻量实现，与 scopeSelectors 同精度）。 */
+function filterTopLevelCssBlocks(css: string, keep: (block: string) => boolean): string {
+  const out: string[] = []
+  let i = 0
+  while (i < css.length) {
+    const open = css.indexOf("{", i)
+    if (open === -1) {
+      out.push(css.slice(i))
+      break
+    }
+    let depth = 1
+    let j = open + 1
+    while (j < css.length && depth > 0) {
+      if (css[j] === "{") depth++
+      else if (css[j] === "}") depth--
+      j++
+    }
+    const block = css.slice(i, j)
+    if (keep(block)) out.push(block)
+    i = j
+  }
+  return out.join("")
+}
+
+/**
+ * 给 CSS 选择器添加作用域前缀
+ *
+ * @example
+ * scopeSelectors('[data-ow-part="message-bubble"] { ... }', 'html[data-ow-skin="aurora"]')
+ * // => 'html[data-ow-skin="aurora"] [data-ow-part="message-bubble"] { ... }'
+ */
+function scopeSelectors(css: string, scope: string): string {
+  // 简化实现：给每个选择器块加前缀
+  // 注意：这是简化版，完整实现需要 CSS parser（如 postcss）
+  return css.replace(/([^{}]+)\{/g, (match, selector) => {
+    const trimmed = selector.trim()
+    // 跳过 @规则（@media, @keyframes 等）
+    if (trimmed.startsWith("@")) {
+      return match
+    }
+    // 添加作用域前缀
+    return `${scope} ${trimmed} {`
+  })
+}
+
+/**
+ * 注入作用域样式到 <style> 标签
+ */
+function injectScopedStyles(elementId: string, css: string): void {
+  // 大小检查
+  const byteLength = new Blob([css]).size
+  if (byteLength > MAX_CSS_SIZE) {
+    console.warn(`[ow-skin] CSS size (${byteLength} bytes) exceeds limit (${MAX_CSS_SIZE} bytes), skipping`)
+    return
+  }
+
+  let styleEl = document.getElementById(elementId) as HTMLStyleElement | null
+  if (!styleEl) {
+    styleEl = document.createElement("style")
+    styleEl.id = elementId
+    document.head.appendChild(styleEl)
+  }
+  styleEl.textContent = css
+}
+
+/**
+ * 移除作用域样式
+ */
+function removeScopedStyles(elementId: string): void {
+  document.getElementById(elementId)?.remove()
+}

package/src/theme/core/tenantTheme.test.mjs

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+/**
+ * parseTenantTheme 契约校验测试。框架与入口照抄同目录 skins.test.mjs 的 node:test 模式
+ * （package.json test 脚本用 node --test 只收 .mjs）。
+ */
+const { parseTenantTheme } = await import("./tenantTheme.ts")
+
+const VALID_THEME = {
+  name: "acme",
+  logo: "",
+  colors: {
+    bg: "#F7F6F1",
+    surface: "#FDFDFC",
+    surface2: "#F1F0EA",
+    text: "#333B50",
+    text2: "#646B7A",
+    text3: "#A2A5A9",
+    border: "#DCDCD7",
+    borderStrong: "#C2C3C1",
+  },
+  typography: { fontSans: "system-ui, sans-serif", fontMono: "monospace" },
+  branding: { productName: "ACME Suite", companyName: "ACME Inc" },
+}
+
+test("完整合法对象 round-trip", () => {
+  const result = parseTenantTheme(VALID_THEME)
+  assert.ok(result.ok)
+  assert.equal(result.theme.name, "acme")
+  assert.equal(result.theme.branding.productName, "ACME Suite")
+})
+
+test("branding 可选字段全缺省 → ok，且结果不含这些键", () => {
+  const result = parseTenantTheme(VALID_THEME)
+  assert.ok(result.ok)
+  assert.equal("claim" in result.theme.branding, false)
+  assert.equal("claimNote" in result.theme.branding, false)
+  assert.equal("slogan" in result.theme.branding, false)
+})
+
+test("branding 可选字段齐发 → 原样通过", () => {
+  const result = parseTenantTheme({
+    ...VALID_THEME,
+    branding: {
+      ...VALID_THEME.branding,
+      claim: "智能工作，从登录开始",
+      claimNote: "连接你的团队与 AI 助手",
+      slogan: "交给工作，继续生活。",
+    },
+  })
+  assert.ok(result.ok)
+  assert.equal(result.theme.branding.claim, "智能工作，从登录开始")
+  assert.equal(result.theme.branding.slogan, "交给工作，继续生活。")
+})
+
+test("根级未知键 → ok:false", () => {
+  const result = parseTenantTheme({ ...VALID_THEME, unexpected: true })
+  assert.equal(result.ok, false)
+})
+
+test("colors 未知键 / 缺键 → ok:false", () => {
+  assert.equal(parseTenantTheme({ ...VALID_THEME, colors: { ...VALID_THEME.colors, extra: "#fff" } }).ok, false)
+  const { borderStrong, ...missingOne } = VALID_THEME.colors
+  assert.equal(parseTenantTheme({ ...VALID_THEME, colors: missingOne }).ok, false)
+})
+
+test("branding 未知键 → ok:false", () => {
+  const result = parseTenantTheme({
+    ...VALID_THEME,
+    branding: { ...VALID_THEME.branding, tagline: "x" },
+  })
+  assert.equal(result.ok, false)
+})
+
+test("非 hex 色 → ok:false", () => {
+  const result = parseTenantTheme({ ...VALID_THEME, colors: { ...VALID_THEME.colors, bg: "red" } })
+  assert.equal(result.ok, false)
+})
+
+test("productName 为空 → ok:false", () => {
+  const result = parseTenantTheme({ ...VALID_THEME, branding: { ...VALID_THEME.branding, productName: "  " } })
+  assert.equal(result.ok, false)
+})
+
+test("claim 超 24 / slogan 超 48 → ok:false", () => {
+  const longClaim = "a".repeat(25)
+  const longSlogan = "b".repeat(49)
+  assert.equal(parseTenantTheme({ ...VALID_THEME, branding: { ...VALID_THEME.branding, claim: longClaim } }).ok, false)
+  assert.equal(
+    parseTenantTheme({ ...VALID_THEME, branding: { ...VALID_THEME.branding, slogan: longSlogan } }).ok,
+    false,
+  )
+})
+
+test("边界长度恰好在限内 → ok", () => {
+  const result = parseTenantTheme({
+    ...VALID_THEME,
+    branding: { ...VALID_THEME.branding, claim: "a".repeat(24), slogan: "b".repeat(48) },
+  })
+  assert.ok(result.ok)
+})
+
+test("logo 传 javascript: 或裸串 → ok:false；空串与 data URI → ok", () => {
+  assert.equal(parseTenantTheme({ ...VALID_THEME, logo: "javascript:alert(1)" }).ok, false)
+  assert.equal(parseTenantTheme({ ...VALID_THEME, logo: "not-a-url" }).ok, false)
+  assert.ok(parseTenantTheme({ ...VALID_THEME, logo: "" }).ok)
+  assert.ok(parseTenantTheme({ ...VALID_THEME, logo: "data:image/svg+xml;base64,AAAA" }).ok)
+  assert.ok(parseTenantTheme({ ...VALID_THEME, logo: "https://cdn.example.com/logo.png" }).ok)
+})
+
+test("favicon 缺省 → ok；非法 → ok:false", () => {
+  assert.ok(parseTenantTheme(VALID_THEME).ok)
+  assert.equal(parseTenantTheme({ ...VALID_THEME, favicon: "ftp://x/f.ico" }).ok, false)
+})
+
+test("非对象输入 → ok:false", () => {
+  assert.equal(parseTenantTheme(null).ok, false)
+  assert.equal(parseTenantTheme("string").ok, false)
+  assert.equal(parseTenantTheme([VALID_THEME]).ok, false)
+})
+
+test("失败结果携带可读 error", () => {
+  const result = parseTenantTheme({ ...VALID_THEME, colors: { ...VALID_THEME.colors, bg: "oops" } })
+  assert.equal(result.ok, false)
+  assert.ok(result.error.includes("colors.bg"))
+})

package/src/theme/core/tenantTheme.ts

@@ -0,0 +1,124 @@
+/**
+ * TenantTheme 契约校验器（GET /api/v1/tenant/theme 的响应体）。
+ *
+ * 严格按 theme/core/types.ts 的契约解析：未知键、错误形态一律拒绝，不认任何
+ * 变体/旧格式（与 parseOrbitworkSkin 同一铁律）。branding 文本可选字段缺省是
+ * 合法的——消费方（组件 props 默认值）负责 fallthrough，不是兼容层。
+ */
+
+import { HEX_COLOR, assertKnownKeys, isRecord } from "./skin.ts"
+import type { TenantBranding, TenantTheme } from "./types.ts"
+
+export type TenantThemeValidationResult = { ok: true; theme: TenantTheme } | { ok: false; error: string }
+
+const ROOT_KEYS = new Set(["name", "logo", "favicon", "colors", "typography", "branding"])
+
+const COLOR_KEYS = new Set(["bg", "surface", "surface2", "text", "text2", "text3", "border", "borderStrong"])
+
+const TYPOGRAPHY_KEYS = new Set(["fontSans", "fontMono"])
+
+const BRANDING_KEYS = new Set(["productName", "companyName", "claim", "claimNote", "slogan"])
+
+const LENGTH_LIMITS = {
+  name: 48,
+  productName: 48,
+  companyName: 64,
+  claim: 24,
+  claimNote: 32,
+  slogan: 48,
+} as const
+
+const FONT_STACK_LIMIT = 400
+/** data-uri 场景的字符串上限（约 1MB） */
+const ASSET_STRING_LIMIT = 1_048_576
+
+/** 品牌图合法形态：空串 / data:image/(png|svg+xml|webp|jpeg) / http(s)://。拒绝 javascript: 等裸串。 */
+const ASSET_URL_PATTERN = /^(?:$|data:image\/(?:png|svg\+xml|webp|jpeg);|https?:\/\/)/i
+
+function parseAsset(value: unknown, path: string, required: boolean): string | undefined {
+  if (value === undefined) {
+    if (required) throw new Error(`${path} 必填`)
+    return undefined
+  }
+  if (typeof value !== "string") throw new Error(`${path} 必须是字符串`)
+  if (value.length > ASSET_STRING_LIMIT) throw new Error(`${path} 超出长度上限`)
+  if (!ASSET_URL_PATTERN.test(value)) throw new Error(`${path} 必须是 data:image URI 或 http(s) URL`)
+  return value
+}
+
+function parseLimitedText(value: unknown, path: string, limit: number, required: boolean): string | undefined {
+  if (value === undefined) {
+    if (required) throw new Error(`${path} 必填`)
+    return undefined
+  }
+  if (typeof value !== "string") throw new Error(`${path} 必须是字符串`)
+  if (value.trim().length === 0) throw new Error(`${path} 不能为空`)
+  if (value.length > limit) throw new Error(`${path} 超出长度上限（${limit}）`)
+  return value
+}
+
+function parseBranding(input: unknown): TenantBranding {
+  if (!isRecord(input)) throw new Error("branding 必须是对象")
+  assertKnownKeys(input, BRANDING_KEYS, "branding")
+
+  const productName = parseLimitedText(input.productName, "branding.productName", LENGTH_LIMITS.productName, true)
+  const companyName = parseLimitedText(input.companyName, "branding.companyName", LENGTH_LIMITS.companyName, true)
+
+  const branding: TenantBranding = { productName: productName as string, companyName: companyName as string }
+  const claim = parseLimitedText(input.claim, "branding.claim", LENGTH_LIMITS.claim, false)
+  const claimNote = parseLimitedText(input.claimNote, "branding.claimNote", LENGTH_LIMITS.claimNote, false)
+  const slogan = parseLimitedText(input.slogan, "branding.slogan", LENGTH_LIMITS.slogan, false)
+  if (claim !== undefined) branding.claim = claim
+  if (claimNote !== undefined) branding.claimNote = claimNote
+  if (slogan !== undefined) branding.slogan = slogan
+  return branding
+}
+
+export function parseTenantTheme(input: unknown): TenantThemeValidationResult {
+  try {
+    if (!isRecord(input)) throw new Error("租户主题必须是 JSON 对象")
+    assertKnownKeys(input, ROOT_KEYS, "租户主题")
+
+    const name = parseLimitedText(input.name, "name", LENGTH_LIMITS.name, true)
+    const logo = parseAsset(input.logo, "logo", true)
+    const favicon = parseAsset(input.favicon, "favicon", false)
+
+    if (!isRecord(input.colors)) throw new Error("colors 必须是对象")
+    assertKnownKeys(input.colors, COLOR_KEYS, "colors")
+    const colors = {} as TenantTheme["colors"]
+    for (const key of COLOR_KEYS) {
+      const value = input.colors[key]
+      if (typeof value !== "string" || !HEX_COLOR.test(value)) {
+        throw new Error(`colors.${key} 必须是十六进制颜色`)
+      }
+      ;(colors as Record<string, string>)[key] = value
+    }
+
+    if (!isRecord(input.typography)) throw new Error("typography 必须是对象")
+    assertKnownKeys(input.typography, TYPOGRAPHY_KEYS, "typography")
+    const fontSans = input.typography.fontSans
+    const fontMono = input.typography.fontMono
+    if (typeof fontSans !== "string" || fontSans.length > FONT_STACK_LIMIT) {
+      throw new Error("typography.fontSans 必须是字符串")
+    }
+    if (typeof fontMono !== "string" || fontMono.length > FONT_STACK_LIMIT) {
+      throw new Error("typography.fontMono 必须是字符串")
+    }
+
+    const branding = parseBranding(input.branding)
+
+    return {
+      ok: true,
+      theme: {
+        name: name as string,
+        logo: logo as string,
+        ...(favicon !== undefined ? { favicon } : {}),
+        colors,
+        typography: { fontSans, fontMono },
+        branding,
+      },
+    }
+  } catch (cause) {
+    return { ok: false, error: cause instanceof Error ? cause.message : String(cause) }
+  }
+}

package/src/theme/core/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Tenant theme configuration
+ * Represents the response from GET /api/v1/tenant/theme
+ *
+ * R2：这份类型原来是一整套 V1/Tailwind 色位（primary/primaryHover ＋ bg1-3/fg1-3/line1-3），
+ * 与 DS 2.0 的面/字/线三层语义毫无关系。现改为 DS2 语义位。
+ *
+ * 落点说明（见 utils/themeApplier.ts）：租户能改的是**中性梯度与字栈**。行动极
+ * （--ow-primary*）在 DS2 禁覆盖清单上，租户主题改不动，故本类型里不再有 primary
+ * 字段——留着就是个应用不上的承诺（原 applyTenantTheme 里那两行每次切主题固定刷两条
+ * console.warn）。
+ */
+/**
+ * 租户品牌素材（GET /api/v1/tenant/theme 的 branding 字段）。
+ *
+ * 文本可选字段的缺省语义是 fallthrough：后端不下发 → 组件回落到包内默认文案
+ * （Orbitwork 默认品牌），**不是**旧格式兼容——parseTenantTheme 对未知键/变体一律拒绝。
+ * 长度卡是为防超长租户文案撑破登录版面。
+ */
+export type TenantBranding = {
+  productName: string
+  companyName: string
+  /** 登录 KV 板主宣传语（≤24）；缺省回落 DesktopLoginView 的 DESKTOP_LOGIN_CLAIM */
+  claim?: string
+  /** 登录 KV 板副宣传语（≤32）；缺省回落 DESKTOP_LOGIN_CLAIM_NOTE */
+  claimNote?: string
+  /** 品牌级短口号（≤48，分享条中部等露出）；缺省回落 ShareStrip 默认文案 */
+  slogan?: string
+}
+
+export type TenantTheme = {
+  name: string
+  /** 品牌图。内联 data-uri 或空串——演示数据不引外网图源。 */
+  logo: string
+  /** 站点图标。形态同 logo。 */
+  favicon?: string
+  colors: {
+    /** 页面地 → --ow-bg */
+    bg: string
+    /** 卡/面 → --ow-surface */
+    surface: string
+    /** 嵌套井/输入底 → --ow-surface-2 */
+    surface2: string
+    /** 正文字 → --ow-text */
+    text: string
+    /** 次级字 → --ow-text-2 */
+    text2: string
+    /** 弱字 → --ow-text-3 */
+    text3: string
+    /** 发丝线/默认边 → --ow-border */
+    border: string
+    /** 强调边（hover/选中态描边） → --ow-border-strong */
+    borderStrong: string
+  }
+  typography: {
+    fontSans: string
+    fontMono: string
+  }
+  branding: TenantBranding
+}