[windows] Capsule 变形、失真与尺寸错位

[Cooper-X-Oak]

治理归属

• 族群：B 族群 / 窗口几何契约
• canonical PR：fix(windows): 收口 Capsule 几何契约 #146
• 主修范围：capsule host bounds、visual pill metrics、badge offset、clipping、distortion、DPI 几何对齐
• 不默认并入：helper-window 生命周期、startup visible/ready ownership、QA helper-window 语义
• 参考：
  • docs/windows-window-governance-board.zh-CN.md
  • docs/2026-05-02-window-capability-family-audit.md
  • docs/github-tracking/windows-window-family-canonical-map.md

现象

• 触发条件：Windows 下展示 Capsule，尤其是录音态、翻译徽章显示态、状态切换态，以及不同 DPI 下的透明窗口呈现。
• 当前表现：Capsule 会出现尺寸/视觉异常，包括 pill 被裁切、模糊边缘被吃掉、翻译徽章与 pill 相对位置不稳，整体像被拉伸或压扁。
• 代码证据：
  • openless-all/app/src-tauri/src/lib.rs 原先将 Windows capsule 窗口几何收缩到与前端 pill 几乎同尺寸，例如 196x52。
  • openless-all/app/src/components/Capsule.tsx 中翻译徽章定位曾写死按 21px 半高计算，等价于沿用 macOS 42px pill 的几何假设。
  • openless-all/app/src/lib/capsuleLayout.ts 定义了 Windows pill metrics，但 native transparent window 还要承载 shadow、blur fringe 与 badge 空间，这两层几何没有分开。
• 与 macOS 原始设计意图的偏差：
  • macOS 的原始设计更接近“浮窗视觉层自然悬浮，窗口承载边界不裁切掉玻璃感和徽章状态”。
  • Windows 当前却直接把 visual pill 尺寸拿去当 native bounds，偏离了“承载层”和“视觉层”应分离的设计意图。
• 平台范围判断：
  • 直接症状是 Windows-first，因为透明窗口裁切、DPI、阴影与 badge 空间在 Windows 上更容易显性暴露。
  • 根因模式有 cross-platform risk，因为只要继续混用 native bounds 和 visual metrics，其他平台未来的新状态或新动画也可能复发。
• 生命周期差异：
  • 不同系统下 transparent window 的实际裁切边界、shadow ownership、DPI rounding、first show timing 都不一样。
  • macOS compositor 对额外视觉空间可能更宽容；Windows 上如果 bounds 太紧，会在 show 时立即转化为可见裁切。
• 5 Whys / 根因分析：
  • Why 1：为什么 Capsule 会变形或被裁切？因为 native transparent window bounds 太紧，几乎贴着 visual pill。
  • Why 2：为什么 bounds 会太紧？因为后端把窗口承载空间当成了前端视觉尺寸，没有留 shadow / blur / badge 安全边距。
  • Why 3：为什么会把两层几何混用？因为 lib.rs 的 native bounds 逻辑与 capsuleLayout.ts 的 visual metrics 没有明确 contract。
  • Why 4：为什么这会偏离 macOS 设计意图？因为原始意图是“视觉层自然悬浮”，而不是让承载层裁切视觉层。
  • Why 5：为什么问题在 Windows 更显性？因为 Windows 的 transparent window / compositor lifecycle 对紧 bounds 更敏感，show 时就会把裁切暴露出来。
• 当前认领：暂以 draft PR fix(windows): 收口 Capsule 几何契约 #146 占位承接；上游仓库暂不可直接把 Cooper-X-Oak 设为 assignee。

影响

• 用户影响：直接影响 Windows 录音态的可读性和质感，用户会把它理解为“浮窗不稳定”。
• 工程影响：增加后续 QA panel 与 capsule 相对定位的误差，因为 QA 锚点依赖 capsule 高度来源。
• 验证影响：让 DPI、阴影、翻译状态切换的所有视觉问题更难定位，因为当前缺陷发生在 native bounds 层。
• 平台影响：当前显性在 Windows，但几何语义混用属于跨平台治理风险。

建议接受标准

• Windows capsule 的 native window bounds 与 visual pill metrics 明确分层，不再共用一套数值语义。
• 常规 pill、翻译徽章、阴影/模糊边缘在 Windows 下不被裁切。
• QA 锚点使用的 capsule 高度来源与前端可视 pill 一致，不受额外安全边距污染。
• 验证至少覆盖 npm run build 和一次 Windows capsule show/hide smoke。
• issue 生命周期由 draft PR fix(windows): 收口 Capsule 几何契约 #146 承接；仅当 PR 从 draft 转 ready 并最终 merge，才视为该 issue 完成。

TODO / 不确定项

• TODO：需要在 100% / 125% / 150% DPI 下各看一次视觉完整性，确认没有新的缩放回归。
• TODO：如果后续增加更多 capsule 子状态，需要约束新状态使用 visual metrics，而不是直接复用 native bounds。

[Cooper-X-Oak]

Checked against #139: keeping this issue open because it is not a duplicate.\n\n- #139 tracks helper-window lifecycle / dead zone / screenshot selectable / lingering transparent overlay\n- #142 tracks geometry / clipping / distortion / bounds-vs-visual-metrics mismatch\n\nThey are adjacent but not the same problem layer.

[Cooper-X-Oak]

去重说明 / Dedup note：本 issue 与 #139 相关但不重复。#142 关注 capsule geometry / bounds / visual distortion；#139 关注 helper-window lifecycle semantics 与 lingering transparent overlay。后续修复可并行，但不应合并成同一条 issue。

[Cooper-X-Oak]

设计治理关联 / Governance link: #158。该票属于跨平台 helper-window / native-window contract 族群案例之一，后续可在 #158 下统一沉淀设计经验与平台边界。

[Cooper-X-Oak]

Family mapping note:

This issue is now treated as the canonical anchor for Family B: Window Geometry & Visual Bounds.

Owned scope:

• capsule host bounds vs visual pill metrics
• clipping / distortion / badge offset
• DPI-sensitive geometry mismatch
• geometry-driven ending-stage visual jump

Do not merge into this issue by default:

• lingering transparent overlay / non-participating hidden-state problems
• QA helper-window semantics
• startup visible/ready ownership

Reference docs:

• docs/2026-05-02-window-capability-family-audit.md
• docs/github-tracking/windows-window-family-canonical-map.md