[tauri] 跨平台UI缺陷频发，windows需分层治理做原生实现

[Cooper-X-Oak]

现象

仓库里现在已经出现多张彼此不重复、但共享同一类跨平台设计缺口的 issue：

• [windows] QA 浮窗生命周期语义未与 macOS 对齐，存在 linger / focus / screenshot 风险 #153 QA helper-window 生命周期 / 可拖动语义
• [windows] OS hook 与主窗口前台热键双事件源并存，听写生命周期存在失配风险 #154 Windows 双热键事件源生命周期风险
• [windows] Capsule 生命周期未对齐 macOS，导致死区 / 截图可选中 / 拖拽卡顿 #139 Capsule helper-window 生命周期
• [Windows][P1] 主窗口四周圆角与自绘外框贴合不完整 #127 / [windows] Capsule 变形、失真与尺寸错位 #142 主窗口与 Capsule 的圆角 / 外框 / 边缘不贴合问题

这些问题表面上落在：

• hotkey
• helper-window
• 拖动
• 圆角
• 截图
• focus
• topmost
• dead zone

但根上都指向同一个治理缺口：

我们缺少一份跨平台 helper-window / native-window contract，
导致 macOS 上自然成立的实现方式，被直接平移到 Windows / Linux 后只兼容了一部分语义。

这次 QA 这条线已经把这个问题暴露得很典型了：

• macOS 的原始产品目标其实没错
• 错的是把 macOS 当前这版实现方式直接当成跨平台模板
• 一旦先做分层，问题会收得很快
• 一旦不分层，就会在单个 bug 票里反向推设计，越修越累

影响

如果不把这类问题提升到设计治理层，后续会持续发生：

• 先在 Windows 暴露半兼容症状
• 再在单点修复里一边猜平台差异、一边补 workaround
• 最后 feature family 的产品语义和平台实现边界都越来越模糊

对当前仓库的直接影响包括：

• helper-window 的 show / dismiss / hidden / non-participating 契约不一致
• 可拖动语义无法跨平台稳定承载
• 窗口外观问题和交互问题容易被混在一起
• 测试和回归也不容易知道自己在验证“产品目标”还是“某个平台的小补丁”

从工程经验角度看，这已经不是“顺手记个心得”的程度了，而是值得单独沉淀的一条治理规则。

建议接受标准

• 产出一份平台无关的 helper-window / native-window contract，明确哪些产品目标必须跨平台一致
• 对 contract 做平台分层：macOS 如何承载、Windows 如何承载、Linux 是否 best-effort
• 把 [windows] QA 浮窗生命周期语义未与 macOS 对齐，存在 linger / focus / screenshot 风险 #153 作为经典案例写进治理说明：说明为什么 non-activating but draggable 不能继续直接复用 macOS 当前实现方式
• 把现有相关 issue 作为首批案例挂进来，至少包括 [windows] QA 浮窗生命周期语义未与 macOS 对齐，存在 linger / focus / screenshot 风险 #153 / [windows] OS hook 与主窗口前台热键双事件源并存，听写生命周期存在失配风险 #154 / [windows] Capsule 生命周期未对齐 macOS，导致死区 / 截图可选中 / 拖拽卡顿 #139 / [Windows][P1] 主窗口四周圆角与自绘外框贴合不完整 #127 / [windows] Capsule 变形、失真与尺寸错位 #142
• 明确哪些问题属于 helper-window / 生命周期族群，哪些属于 Windows UI 外观族群，避免后续误混
• 后续新增类似窗口能力时，先对照治理 contract 再选平台实现，而不是等 Windows 症状暴露后再反推设计

TODO / 不确定项

• 这份治理说明后续是否要正式落进 docs/ 作为长期设计约束
• Linux 是否应正式定义为 best-effort，还是也要求达到同等产品目标
• 后续可以继续把更多现存 issue 挂到这张治理 issue 下，作为同族群案例库

[Cooper-X-Oak]

首批关联案例 / First batch related cases

• [windows] QA 浮窗生命周期语义未与 macOS 对齐，存在 linger / focus / screenshot 风险 #153: QA helper-window lifecycle / draggable semantics
• [windows] OS hook 与主窗口前台热键双事件源并存，听写生命周期存在失配风险 #154: Windows 双热键事件源生命周期风险
• [windows] Capsule 生命周期未对齐 macOS，导致死区 / 截图可选中 / 拖拽卡顿 #139: Capsule helper-window lifecycle 作为同类先例
• [Windows][P1] 主窗口四周圆角与自绘外框贴合不完整 #127: 主窗口圆角 / 外框贴合问题（Windows UI 外观 family）
• [windows] Capsule 变形、失真与尺寸错位 #142: Capsule 变形 / 失真 / 尺寸错位（Windows UI 外观 family）

说明：这些 issue 并不重复，但都暴露了“跨平台窗口 contract 未先定义清楚，就直接把 macOS 当前实现方式平移”的治理缺口。后续可继续把同族群案例挂到本 issue 下。

[Cooper-X-Oak]

补一条从 macOS design intent 反推 Windows 语义漂移的论据，供后续集中治理参考。

观察结论 / Thesis

当前这批 Windows UI 异常，不宜继续按“看见一个问题修一个问题”的方式推进。更合理的判断是：

很多窗口能力最初是按 macOS 的“创建即设计态 / 原生语义天然成立”来落地的；
到了 Windows 上，这些语义并不会自动成立，结果就是 UI/interaction contract 在 host-window 层发生漂移，
最终表现成一组表面上分散、但根上同类的问题。

这意味着：在修复之前，应该先扩大检查范围，系统性盘点“哪些语义在 macOS 上默认成立、但在 Windows 上并不成立”，再按问题层面分类治理。

macOS 原始设计假设 / Original macOS assumptions

从现有实现和现象回看，仓库里至少存在这些隐含的 macOS-first 假设：

• 窗口在 first paint 时就接近最终 design-state
• native titlebar / panel / vibrancy / non-activating window 行为足够稳定，可以直接承接产品语义
• visual bounds 和 host-window bounds 即使不显式区分，也不容易马上暴露问题
• “视觉上已经隐藏”通常接近“系统层面也不再参与”
• draggable / focus / topmost / screenshot participation 等语义可以较自然地依附在原生窗口模型上

这些假设在 macOS 上经常“看起来没问题”，所以设计和实现会自然地往前走；但 Windows 并不会自动兑现这些假设。

到 Windows 之后的语义变化 / Semantic drift on Windows

Windows 下更像是：

• 每个窗口都要显式面对 DWM corner / shadow / Mica / frameless / hit-test / activation / topmost / compositor lifecycle
• host-window bounds、visual bounds、first visible frame、final interactive state 往往不是同一个时点，也不是同一个层次
• “视觉隐藏”不等于“停止系统参与”；“透明”也不等于“不会被命中 / 不会被截图 / 不会参与合成”

因此，同一套从 macOS 平移过来的实现，在 Windows 上就会出现语义漂移：

• 设计以为在表达一个产品 contract
• 运行时实际上只兑现了一部分 native-window contract
• 剩余未兑现的部分就以 UI 异常、交互异常、visual mismatch 的形式暴露出来

这轮预防性检查里已经看到的同类症状 / Preventive signals already found

1. Main window appearance family

• #127 主窗口圆角 / 外框 / titlebar 贴合问题，本质不是单个 borderRadius 值不对，而是：
  • first visible frame
  • native frame / DWM corner
  • custom chrome shell
  • inner console radius
    没有被定义成同一个 contract
• 这类问题在 macOS 上更容易被系统窗口模型“帮忙补齐”；在 Windows 上则必须显式建模

2. Multi-window visual-host mismatch family

• 这不是主窗口独有现象。
• qa、capsule 这类窗口同样采用 transparent、decorations:false、自绘 shell 或 helper-window 语义。
• 说明“圆角 / 外框 / 视觉边界贴合”是 multi-window family，不应只按单窗 patch 来理解。

3. Capsule geometry / distortion family

• #142 看起来像尺寸或视觉问题，但更准确的根因是：
  • native host bounds
  • visual pill metrics
  • translation badge geometry
  • Windows bottom inset / shadow allowance
    没有被当成一份 shared contract
• 在 macOS 上，类似几何混用未必立刻显性暴露；到了 Windows，上述几层一旦不同步，就会表现成 clipping / distortion / “看起来变形”。

4. Capsule ending-stage deformation signal

• 预防性检查里还有一个值得单独记下来的信号：
  • Capsule 在 active states 之外会很快退出可见态
  • 但 Windows 下 host bounds、translation badge、visual pill、hide timing 并不天然是一个平滑收束过程
• 这会让“结束对话 / 结束胶囊时的变形感”更像一种 contract 缺口，而不是单纯 CSS 问题
• 换句话说：
  • 这不是“多调两个像素就完了”
  • 而是要确认 exit-stage geometry semantics 到底应该是什么

5. Helper-window participation family

• #139、#153 之类问题已经说明：
  • 在 macOS 上“non-activating but draggable / visually gone”这些语义可以比较自然地成立
  • 在 Windows 上如果不显式约束 host-window participation，就会冒出 dead zone / screenshot selectable / linger / focus drift 一类问题
• 这进一步说明：
  • Windows 异常不只是 bug 多
  • 而是原始 design intent 缺少跨平台 native-window contract

为什么现在不适合继续 patch-by-patch / Why not patch-by-patch now

如果继续按单点修补推进：

• 今天修主窗口圆角
• 明天修 Capsule distortion
• 后天修 QA linger

那我们其实是在持续用 symptom fixes 反推设计，而不是先把 native-window / helper-window contract 说清楚。

风险是：

• 问题会被错误归类
• 各支线会把 appearance、geometry、lifecycle、interaction 混修
• regression review 时不知道自己在验证产品语义，还是某个平台 workaround
• 同一类设计缺口会在新窗口能力上反复出现

建议的下一步 / Suggested next step

建议把当前工作流改成：

1. 扩大检查范围

• 不只看 main
• 也把 capsule、qa，以及所有 transparent + frameless + helper-window-like 的窗口都纳入同一轮审计

2. 先按问题层面分类

• appearance family
  • round corner / outer frame / shadow / shell fit / first visible design-state
• geometry family
  • host bounds vs visual bounds / clipping / badge offset / DPI
• lifecycle family
  • visible vs ready / show-hide semantics / non-participating hidden state
• interaction family
  • draggable semantics / resize hit-test / activation / focus / screenshot participation

3. 再做集中治理

• 先定义 contract
• 再决定哪些 issue 属于同一 repair track
• 最后才进入实现修复，而不是继续看到一个症状就单点 patch

对 #158 的价值 / Why this supports #158

这条论据支持 #158 的核心判断：

我们需要的不是再多几个 Windows workaround，
而是一份从产品语义出发、对不同 OS 的 native-window / helper-window 差异显式建模的 contract。

否则，Windows 只会不断充当“把 macOS 隐含假设打成显性 bug 的平台”。

[Cooper-X-Oak]

Expanded audit 已整理成文档：

• docs/2026-05-02-window-capability-family-audit.md

这份文档做了三件事：

1. 从 macOS-first assumptions 与 Windows semantic drift 出发，解释为什么当前不是单点 bug 堆积，而是 contract 分层缺口
2. 对窗口能力做 family 分类：
   • Appearance Contract
   • Geometry Contract
   • Lifecycle Contract
   • Interaction Contract
3. 给出 repair track 边界和顺序建议：
   • Windows UI adaptation 线：#127 / #125、#142 / #146
   • helper-window / lifecycle 线：#98 / #145、#139 / #140、#153 / #156、#154 / #155

结论是：

后续不应继续按 symptom patch-by-patch 推进，
而应先把 issue 绑定到 primary family，再在 family-specific canonical issue/PR 里实现。

[Cooper-X-Oak]

认领这条 issue，当前由我推进。
Current status: issue convergence complete, follow-up repair scheduling in progress.
PR status: no dedicated PR yet; this issue is currently tracked at the problem-map / scope-convergence level.