refactor(toolbar): L1 几何单一真相源，删按钮坐标线性公式

工具栏按钮矩形原本被算三遍且互不引用（渲染 buildToolbarTree / 命中 HitTest /
定位 GetButtonBounds），改任一常量需同步三处。L1 统一为一次 buildToolbarTree+Layout
派生：

- HitTest/GetButtonBounds/GetToolbarSize 删除各自的线性公式，统一查 computeGeometry()
- GetButtonBounds = 按钮 View 的 Rect()（content 矩形）
- HitTest = viewOuterRect（margin 盒，LayoutRow 使其首尾相接、平铺整条满高）
- GetToolbarSize = root 尺寸
- 窗口尺寸魔数 116/30 收口为常量 toolbarBaseWidth/Height（不动 ScaleIntForDPI 缩放源）
- 新增 TestToolbarGeometry_SingleSource 守护命中带/content 矩形/尺寸与旧公式逐像素等价

零视觉/交互变化（真机验证按钮点击/拖动/菜单/tooltip 定位均正常）。设计见
docs/design/theme-toolbar-geometry.md。

Author: huanfeng

docs/design/AGENTS.md

@@ -25,6 +25,7 @@
 | `macos-imkit-plan.md` | **PR-A 实战手册**: macOS IMKit `.app` 工程目录结构 / Swift 类骨架 / Info.plist 模板 / 6 个开发里程碑 / 验证步骤 / 风险清单 |
 | `enum-constraint.md` | 枚举与魔法字符串约束 SSOT (跨模块共享) |
 | `theme-schema-v3.md` | **主题 Schema v3（当前权威设计语义）**：结构归一（删 layout 并入 views / 删 candidate_window 颜色组并入 colors 扁平 token）+ 亮暗统一（`LightDark<T>` 贯穿颜色与图片）+ base 单链继承 + Fill(色·渐变·图)/font 分组；含 v2.6→v3 迁移映射与编辑器原型（`WindInputThemeEditor/src/lib/theme3`）作参考实现 |
+| `theme-toolbar-geometry.md` | 工具栏几何重构：L1 几何单一真相源（HitTest/GetButtonBounds/GetToolbarSize 统一查 Layout 派生的 Rect，删线性公式）+ L2 盒模型化（几何进 schema、measure 生效、补 ResolveToolbarViews）规划 |
 | `theme-v3-freeze-report.md` | **主题 v3 冻结契约（当前权威）**：冻结字段面 + 求值语义快照 + 不兼容旧主题（不合法整体回退 default）+ golden 逐字节验收证据。历史演进/阶段文档（architecture/P2/P4-P8、v26-freeze）已移入 `archive/` |
 | `settings-incremental-save.md` | 设置端全局保存重构：快照 diff + 按 key 最小化提交（`Config.Set`）。根治「全局保存整份覆盖、formData 不含 stats 导致 null 冲掉 track_english」的 bug；独立段（stats/dict）天然隔离 |
 

docs/design/theme-toolbar-geometry.md

@@ -0,0 +1,81 @@
+<!-- Parent: AGENTS.md -->
+<!-- Generated: 2026-06-04 | Updated: 2026-06-04 -->
+
+# 工具栏几何重构（L1 几何单一真相源 + L2 盒模型化）
+
+## 背景
+
+输入法浮动工具栏（`internal/ui` 的 toolbar 系列，仅 Windows）当前几何还停留在
+"线性公式手算按钮坐标 + 几何与鼠标命中各算一套"的状态。候选窗早已迁到盒模型 View
+引擎（`viewbox.go` 的 `Layout`/measure/arrange），工具栏渲染虽也接了 `Layout`/`PaintTree`，
+但用 `FixedW/FixedH` 把 measure 架空，且命中/边界查询仍走独立公式。
+
+本次按颜色已迁 `toolbar_*` token（v3）之后的延续工作，分两步：**L1 几何单一真相源**
+（解耦，零视觉变化）、**L2 盒模型化**（几何进 schema，measure 真正生效）。
+
+## 问题：按钮矩形被算了三遍（+窗口尺寸第四处）
+
+| # | 位置 | 用途 | 形式 |
+|---|------|------|------|
+| 1 | `viewbox_toolbar.go buildToolbarTree` | 渲染布局 | View `FixedW + Margin` 隐式编码 x |
+| 2 | `toolbar_renderer.go HitTest` | 鼠标命中 | 独立线性累加 `gripW + n×buttonW` |
+| 3 | `toolbar_renderer.go GetButtonBounds` | tooltip/菜单定位 | 独立线性累加 + padding |
+| 4 | `toolbar_window.go:219/547` | Win32 窗口尺寸 | `ScaleIntForDPI(116/30)` 字面量 |
+
+改任一常量（如 `buttonWidth`）需同步改 1/2/3 三处——这是耦合。#4 用的是不同缩放源
+（`ScaleIntForDPI` vs 渲染的 `GetDPIScale`），属另一议题，L1 不动缩放基准。
+
+## L1：几何单一真相源（已实现，零视觉变化）
+
+**核心**：一切按钮矩形从同一次 `buildToolbarTree + Layout` 派生，删除 #2/#3 的线性公式。
+
+仿候选窗 `renderTree → RenderResult.Rects → hitRects` 范式，但工具栏只 5 个 View、
+几何与状态无关（mode 文字变化不影响布局，因 `FixedW` 固定），故采用**无状态按需布局**，
+不引入缓存（无缓存失效 / DPI 过期风险）：
+
+```
+computeGeometry() → 用零 state/零色 buildToolbarTree + Layout，提取：
+  - size   = root.Rect().Size()                    （GetToolbarSize）
+  - bounds = 各按钮 View 的 Rect()（content 矩形）  （GetButtonBounds）
+  - hits   = 各按钮 View 的 margin 盒（content 外扩 Margin）（HitTest）
+```
+
+**等价性证明（faithful 关键）**：
+- 旧 `HitTest` 命中语义 = 按 x 分段、忽略 y、按钮间无间隙 = 每个子 View 的 **margin 盒**。
+  `LayoutRow` 使 margin 盒首尾相接 → 平铺整条、满高。逐按钮核对：grip `[0,10)`、
+  mode `[10,36)`、width `[36,62)`、punct `[62,88)`、settings `[88,114)`（scale=1），与旧带界一致。
+- 旧 `GetButtonBounds` = content 矩形 = View `Rect()`（如 settings `Min.X=90`、宽 `buttonW-2pad=22`）。
+- 旧 `GetToolbarSize` = `(116,30)×scale` = root `Rect().Size()`（root `FixedW/FixedH` 即此值）。
+
+`viewOuterRect(v)` = `v.Rect()` 外扩 `v.Margin`（Margin 是 View 自带数据，非重算公式）。
+
+**附带**：`toolbar_window.go` 的窗口尺寸字面量 `116/30` 换成包内常量
+`toolbarBaseWidth/toolbarBaseHeight`（消魔数，不改 `ScaleIntForDPI` 缩放源）。
+
+**不变**：渲染（`Render`）与矢量符号后处理已用 `tt.X.Rect()`，本就单源，无需改。
+
+## L2：盒模型化（规划，L1 绿后再开）
+
+L1 解耦后，几何收口到 `buildToolbarTree`，可安全地让 measure 真正生效、几何进主题 schema：
+
+1. **schema 补几何字段**：`ToolbarViews` 增按钮 padding / gap / grip 宽 / 圆角等；默认值=当前常量（零回归）。
+2. **弃 `FixedW`**：按钮尺寸由内容 measure + padding 决定，root 尺寸由 measure 汇总；`GetToolbarSize` 自然反映。
+3. **补 `ResolveToolbarViews`**：`other_views.go` 当前唯一缺失槽位；走统一 `resolveViewNode`，
+   消费目前被忽略的 `ToolbarButtonNode.Border` 等字段。
+4. 协调 `GetDPIScale` vs `ScaleIntForDPI`，统一窗口尺寸到 `GetToolbarSize`（#4 收口）。
+
+## L3 愿景（远期，不在本次）
+
+按钮内容动态化：每个状态指定开/关对应显示效果（文字 / 符号 / 图片），支持悬停特效。
+当前无视觉 hover（仅记录用于 tooltip）。
+
+## 测试策略
+
+- `TestBuildToolbarTree_Geometry`（既有）：整条 116×30、按钮框高 26、mode 选色、settings `Min.X=90`——L1 后仍逐项绿（几何数值不变）。
+- 新增 `TestToolbarHitTest_SingleSource`：① 各按钮带中心点 `HitTest` 返回对应 kind；② `GetButtonBounds` == `buildToolbarTree+Layout` 的对应 `Rect()`；③ `GetToolbarSize` == root 尺寸；④ 命中带平铺无缝（相邻带界相接）。
+- `TestResolveToolbarViews_BaseAndMode`（既有）：颜色不变。
+
+## 风险与回滚
+
+- L1 行为零变化由等价性证明 + 测试守护；如真机命中异常，回滚仅涉及 `toolbar_renderer.go` 三方法。
+- 缩放源差异（`GetDPIScale`/`ScaleIntForDPI`）刻意留到 L2，避免 L1 夹带 DPI 回归。

wind_input/internal/ui/AGENTS.md

@@ -65,7 +65,7 @@
 | `viewbox_tooltip.go` | **Tooltip View 化（P4-B）**：`buildTooltipTree`（多行 LayoutColumn + `\t` 列对齐 LayoutRow，每列 `FixedW` 取最大宽对齐、缺列补空占位 cell；行数上限 20 / 单列截断 / 多列末列截断逻辑预处理）+ `(*TooltipWindow).resolveTooltipColors`（views.tooltip token > `Palette.Tooltip` > 默认）。`tooltip.go:render` 改走此路径 + `newSharedDrawContext`（取代旧 gg 直绘 + `getTooltipColors`）；`truncateLineToWidth` 形参改 `TextMeasurer` 以可单测 |
 | `toolbar_window.go` | 工具栏 Win32 窗口创建和消息循环 |
 | `toolbar_window_event.go` | 工具栏鼠标事件（拖拽、按钮点击） |
-| `toolbar_renderer.go` | 工具栏渲染：`Render` 走盒模型 View 引擎（见 viewbox_toolbar.go），整条背景/边框/按钮框/mode 文字走 View，grip/全半角/标点/齿轮矢量符号后处理（`paintGrip`/`paintWidthSymbol`/`paintPunctSymbols`/`paintGear`，定位用 View rect）；含 HitTest/GetButtonBounds/RenderTooltip（按钮悬停提示，仍 gg 直绘） |
+| `toolbar_renderer.go` | 工具栏渲染：`Render` 走盒模型 View 引擎（见 viewbox_toolbar.go），整条背景/边框/按钮框/mode 文字走 View，grip/全半角/标点/齿轮矢量符号后处理（`paintGrip`/`paintWidthSymbol`/`paintPunctSymbols`/`paintGear`，定位用 View rect）。**L1 几何单一真相源**：`HitTest`/`GetButtonBounds`/`GetToolbarSize` 不再各算线性公式，统一查 `computeGeometry()`（一次 `buildToolbarTree`+`Layout` 派生）——`GetButtonBounds`=按钮 View 的 `Rect()`(content)，`HitTest`=`viewOuterRect`(margin 盒，平铺整条满高)，`GetToolbarSize`=root 尺寸；设计见 `docs/design/theme-toolbar-geometry.md`。含 `RenderTooltip`（按钮悬停提示，仍 gg 直绘） |
 | `viewbox_toolbar.go` | **工具栏 View 化（P4-C）**：`buildToolbarTree`（整条 LayoutRow：grip 占位 + 4 按钮框，按钮 Stretch 撑高 + margin，mode 是带背景文本叶子，width/punct/settings 是无 Text 框）返回 `toolbarTree`(各按钮 View 引用)；`(*ToolbarRenderer).resolveToolbarViews`（button base 默认 FullWidthOff* + mode 中/英 token 覆盖，映射 `Palette.Toolbar`）。几何 hardcode×scale 与现状逐像素一致 |
 | `toolbar_shellhook.go` | 工具栏 Shell Hook 集成：`RegisterShellHookWindow` + 动态注册 `SHELLHOOK` 消息；拦截 `HSHELL_WINDOWENTERFULLSCREEN=53`/`HSHELL_WINDOWEXITFULLSCREEN=54` 通过 `ToolbarCallback.OnForegroundFullscreenChange` 派发 |
 | `popup_menu.go` | `PopupMenu`：自定义弹出菜单窗口，支持子菜单、勾选状态、主题；`Show`/`Hide`/`Destroy`；键盘导航通过全局低级键盘钩子（`WH_KEYBOARD_LL`）实现；子菜单共享父菜单渲染资源（`newPopupMenuShared`） |

wind_input/internal/ui/toolbar_renderer.go

@@ -164,73 +164,77 @@ func (r *ToolbarRenderer) paintGear(dc *gg.Context, rect image.Rectangle, scale
 	dc.Fill()
 }
 
-// HitTest determines which part of the toolbar was clicked
-func (r *ToolbarRenderer) HitTest(x, y, width, height int) ToolbarHitResult {
-	scale := GetDPIScale()
-
-	// Check grip area
-	gripW := int(gripWidth * scale)
-	if x < gripW {
-		return HitGrip
-	}
-
-	// Check buttons
-	buttonW := int(buttonWidth * scale)
-	buttonX := gripW
+// toolbarHit 是一个按钮的命中带（kind + margin 盒；LayoutRow 使各 margin 盒首尾相接，平铺整条满高）。
+type toolbarHit struct {
+	kind ToolbarHitResult
+	rect image.Rectangle
+}
 
-	// Mode button
-	if x >= buttonX && x < buttonX+buttonW {
-		return HitModeButton
-	}
-	buttonX += buttonW
+// toolbarGeometry 是工具栏几何的单一真相源：一次 buildToolbarTree+Layout 的派生结果。
+type toolbarGeometry struct {
+	size   image.Point                          // 整条尺寸（GetToolbarSize）
+	bounds map[ToolbarHitResult]image.Rectangle // 各按钮 content 矩形（GetButtonBounds）
+	hits   []toolbarHit                         // 各按钮 margin 盒，按 x 顺序（HitTest）
+}
 
-	// Width button
-	if x >= buttonX && x < buttonX+buttonW {
-		return HitWidthButton
-	}
-	buttonX += buttonW
+// viewOuterRect 返回 View 的 margin 盒（content 矩形外扩自身 Margin）。
+func viewOuterRect(v *View) image.Rectangle {
+	r := v.Rect()
+	return image.Rect(
+		r.Min.X-v.Margin.Left, r.Min.Y-v.Margin.Top,
+		r.Max.X+v.Margin.Right, r.Max.Y+v.Margin.Bottom,
+	)
+}
 
-	// Punctuation button
-	if x >= buttonX && x < buttonX+buttonW {
-		return HitPunctButton
+// computeGeometry 用零 state/零色构建工具栏 View 树并 Layout，派生几何——命中/边界/尺寸的唯一来源。
+// 几何与 state/颜色无关（按钮 FixedW 固定、mode 文字不影响布局），故按需计算、无需缓存。
+func (r *ToolbarRenderer) computeGeometry() toolbarGeometry {
+	scale := GetDPIScale()
+	tt := buildToolbarTree(ToolbarState{}, theme.ResolvedToolbarViews{}, scale)
+	Layout(tt.root, 0, 0, r.TextDrawer())
+	return toolbarGeometry{
+		size: tt.root.Rect().Size(),
+		bounds: map[ToolbarHitResult]image.Rectangle{
+			HitGrip:           tt.grip.Rect(),
+			HitModeButton:     tt.mode.Rect(),
+			HitWidthButton:    tt.width.Rect(),
+			HitPunctButton:    tt.punct.Rect(),
+			HitSettingsButton: tt.settings.Rect(),
+		},
+		hits: []toolbarHit{
+			{HitGrip, viewOuterRect(tt.grip)},
+			{HitModeButton, viewOuterRect(tt.mode)},
+			{HitWidthButton, viewOuterRect(tt.width)},
+			{HitPunctButton, viewOuterRect(tt.punct)},
+			{HitSettingsButton, viewOuterRect(tt.settings)},
+		},
 	}
-	buttonX += buttonW
+}
 
-	// Settings button
-	if x >= buttonX && x < buttonX+buttonW {
-		return HitSettingsButton
+// HitTest determines which part of the toolbar was clicked（查 Layout 派生的命中带，无独立公式）。
+func (r *ToolbarRenderer) HitTest(x, y, width, height int) ToolbarHitResult {
+	pt := image.Pt(x, y)
+	for _, h := range r.computeGeometry().hits {
+		if pt.In(h.rect) {
+			return h.kind
+		}
 	}
-
 	return HitNone
 }
 
-// GetButtonBounds returns the bounds of a specific button
+// GetButtonBounds returns the bounds of a specific button（查 Layout 派生的 content 矩形）。
 func (r *ToolbarRenderer) GetButtonBounds(button ToolbarHitResult) (x, y, w, h int) {
-	scale := GetDPIScale()
-	height := int(toolbarBaseHeight * scale)
-	gripW := int(gripWidth * scale)
-	buttonW := int(buttonWidth * scale)
-	padding := int(buttonPadding * scale)
-
-	switch button {
-	case HitGrip:
-		return 0, 0, gripW, height
-	case HitModeButton:
-		return gripW + padding, padding, buttonW - padding*2, height - padding*2
-	case HitWidthButton:
-		return gripW + buttonW + padding, padding, buttonW - padding*2, height - padding*2
-	case HitPunctButton:
-		return gripW + buttonW*2 + padding, padding, buttonW - padding*2, height - padding*2
-	case HitSettingsButton:
-		return gripW + buttonW*3 + padding, padding, buttonW - padding*2, height - padding*2
+	rect, ok := r.computeGeometry().bounds[button]
+	if !ok {
+		return 0, 0, 0, 0
 	}
-	return 0, 0, 0, 0
+	return rect.Min.X, rect.Min.Y, rect.Dx(), rect.Dy()
 }
 
-// GetToolbarSize returns the toolbar size
+// GetToolbarSize returns the toolbar size（Layout 后 root 尺寸）。
 func (r *ToolbarRenderer) GetToolbarSize() (width, height int) {
-	scale := GetDPIScale()
-	return int(toolbarBaseWidth * scale), int(toolbarBaseHeight * scale)
+	sz := r.computeGeometry().size
+	return sz.X, sz.Y
 }
 
 // CreateModeIndicatorColor returns the color for mode indicator

wind_input/internal/ui/toolbar_window.go

@@ -216,8 +216,8 @@ func (w *ToolbarWindow) Create() error {
 	style := uint32(WS_POPUP)
 
 	// Initial size - match toolbarBaseWidth/Height in toolbar_renderer.go
-	w.width = ScaleIntForDPI(116)
-	w.height = ScaleIntForDPI(30)
+	w.width = ScaleIntForDPI(toolbarBaseWidth)
+	w.height = ScaleIntForDPI(toolbarBaseHeight)
 
 	hwnd, _, err := procCreateWindowExW.Call(
 		uintptr(exStyle),
@@ -544,8 +544,8 @@ func (w *ToolbarWindow) Destroy() {
 func (w *ToolbarWindow) handleDPIChanged() {
 	// Recalculate toolbar size with new DPI
 	w.mu.Lock()
-	w.width = ScaleIntForDPI(116)
-	w.height = ScaleIntForDPI(30)
+	w.width = ScaleIntForDPI(toolbarBaseWidth)
+	w.height = ScaleIntForDPI(toolbarBaseHeight)
 	w.mu.Unlock()
 
 	// Re-render with the new DPI scale

wind_input/internal/ui/viewbox_toolbar_test.go

@@ -75,3 +75,63 @@ func TestBuildToolbarTree_Geometry(t *testing.T) {
 		t.Errorf("settings 框左缘应 90, got %d", tt2.settings.Rect().Min.X)
 	}
 }
+
+// TestToolbarGeometry_SingleSource 守护 L1：命中/边界/尺寸均从一次 buildToolbarTree+Layout 派生，
+// 且与旧线性公式逐项等价（scale=1：grip=10, button=26, pad=2, H=30）。
+func TestToolbarGeometry_SingleSource(t *testing.T) {
+	m := fixedMeasurer{charW: 10}
+	tt := buildToolbarTree(ToolbarState{ChineseMode: true}, theme.ResolvedToolbarViews{}, 1.0)
+	Layout(tt.root, 0, 0, m)
+
+	// content 矩形（GetButtonBounds 语义）= 旧 GetButtonBounds 公式
+	type rectWant struct {
+		name             string
+		v                *View
+		minX, minY, w, h int
+	}
+	for _, c := range []rectWant{
+		{"grip", tt.grip, 0, 0, 10, 30},
+		{"mode", tt.mode, 12, 2, 22, 26},
+		{"width", tt.width, 38, 2, 22, 26},
+		{"punct", tt.punct, 64, 2, 22, 26},
+		{"settings", tt.settings, 90, 2, 22, 26},
+	} {
+		r := c.v.Rect()
+		if r.Min.X != c.minX || r.Min.Y != c.minY || r.Dx() != c.w || r.Dy() != c.h {
+			t.Errorf("%s content=(%d,%d,%d,%d), 期望(%d,%d,%d,%d)",
+				c.name, r.Min.X, r.Min.Y, r.Dx(), r.Dy(), c.minX, c.minY, c.w, c.h)
+		}
+	}
+
+	// 命中带（HitTest 语义）= margin 盒：与旧 x-分段一致、满高 [0,30)、首尾相接平铺
+	type bandWant struct {
+		name       string
+		v          *View
+		minX, maxX int
+	}
+	prevMax := 0
+	for _, b := range []bandWant{
+		{"grip", tt.grip, 0, 10},
+		{"mode", tt.mode, 10, 36},
+		{"width", tt.width, 36, 62},
+		{"punct", tt.punct, 62, 88},
+		{"settings", tt.settings, 88, 114},
+	} {
+		hb := viewOuterRect(b.v)
+		if hb.Min.X != b.minX || hb.Max.X != b.maxX {
+			t.Errorf("%s 命中带 x=[%d,%d), 期望[%d,%d)", b.name, hb.Min.X, hb.Max.X, b.minX, b.maxX)
+		}
+		if hb.Min.Y != 0 || hb.Max.Y != 30 {
+			t.Errorf("%s 命中带应满高[0,30), got[%d,%d)", b.name, hb.Min.Y, hb.Max.Y)
+		}
+		if hb.Min.X != prevMax {
+			t.Errorf("%s 命中带应与前带相接：期望 Min.X=%d, got %d", b.name, prevMax, hb.Min.X)
+		}
+		prevMax = hb.Max.X
+	}
+
+	// 整条尺寸（GetToolbarSize 语义）
+	if sz := tt.root.Rect().Size(); sz.X != 116 || sz.Y != 30 {
+		t.Errorf("整条尺寸应 116x30, got %dx%d", sz.X, sz.Y)
+	}
+}