@orbit-work/ui 0.1.0

package/src/lib/appearance.test.mjs

@@ -0,0 +1,283 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+const {
+  applyOrbitworkSkin,
+  orbitworkSkinChatBackgroundMaskColor,
+  BUILTIN_ORBITWORK_SKINS,
+  hasOrbitworkSkinChatBackground,
+  parseOrbitworkSkin,
+  resolveOrbitworkSkinChatBackgroundMask,
+} = await import("./appearance.ts")
+const PNG_DATA_URL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB"
+
+// DS2（COMPONENT-RULES §15）：primary/link/switchActive/功能色/common 圆角已从皮肤白名单移除；
+// 中性梯度触发整组提交 + 对比度实算，故 light/dark 均给出完整中性组。
+const validSkin = {
+  version: 1,
+  id: "ocean-night",
+  name: "  Ocean Night  ",
+  description: "A calm workspace",
+  modes: {
+    light: {
+      buttonPrimaryBackground: "#0EA5E9",
+      backgroundPrimary: "#ffffff",
+      backgroundSecondary: "#f5f5f2",
+      backgroundTertiary: "#ecebe6",
+      foregroundPrimary: "#1f1f1c",
+      foregroundSecondary: "#55554e",
+    },
+    dark: {
+      buttonPrimaryBackground: "#38bdf8",
+      backgroundPrimary: "#0c1520",
+      backgroundSecondary: "#111c29",
+      backgroundTertiary: "#182636",
+      foregroundPrimary: "#e8ecf1",
+      foregroundSecondary: "#a7b1bd",
+    },
+  },
+}
+
+function createMockDocument() {
+  const attributes = new Map()
+  const elements = new Map()
+  const removed = new Set()
+  const target = {
+    setAttribute: (key, value) => attributes.set(key, value),
+    removeAttribute: (key) => attributes.delete(key),
+    getAttribute: (key) => attributes.get(key) ?? null,
+  }
+  const head = {
+    appendChild: (el) => {
+      elements.set(el.getAttribute("id") ?? el.id, el)
+    },
+  }
+  const document = {
+    documentElement: target,
+    head,
+    getElementById: (id) => {
+      for (const el of elements.values()) {
+        if (removed.has(el)) continue
+        if ((el.getAttribute("id") ?? el.id) === id) return el
+      }
+      return null
+    },
+    createElement: () => {
+      const attrs = new Map()
+      const el = {
+        textContent: "",
+        attrs,
+        setAttribute(key, value) {
+          attrs.set(key, value)
+        },
+        getAttribute(key) {
+          return attrs.get(key) ?? null
+        },
+        remove() {
+          removed.add(this)
+        },
+      }
+      Object.defineProperty(el, "id", {
+        get() {
+          return attrs.get("id") ?? ""
+        },
+        set(value) {
+          attrs.set("id", value)
+        },
+      })
+      return el
+    },
+  }
+  return { document, target, elements, removed, attributes }
+}
+
+test("parseOrbitworkSkin validates and normalizes a supported theme", () => {
+  const parsed = parseOrbitworkSkin(validSkin)
+  assert.equal(parsed.ok, true)
+  assert.equal(parsed.skin.name, "Ocean Night")
+  assert.equal(parsed.skin.modes.light.buttonPrimaryBackground, "#0ea5e9")
+  assert.equal(parsed.skin.common, undefined)
+})
+
+test("parseOrbitworkSkin preserves validated embedded images and normalizes background options", () => {
+  const parsed = parseOrbitworkSkin({
+    ...validSkin,
+    modes: {
+      light: {
+        chatBackgroundImage: PNG_DATA_URL,
+        chatBackgroundPosition: "Top Right",
+        chatBackgroundSize: "COVER",
+        chatBackgroundOverlay: "#FFFFFF99",
+        chatBackgroundMaskColor: "#ABCDEF",
+        userBubbleBackground: "#123456",
+      },
+    },
+  })
+  assert.equal(parsed.ok, true)
+  assert.equal(parsed.skin.modes.light.chatBackgroundImage, PNG_DATA_URL)
+  assert.equal(parsed.skin.modes.light.chatBackgroundPosition, "top right")
+  assert.equal(parsed.skin.modes.light.chatBackgroundSize, "cover")
+  assert.equal(parsed.skin.modes.light.chatBackgroundOverlay, "#ffffff99")
+  assert.equal(parsed.skin.modes.light.chatBackgroundMaskColor, "#abcdef")
+})
+
+test("chat background presence follows the active light or dark skin mode", () => {
+  const skin = {
+    ...validSkin,
+    modes: { light: { chatBackgroundImage: PNG_DATA_URL }, dark: { buttonPrimaryBackground: "#38bdf8" } },
+  }
+  assert.equal(hasOrbitworkSkinChatBackground(skin, "light"), true)
+  assert.equal(hasOrbitworkSkinChatBackground(skin, "dark"), false)
+  assert.equal(hasOrbitworkSkinChatBackground(null, "light"), false)
+})
+
+test("parseOrbitworkSkin rejects unknown fields and unsafe token values", () => {
+  for (const candidate of [
+    { ...validSkin, css: "body {}" },
+    { ...validSkin, modes: { ...validSkin.modes, sepia: {} } },
+    { ...validSkin, modes: { light: { unknownToken: "#fff" } } },
+    { ...validSkin, modes: { light: { buttonPrimaryBackground: "url(https://example.com/a.png)" } } },
+    { ...validSkin, modes: { light: { buttonPrimaryBackground: "var(--secret)" } } },
+    { ...validSkin, modes: { light: { buttonPrimaryBackground: "#fff; color: red" } } },
+    // DS2 §15：已移除的皮肤覆盖位一律拒绝
+    { ...validSkin, modes: { light: { primary: "#0ea5e9" } } },
+    { ...validSkin, modes: { light: { link: "#0ea5e9" } } },
+    { ...validSkin, modes: { light: { switchActive: "#0ea5e9" } } },
+    { ...validSkin, modes: { light: { success: "#22c55e" } } },
+    { ...validSkin, common: { cardRadius: "12px" } },
+    { ...validSkin, common: {} },
+    // DS2 中性梯度闸：整组提交、对比度 ≥ 4.5:1
+    { ...validSkin, modes: { light: { backgroundPrimary: "#ffffff" } } },
+    {
+      ...validSkin,
+      modes: {
+        light: { ...validSkin.modes.light, foregroundSecondary: "#cccccc" },
+      },
+    },
+    { ...validSkin, modes: { light: { chatBackgroundImage: "https://example.com/a.png" } } },
+    { ...validSkin, modes: { light: { chatBackgroundImage: "data:image/svg+xml;base64,PHN2Zz4=" } } },
+    { ...validSkin, modes: { light: { chatBackgroundImage: "data:image/png;base64,bm90LXJlYWxseS1hLXBuZw==" } } },
+    { ...validSkin, modes: { light: { chatBackgroundPosition: "20% 40%" } } },
+    { ...validSkin, modes: { light: { chatBackgroundSize: "100% 100%" } } },
+    { ...validSkin, modes: { light: { chatBackgroundMaskColor: "#fff" } } },
+    { ...validSkin, modes: { light: { chatBackgroundMaskColor: "black" } } },
+  ]) {
+    assert.equal(parseOrbitworkSkin(candidate).ok, false)
+  }
+})
+
+test("parseOrbitworkSkin accepts mask colors with an alpha channel", () => {
+  const parsed = parseOrbitworkSkin({
+    ...validSkin,
+    modes: { light: { chatBackgroundMaskColor: "#FF336680" } },
+  })
+  assert.equal(parsed.ok, true)
+  assert.equal(parsed.skin.modes.light.chatBackgroundMaskColor, "#ff336680")
+})
+
+test("mask strength preserves the default gradient and reaches full coverage at 100%", () => {
+  assert.deepEqual(resolveOrbitworkSkinChatBackgroundMask("#000000"), {
+    color: "#000000",
+    strength: 80,
+    startOpacity: 80,
+    endOpacity: 50,
+  })
+  assert.deepEqual(resolveOrbitworkSkinChatBackgroundMask("#000000ff"), {
+    color: "#000000",
+    strength: 100,
+    startOpacity: 100,
+    endOpacity: 100,
+  })
+  assert.equal(orbitworkSkinChatBackgroundMaskColor("#000000", 100), "#000000ff")
+  assert.equal(orbitworkSkinChatBackgroundMaskColor("#FFFFFF", 0), "#ffffff00")
+})
+
+test("parseOrbitworkSkin accepts images up to 5 MiB and rejects larger images", () => {
+  const maximumPng = Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    Buffer.alloc(5 * 1024 * 1024 - 8),
+  ]).toString("base64")
+  assert.equal(
+    parseOrbitworkSkin({
+      ...validSkin,
+      modes: { light: { chatBackgroundImage: `data:image/png;base64,${maximumPng}` } },
+    }).ok,
+    true,
+  )
+
+  const oversizedPng = Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    Buffer.alloc(5 * 1024 * 1024 - 7),
+  ]).toString("base64")
+  assert.equal(
+    parseOrbitworkSkin({
+      ...validSkin,
+      modes: { light: { chatBackgroundImage: `data:image/png;base64,${oversizedPng}` } },
+    }).ok,
+    false,
+  )
+})
+
+test("parseOrbitworkSkin rejects common radius overrides and validates built-ins", () => {
+  // DS2 §15：圆角是品牌定稿，common 字段整体取消
+  assert.equal(parseOrbitworkSkin({ ...validSkin, common: { cardRadius: "32px" } }).ok, false)
+  assert.equal(parseOrbitworkSkin({ ...validSkin, common: { buttonRadius: "8px" } }).ok, false)
+  // 与旧测试同范围：仅前三个 L1 内建皮肤走严格解析（cyberpunk/glass 含 rgba/gradient，
+  // 历来不过 hex-only 解析器，属 P1 遗留）
+  for (const skin of [BUILTIN_ORBITWORK_SKINS[0], BUILTIN_ORBITWORK_SKINS[1], BUILTIN_ORBITWORK_SKINS[2]]) {
+    assert.equal(parseOrbitworkSkin(skin).ok, true, `内建皮肤 ${skin.id} 应通过 DS2 校验`)
+  }
+})
+
+test("applyOrbitworkSkin replaces managed values between modes and resets cleanly", () => {
+  const { document, target, attributes, elements } = createMockDocument()
+  global.document = document
+  try {
+    const parsed = parseOrbitworkSkin(validSkin)
+    assert.equal(parsed.ok, true)
+
+    applyOrbitworkSkin(target, parsed.skin, "light")
+    assert.equal(attributes.get("data-ow-skin"), "ocean-night")
+    assert.equal(attributes.has("data-chat-background-image"), false)
+    const lightStyle = elements.get("ow-skin-runtime")
+    assert.ok(lightStyle)
+    assert.match(lightStyle.textContent, /--ow-btn-primary-bg:\s*#0ea5e9;/)
+    assert.match(lightStyle.textContent, /--ow-bg:\s*#ffffff;/)
+    // DS2 §15：--ow-primary 不再是皮肤覆盖位
+    assert.doesNotMatch(lightStyle.textContent, /--ow-primary:/)
+
+    applyOrbitworkSkin(target, parsed.skin, "dark")
+    assert.equal(attributes.get("data-ow-skin"), "ocean-night")
+    const darkStyle = elements.get("ow-skin-runtime")
+    assert.match(darkStyle.textContent, /--ow-btn-primary-bg:\s*#38bdf8;/)
+    assert.match(darkStyle.textContent, /--ow-bg:\s*#0c1520;/)
+    // DS2 §15：圆角是品牌定稿，皮肤不再输出 --ow-radius-*
+    assert.doesNotMatch(darkStyle.textContent, /--ow-radius-/)
+
+    const withImage = parseOrbitworkSkin({
+      ...validSkin,
+      modes: {
+        light: {
+          chatBackgroundImage: PNG_DATA_URL,
+          chatBackgroundMaskColor: "#FFFFFF",
+          composerBackground: "#ffffffcc",
+        },
+      },
+    })
+    assert.equal(withImage.ok, true)
+    applyOrbitworkSkin(target, withImage.skin, "light")
+    assert.match(elements.get("ow-skin-runtime").textContent, /--ow-chat-bg-image:\s*url\("[^"]+"\);/)
+    assert.match(elements.get("ow-skin-runtime").textContent, /--ow-chat-bg-mask-color:\s*#ffffff;/)
+    assert.match(elements.get("ow-skin-runtime").textContent, /--ow-chat-bg-mask-start-opacity:\s*80%;/)
+    assert.match(elements.get("ow-skin-runtime").textContent, /--ow-chat-bg-mask-end-opacity:\s*50%;/)
+    assert.match(elements.get("ow-skin-runtime").textContent, /--ow-composer-bg:\s*#ffffffcc;/)
+    assert.equal(attributes.has("data-chat-background-image"), true)
+
+    applyOrbitworkSkin(target, null, "dark")
+    assert.equal(attributes.has("data-skin"), false)
+    assert.equal(attributes.has("data-ow-skin"), false)
+    assert.equal(attributes.has("data-chat-background-image"), false)
+  } finally {
+    delete global.document
+  }
+})

package/src/lib/appearance.ts

@@ -0,0 +1,46 @@
+/**
+ * @deprecated Import from './theme' instead. This file re-exports for backward compatibility.
+ *
+ * 例外：`THEME_OPTIONS`（文件末）是本文件自有的值——设置面与账户菜单共用的主题三格。
+ */
+
+/* THEME_OPTIONS 的元素类型＝Theme 本体（light | dark | system）；
+   本文件其余部分是纯 re-export 壳，值侧要用这个类型就得自己 import 一次。 */
+import type { Theme as ThemeOptionValue } from "../theme/core/skin.ts"
+
+export type {
+  Theme,
+  ResolvedTheme,
+  OrbitworkSkin,
+  OrbitworkSkinTokens,
+  OrbitworkSkinChatBackgroundMask,
+  SkinValidationResult,
+} from "../theme/core/skin.ts"
+
+export {
+  ORBITWORK_SKIN_CSS_VARIABLES,
+  MAX_ORBITWORK_SKIN_IMAGE_BYTES,
+  resolveOrbitworkSkinChatBackgroundMask,
+  orbitworkSkinChatBackgroundMaskColor,
+  orbitworkSkinImageCssValue,
+  hasOrbitworkSkinChatBackground,
+  parseOrbitworkSkin,
+} from "../theme/core/skin.ts"
+
+export { BUILTIN_ORBITWORK_SKINS } from "../theme/skins/index.ts"
+
+export { applyScopedOrbitworkSkin as applyOrbitworkSkin } from "../theme/core/skinScoped.ts"
+
+/**
+ * 主题三格（R2 · D4 / 裁决：设置常规段与账户菜单「外观」行共用同一份选项）。
+ *
+ * 原型的 themeRows 只有「浅色 / 深色」两档、另配一条「显示模式跟随系统」开关；
+ * R2 按 Terry 的参考图把三件事收成一排三格——`system` 就是第三格「自动」，
+ * 那条开关卡随之撤除。写在这里而不是各件各写一份：设置面（DesktopAppearanceSettings）
+ * 与侧栏账户菜单（DesktopAccountMenuView）两处必须同词同序，分叉了就是两套语汇。
+ */
+export const THEME_OPTIONS: Array<{ value: ThemeOptionValue; label: string }> = [
+  { value: "light", label: "浅色" },
+  { value: "dark", label: "深色" },
+  { value: "system", label: "自动" },
+]

package/src/lib/browser-annotation-popup.ts

@@ -0,0 +1,151 @@
+export type BrowserAnnotationPropertyType = "text" | "color" | "number" | "select" | "spacing"
+
+export interface BrowserAnnotationPropertyDefinition {
+  key: string
+  label: string
+  cssProp: string
+  type: BrowserAnnotationPropertyType
+  unit?: string
+  options?: readonly string[]
+  step?: number
+  min?: number
+  max?: number
+}
+
+/**
+ * Annotation properties shared by the WebView runtime and the React preview.
+ * Keep this module free of React and DOM imports so Electron can bundle it in
+ * the sandboxed guest preload without pulling in the component library.
+ */
+export const BROWSER_ANNOTATION_PROPERTY_DEFS: readonly BrowserAnnotationPropertyDefinition[] = [
+  { key: "textContent", label: "文本", cssProp: "", type: "text" },
+  { key: "color", label: "文本颜色", cssProp: "color", type: "color" },
+  { key: "backgroundColor", label: "背景", cssProp: "backgroundColor", type: "color" },
+  { key: "opacity", label: "Opacity", cssProp: "opacity", type: "number", step: 0.1, min: 0, max: 1 },
+  { key: "fontFamily", label: "字体", cssProp: "fontFamily", type: "select", options: [] },
+  { key: "fontSize", label: "字号", cssProp: "fontSize", type: "number", unit: "px" },
+  {
+    key: "fontWeight",
+    label: "字重",
+    cssProp: "fontWeight",
+    type: "select",
+    options: ["100", "200", "300", "400", "500", "600", "700", "800", "900"],
+  },
+  { key: "borderRadius", label: "边框圆角半径", cssProp: "borderRadius", type: "number", unit: "px" },
+  { key: "borderColor", label: "边框颜色", cssProp: "borderColor", type: "color" },
+  { key: "borderWidth", label: "边框宽度", cssProp: "borderWidth", type: "number", unit: "px" },
+  { key: "width", label: "宽度", cssProp: "width", type: "number", unit: "px" },
+  { key: "height", label: "高度", cssProp: "height", type: "number", unit: "px" },
+  { key: "padding", label: "内边距", cssProp: "padding", type: "spacing" },
+  { key: "margin", label: "外边距", cssProp: "margin", type: "spacing" },
+]
+
+/**
+ * Isolated light-surface skin used inside arbitrary third-party pages. The
+ * scoped semantic variables prevent host-page CSS variables from changing the
+ * popup while keeping every visual value in this Orbitwork UI-owned source.
+ *
+ * DS 2.0 契约（P6-7 / W4 去痕）：这段 CSS 注进的是**第三方页面**，全局 `--ow-*` token 表
+ * 不在场，所以 `var(--ow-x, y)` 里真正生效的永远是回退值 y —— 这份 `--ow-annotation-*`
+ * 就是 DS token 的镜像，是本文件唯一允许出现字面色值的地方。规则块里一律零裸色：
+ * 新值先在这里立一个 `--ow-annotation-*`（值抄 DS 2.0 浅档终值），再去规则里引。
+ *
+ * 表里每行右侧注释＝它抄的那个 DS 2.0 token 名；终值出自 `src/tokens/base.ts` +
+ * `src/tokens/light.ts`（解析后与 `tokens/ds2-spec.json` 的 light 档逐值一致）。
+ * 改值的顺序永远是「先改 DS token，再回来同步这张表」，两边不许各自漂。
+ *
+ * **单主题（恒浅档）是有意的决定**：浮层落在任意第三方页面上，宿主页的明暗与我们无关，
+ * 我们也拿不到自己的 `[data-theme]`；跟着宿主猜主题只会得到一个半明半暗的壳。所以这张表
+ * 恒取 DS 2.0 **浅档**终值，浮层永远是一块自带 `--ow-popover-bg` 白面 ＋ 1px `--ow-border`
+ * ＋ `--ow-shadow-pop` 的离地卡片（§5 立面：悬浮层永远保留 1px 边框），靠自己的立面立住，
+ * 不靠宿主底色。`.is-preview`（应用内 React 预览）沿用同一张表，两处所见一致。
+ *
+ * 圆角走 `--ow-radius-lg`(12)：浮层是 popover/卡片档（§7 形状表 12＝卡片/popover/toast），
+ * 不是 modal 档；旧写法 `var(--ow-radius-modal, 14px)` 既走错语义档、14 又是形状表外的
+ * 自造值（表内只有 4/6/8/10/12/16/999）。
+ *
+ * 类名 `__ow-popup*` 是与 desktop preload（webviewPreload.ts createPopup）和
+ * BrowserAnnotationPopupView 之间的三方约定，改名要三处同改。
+ */
+export const BROWSER_ANNOTATION_POPUP_STYLES = `
+.__ow-popup{all:initial;box-sizing:border-box;
+/* ── DS 2.0 浅档终值镜像表（左＝本地隔离键，右注释＝所抄的 DS 2.0 token）───────────── */
+--ow-annotation-primary:#0F1B3D;          /* --ow-btn-primary-bg（＝--ow-accent / --ow-navy） */
+--ow-annotation-primary-hover:#202942;    /* --ow-btn-primary-hover */
+--ow-annotation-on-fill:#F7F6F1;          /* --ow-on-fill（＝--ow-btn-primary-fg——实现名，规格侧写的 --ow-btn-primary-text 在 tokens.css 里不存在） */
+--ow-annotation-bg:#FFFFFF;               /* --ow-popover-bg —— 浮层自己的面 */
+--ow-annotation-bg-muted:#F1F0EA;         /* --ow-surface-2（嵌套井/输入底/表头底），浅档与 --ow-hover-pop 同值 */
+--ow-annotation-bg-hover:#ECEBE5;         /* --ow-press-pop —— 比 bg-muted 再深一档（§5 弹层上走 pop 档） */
+--ow-annotation-fg:#333B50;               /* --ow-text */
+--ow-annotation-fg-muted:#646B7A;         /* --ow-text-2 */
+--ow-annotation-fg-subtle:#A2A5A9;        /* --ow-text-3 */
+--ow-annotation-fg-placeholder:#A2A5A9;   /* --ow-placeholder（浅档＝--ow-text-3） */
+--ow-annotation-line:#DCDCD7;             /* --ow-border（＝--ow-input-border）—— 描边与分隔线 rest */
+--ow-annotation-line-strong:#C2C3C1;      /* --ow-border-strong —— 输入 hover 档（§6 三态边框） */
+--ow-annotation-shadow-pop:0 4px 12px rgba(15, 27, 61, 0.10); /* --ow-shadow-pop */
+/* 字体栈也要镜像：注进第三方页时 --ow-font-sans 不在场，回退值必须逐字抄 DS 2.0 的栈
+   （§8 已知坑：emoji 族必须置于栈尾，Linux 数字渲染缺陷，勿调序）。 */
+--ow-annotation-font-sans:'HarmonyOS Sans SC','Noto Sans SC','PingFang SC','Microsoft YaHei',sans-serif,'Apple Color Emoji','Segoe UI Emoji','Noto Color Emoji'; /* --ow-font-sans */
+/* ──────────────────────────────────────────────────────────────────────────────── */
+position:fixed;z-index:2147483647;font-family:var(--ow-annotation-font-sans);font-size:var(--ow-fs-ui, 13px);color:var(--ow-annotation-fg);pointer-events:auto;width:320px;background:var(--ow-annotation-bg);border:var(--ow-border-width-default, 1px) solid var(--ow-annotation-line);border-radius:var(--ow-radius-lg, 12px);box-shadow:var(--ow-annotation-shadow-pop);overflow:hidden;display:flex;flex-direction:column;}
+.__ow-popup.is-preview{position:relative;z-index:1;max-height:100%;}
+.__ow-popup *{box-sizing:border-box;}
+/* 左侧竖条是纯装饰的一条脊，不编码任何状态——按 §4 R2/R1 它没有资格拿提色，走中性描边。 */
+.__ow-popup__collapsed{display:flex;align-items:center;gap:var(--ow-space-15, 6px);padding:10px var(--ow-space-3, 12px);border-left:3px solid var(--ow-annotation-line-strong);border-radius:var(--ow-radius-lg, 12px);}
+.__ow-popup__expanded{display:none;flex-direction:column;overflow:hidden;flex:1;min-height:0;}
+.__ow-popup.is-expanded .__ow-popup__collapsed{display:none;}
+.__ow-popup.is-expanded .__ow-popup__expanded{display:flex;}
+.__ow-popup.is-expanded.is-flipped .__ow-popup__expanded{flex-direction:column-reverse;}
+.__ow-popup.is-expanded.is-flipped{border-radius:var(--ow-radius-lg, 12px);}
+.__ow-popup__top{display:flex;align-items:center;gap:var(--ow-space-2, 8px);padding:10px var(--ow-space-3, 12px);border-left:3px solid var(--ow-annotation-line-strong);border-radius:var(--ow-radius-lg, 12px) var(--ow-radius-lg, 12px) 0 0;flex-shrink:0;}
+/* 工具条按钮走 ghost（DS 2.0 P6-7）：静止透明，hover 才上底，press 再深一档。
+   之前静止就带 bg-muted，等于一直是个实心 chip，跟 §5「贴地不上底」对不上。 */
+.__ow-popup__settings-btn{all:initial;cursor:pointer;font:inherit;width:28px;height:28px;display:inline-flex;align-items:center;justify-content:center;border-radius:var(--ow-radius-sm, 8px);background:transparent;color:var(--ow-annotation-fg-muted);flex-shrink:0;transition:background var(--ow-dur-1, 120ms) var(--ow-ease-beacon, cubic-bezier(0.22, 1, 0.36, 1));font-size:0;}
+.__ow-popup__settings-btn:hover{background:var(--ow-annotation-bg-muted);}
+.__ow-popup__settings-btn:active{background:var(--ow-annotation-bg-hover);}
+.__ow-popup__input{all:initial;flex:1;font:inherit;font-size:var(--ow-fs-ui, 13px);color:var(--ow-annotation-fg);padding:var(--ow-space-05, 2px) 0;border:none;outline:none;background:transparent;min-width:0;}
+.__ow-popup__input::placeholder{color:var(--ow-annotation-fg-placeholder);}
+/* 提交钮与同一行的 settings-btn 同档：28×28（§7 控件高 {28,32,40}，图标钮 ≥28×28）。
+   旧值 30×30 不在档内，且与行内邻居对不齐。 */
+.__ow-popup__submit-btn{all:initial;cursor:pointer;font:inherit;width:28px;height:28px;display:inline-flex;align-items:center;justify-content:center;border-radius:var(--ow-radius-sm, 8px);background:transparent;color:var(--ow-annotation-fg-subtle);flex-shrink:0;transition:background var(--ow-dur-1, 120ms) var(--ow-ease-beacon, cubic-bezier(0.22, 1, 0.36, 1)),color var(--ow-dur-1, 120ms) var(--ow-ease-beacon, cubic-bezier(0.22, 1, 0.36, 1));}
+.__ow-popup__submit-btn:hover{background:var(--ow-annotation-bg-muted);}
+/* 有字才是「能提交了」——实底＋提色，形状不变，颜色是第二编码（R1）。 */
+.__ow-popup__submit-btn.has-text{background:var(--ow-annotation-primary);color:var(--ow-annotation-on-fill);}
+.__ow-popup__submit-btn.has-text:hover{background:var(--ow-annotation-primary-hover);}
+/* §6：焦点环 2px + 2px 留白缝，不靠 all:initial 之后消失的浏览器默认环。
+   环色引 primary：DS 2.0 浅档 --ow-focus-ring 与 --ow-btn-primary-bg 同为 #0F1B3D，
+   不另立键；若上游把两者拆开，这里要跟着补 --ow-annotation-focus-ring。 */
+.__ow-popup__settings-btn:focus-visible,.__ow-popup__submit-btn:focus-visible,.__ow-popup__cancel:focus-visible,.__ow-popup__confirm:focus-visible{outline:var(--ow-focus-ring-w, 2px) solid var(--ow-annotation-primary);outline-offset:var(--ow-focus-ring-offset, 2px);}
+.__ow-popup__tag{display:flex;align-items:center;justify-content:space-between;padding:var(--ow-space-15, 6px) 14px;background:var(--ow-annotation-bg-muted);font-weight:700;font-size:var(--ow-fs-ui, 13px);color:var(--ow-annotation-fg);flex-shrink:0;}
+/* 拖拽握把是字形不是装饰色块，§7「图标色只取 text/text-2/text-3」——原 fg-faint(#C2C3C1)
+   在 DS 2.0 里是 --ow-border-strong，没有对应的文字档，故并入 text-3。 */
+.__ow-popup__tag-drag{color:var(--ow-annotation-fg-subtle);cursor:grab;font-size:var(--ow-fs-body, 14px);letter-spacing:1px;}
+.__ow-popup__props{padding:var(--ow-space-05, 2px) 14px var(--ow-space-1, 4px);overflow-y:auto;flex:1;min-height:0;}
+.__ow-popup__prop{display:flex;align-items:center;padding:var(--ow-space-15, 6px) 0;border-bottom: var(--ow-border-width-default, 1px) solid var(--ow-annotation-line);gap:10px;}
+.__ow-popup__prop:last-child{border-bottom:none;}
+.__ow-popup__prop-label{width:60px;flex-shrink:0;font-size:var(--ow-fs-mark-md, 11px);color:var(--ow-annotation-fg);font-weight:500;}
+.__ow-popup__prop-value{flex:1;display:flex;align-items:center;gap:5px;position:relative;}
+/* 输入类底色走 --ow-surface-2 的镜像（§5「嵌套井＝输入底」），坐在 popover 白面上才读得出井；
+   三态边框 rest(line) → hover(line-strong) → focus(focus-ring，浅档同 primary)，§6。 */
+.__ow-popup__prop-input{all:initial;font:inherit;font-size:var(--ow-fs-mark-md, 11px);color:var(--ow-annotation-fg);box-sizing:border-box;height:28px;padding:0 var(--ow-space-2, 8px);border: var(--ow-border-width-default, 1px) solid var(--ow-annotation-line);border-radius:var(--ow-radius-xs, 6px);width:100%;outline:none;background:var(--ow-annotation-bg-muted);}
+.__ow-popup__prop-input:hover{border-color:var(--ow-annotation-line-strong);}
+.__ow-popup__prop-input:focus{border-color:var(--ow-annotation-primary);}
+.__ow-popup__prop-unit{font-size:var(--ow-fs-mark-sm, 10px);color:var(--ow-annotation-fg-subtle);position:absolute;right:8px;pointer-events:none;}
+.__ow-popup__prop-select{all:initial;font:inherit;font-size:var(--ow-fs-mark-md, 11px);color:var(--ow-annotation-fg);box-sizing:border-box;height:28px;padding:0 var(--ow-space-2, 8px);border: var(--ow-border-width-default, 1px) solid var(--ow-annotation-line);border-radius:var(--ow-radius-xs, 6px);width:100%;outline:none;appearance:auto;cursor:pointer;background:var(--ow-annotation-bg-muted);}
+.__ow-popup__prop-select:hover{border-color:var(--ow-annotation-line-strong);}
+.__ow-popup__prop-select:focus{border-color:var(--ow-annotation-primary);}
+/* §7 形状表：999 只留给带状态点/计数的 chip 与真圆件（头像/状态点）。色板是个取色控件，
+   落按钮档 8px（原 50% 圆点是 V1 色板母题）。 */
+.__ow-popup__color-swatch{width:20px;height:20px;border-radius:var(--ow-radius-sm, 8px);border: var(--ow-border-width-default, 1px) solid var(--ow-annotation-line);flex-shrink:0;cursor:pointer;position:relative;overflow:hidden;}
+.__ow-popup__color-swatch:hover{border-color:var(--ow-annotation-line-strong);}
+.__ow-popup__color-swatch input{position:absolute;inset:-4px;width:28px;height:28px;opacity:0;cursor:pointer;}
+.__ow-popup__spacing{display:flex;gap:3px;flex:1;}
+.__ow-popup__spacing input{all:initial;font:inherit;font-size:var(--ow-fs-mark-sm, 10px);color:var(--ow-annotation-fg);box-sizing:border-box;height:28px;padding:0 3px;border: var(--ow-border-width-default, 1px) solid var(--ow-annotation-line);border-radius:var(--ow-radius-xs, 6px);width:100%;text-align:center;outline:none;background:var(--ow-annotation-bg-muted);}
+.__ow-popup__spacing input:hover{border-color:var(--ow-annotation-line-strong);}
+.__ow-popup__spacing input:focus{border-color:var(--ow-annotation-primary);}
+.__ow-popup__actions{display:flex;align-items:center;justify-content:space-between;padding:var(--ow-space-2, 8px) var(--ow-space-3, 12px);border-top: var(--ow-border-width-default, 1px) solid var(--ow-annotation-line);flex-shrink:0;}
+.__ow-popup__cancel{all:initial;cursor:pointer;font:inherit;font-weight:500;font-size:var(--ow-fs-ui, 13px);color:var(--ow-annotation-fg);box-sizing:border-box;height:32px;padding:0 14px;border:none;border-radius:var(--ow-radius-sm, 8px);background:var(--ow-annotation-bg-muted);transition:background var(--ow-dur-1, 120ms) var(--ow-ease-beacon, cubic-bezier(0.22, 1, 0.36, 1));display:inline-flex;align-items:center;justify-content:center;}
+.__ow-popup__cancel:hover{background:var(--ow-annotation-bg-hover);}
+.__ow-popup__confirm{all:initial;cursor:pointer;font:inherit;font-weight:500;font-size:var(--ow-fs-ui, 13px);box-sizing:border-box;height:32px;padding:0 14px;border:none;border-radius:var(--ow-radius-sm, 8px);background:var(--ow-annotation-primary);color:var(--ow-annotation-on-fill);transition:background var(--ow-dur-1, 120ms) var(--ow-ease-beacon, cubic-bezier(0.22, 1, 0.36, 1));display:inline-flex;align-items:center;justify-content:center;gap:var(--ow-space-1, 4px);}
+.__ow-popup__confirm:hover{background:var(--ow-annotation-primary-hover);}
+`

package/src/lib/focusTrap.ts

@@ -0,0 +1,51 @@
+/**
+ * 模态焦点闭环的共享零件（内部模块，不进 lib/index 公共出口）。
+ *
+ * §6 无障碍：凡声明 role="dialog" aria-modal="true" 的立面都必须三件齐——
+ * ① Tab 焦点圈闭环（焦点不外泄到背后的页面）② 入场取焦 ③ 离场把焦点还给触发元素。
+ * Dialog 基座与 ImagePreview 同为模态，共用同一份选择器与同一套圈闭环实现。
+ */
+export const FOCUSABLE =
+  'a[href],area[href],button:not([disabled]),input:not([disabled]):not([type="hidden"]),select:not([disabled]),textarea:not([disabled]),iframe,[tabindex]:not([tabindex="-1"]),[contenteditable="true"]'
+
+/**
+ * 取出立面内当前可聚焦、且确实可见的节点（隐藏槽位不参与圈闭环）。
+ *
+ * `tabindex="-1"` 的节点一并剔除（R2 核对 T3 发现）：分段器 / RadioCardGroup 这类 roving-tabindex
+ * 组里，非选中项是 `<button tabindex="-1">`——`button:not([disabled])` 会把它们选进来，
+ * 组若恰好是立面里最后一个控件，`last` 就落在一枚浏览器永远不会 Tab 到的按钮上，
+ * 真正的末位控件按 Tab 时 `active !== last`、圈闭环不接手，焦点漏到 body。
+ * 当前已聚焦的节点例外（程序化聚焦的 -1 节点也要能从它接着绕）。
+ */
+export function visibleFocusables(surface: HTMLElement): HTMLElement[] {
+  return [...surface.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(
+    (node) => (node.tabIndex >= 0 && node.offsetParent !== null) || node === document.activeElement,
+  )
+}
+
+/**
+ * 处理一次 Tab：到尾回首、shift+Tab 到首回尾、焦点在立面外时拉回。
+ * 命中并已 preventDefault 时返回 true。
+ */
+export function trapTab(event: KeyboardEvent, surface: HTMLElement): boolean {
+  const focusables = visibleFocusables(surface)
+  if (focusables.length === 0) {
+    event.preventDefault()
+    surface.focus()
+    return true
+  }
+  const first = focusables.at(0)
+  const last = focusables.at(-1)
+  const active = document.activeElement as HTMLElement | null
+  if (!event.shiftKey && (active === last || !surface.contains(active))) {
+    event.preventDefault()
+    first?.focus()
+    return true
+  }
+  if (event.shiftKey && (active === first || !surface.contains(active))) {
+    event.preventDefault()
+    last?.focus()
+    return true
+  }
+  return false
+}

package/src/lib/index.ts

@@ -0,0 +1,5 @@
+export * from "./utils"
+export * from "./appearance"
+export * from "./browser-annotation-popup"
+export * from "./about-window"
+export * from "./shortcut"

package/src/lib/shortcut.test.mjs

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const { formatShortcut, formatShortcutKeys, isMacShortcutPlatform } = await import("./shortcut.ts")
+
+test("R2 · L3-2-8：Mod 在 mac 渲 ⌘、在 windows/linux/web 渲 Ctrl", () => {
+  assert.equal(formatShortcut(["Mod", "T"], "mac"), "⌘T")
+  assert.equal(formatShortcut(["Mod", "T"], "windows"), "Ctrl+T")
+  assert.equal(formatShortcut(["Mod", "T"], "linux"), "Ctrl+T")
+  assert.equal(formatShortcut(["Mod", "T"], "web"), "Ctrl+T")
+})
+
+test("分隔符按平台分档：mac 无缝拼接，其余平台用 +", () => {
+  assert.equal(formatShortcut(["Mod", "Shift", "P"], "mac"), "⌘⇧P")
+  assert.equal(formatShortcut(["Mod", "Shift", "P"], "windows"), "Ctrl+Shift+P")
+})
+
+test("Alt / Ctrl / Meta 各走各的：mac 上 Ctrl 是 ⌃ 不是 ⌘", () => {
+  assert.equal(formatShortcut(["Alt", "Enter"], "mac"), "⌥↩")
+  assert.equal(formatShortcut(["Alt", "Enter"], "windows"), "Alt+Enter")
+  assert.equal(formatShortcut(["Ctrl", "C"], "mac"), "⌃C")
+  assert.equal(formatShortcut(["Meta", "L"], "windows"), "Win+L")
+})
+
+test("词表外的键按字面渲染，两平台一致", () => {
+  assert.equal(formatShortcut(["F5"], "mac"), "F5")
+  assert.equal(formatShortcut(["Mod", "F5"], "windows"), "Ctrl+F5")
+})
+
+test("缺省平台是 mac（＝改造前的现状，不改既有画面）", () => {
+  assert.equal(formatShortcut(["Mod", "T"]), "⌘T")
+  assert.equal(isMacShortcutPlatform("mac"), true)
+  assert.equal(isMacShortcutPlatform("windows"), false)
+})
+
+test("formatShortcutKeys 逐键返回，给 KeycapCombo 那类一键一帽的消费方", () => {
+  assert.deepEqual(formatShortcutKeys(["Mod", "Shift", "P"], "mac"), ["⌘", "⇧", "P"])
+  assert.deepEqual(formatShortcutKeys(["Mod", "Shift", "P"], "windows"), ["Ctrl", "Shift", "P"])
+})
+
+test("空键组不炸", () => {
+  assert.equal(formatShortcut([], "mac"), "")
+  assert.equal(formatShortcut([], "windows"), "")
+})
+
+const stripComments = (text) => text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^[ \t]*\/\/.*$/gm, "")
+
+const shortcutSource = await readFile(new URL("./shortcut.ts", import.meta.url), "utf8")
+
+test("平台受控：库侧不嗅探 userAgent / process.platform", () => {
+  assert.doesNotMatch(stripComments(shortcutSource), /navigator|userAgent|process\.platform/)
+})
+
+test("四平台词表与 TitleBarPlatform 同一份（词表一改这条就红）", () => {
+  assert.match(shortcutSource, /export type ShortcutPlatform = "mac" \| "windows" \| "linux" \| "web"/)
+})
+
+const titleBar = await readFile(new URL("../components/composite/TitleBar/index.tsx", import.meta.url), "utf8")
+test("TitleBarPlatform 词表没变", () => {
+  assert.match(titleBar, /export type TitleBarPlatform = "mac" \| "windows" \| "linux" \| "web"/)
+})
+
+/* ── 库内三处硬编码 ⌘ 已全部改走 formatShortcut ── */
+
+const sidePanelEmpty = await readFile(
+  new URL("../components/domain/desktop/SidePanelEmpty/index.tsx", import.meta.url),
+  "utf8",
+)
+const chatHeader = await readFile(
+  new URL("../components/domain/desktop/DesktopChatHeaderView/index.tsx", import.meta.url),
+  "utf8",
+)
+const webPreviewNav = await readFile(
+  new URL("../components/domain/browser/WebPreviewNav/index.tsx", import.meta.url),
+  "utf8",
+)
+
+test("SIDE_PANEL_EMPTY_ACTIONS 存语义键名，不再存 mac 字形", () => {
+  const code = stripComments(sidePanelEmpty)
+  assert.match(code, /keys: \["Mod", "T"\]/)
+  assert.match(code, /keys: \["Mod", "B"\]/)
+  assert.match(code, /keys: \["Mod", "P"\]/)
+  assert.doesNotMatch(code, /⌘/)
+  assert.match(code, /formatShortcut\(action\.keys, platform\)/)
+  assert.match(code, /platform\?: ShortcutPlatform/)
+  assert.match(code, /platform = "mac"/)
+})
+
+test("DesktopChatHeaderView / WebPreviewNav 的 title 同源取值，不再写死 ⌘T", () => {
+  for (const [name, raw] of [
+    ["DesktopChatHeaderView", chatHeader],
+    ["WebPreviewNav", webPreviewNav],
+  ]) {
+    const code = stripComments(raw)
+    assert.doesNotMatch(code, /⌘/, `${name} 仍有硬编码 ⌘`)
+    assert.match(code, /formatShortcut\(/, `${name} 没接 formatShortcut`)
+    assert.match(code, /platform\?: ShortcutPlatform/, `${name} 没收 platform prop`)
+  }
+})