Expose layout API and refresh regression docs

开发记录/功能变更/Feature-20260415-0008-KEY5-第二阶段专项回归场景增强.md

@@ -0,0 +1,78 @@
+# 功能变更 ID: Feature-20260415-0008
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260415-0008
+- 标题: KEY5 第二阶段专项回归场景增强
+- 状态：已完成
+- 类型：修改
+- 级别：L2 中等
+- 模块: 测试用例 / 回归场景
+- 版本 / 分支: 当前工作区
+- 环境: Windows + EasyX
+- 负责人: Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - 旧版 `KEY5` 已能覆盖第一阶段布局主线，但场景层次不够集中，说明文字偏长，部分区域排版紧。
+  - 第二阶段引入了内容驱动、overlay 补画、容器职责边界等新验证点，旧 `KEY5` 覆盖不完整。
+- 目标:
+  - 把 `KEY5` 重构成第二阶段专项回归入口。
+  - 增加三层 `Canvas` 嵌套、通用 overlay、跨容器 hover 清理、`Label` 内容驱动规则验证。
+- 不做什么：[可选]
+  - 不追求视觉美化。
+  - 不把测试用例变成完整 demo 页。
+
+## 变更内容
+
+- 变更摘要:
+  - 重构 `KEY5` 的区域布局与说明文案。
+  - 引入三层嵌套 `Canvas` 场景。
+  - 增加 `Window / Canvas / TabControl / Table` 四类关键回归点。
+- 新增项：[可选]
+  - 三层 `Canvas` 嵌套与多层锚点链回归。
+  - `Label` 文本变化 / 样式变化按钮。
+  - 跨容器相邻按钮 hover/tooltip 回归点。
+  - 顶层浮层覆盖 `Table` 的 overlay 回归点。
+- 修改项：[可选]
+  - 缩短说明 `Label` 文案，减少普通排版重叠。
+  - 重新组织分区顺序，提升单区可读性。
+- 删除 / 废弃项：[可选]
+  - 删除过长、重复的说明文案。
+- 受影响的文件 / 类 / 函数:
+  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp)
+- 对外 API / 属性变化：[可选]
+  - 无
+
+## 行为对照
+
+- 变更前:
+  - `KEY5` 主要覆盖第一阶段布局规则，层次和交互链回归点相对分散。
+  - 说明文字较长，部分区域排版偏挤。
+- 变更后:
+  - `KEY5` 成为第二阶段主回归入口。
+  - 三层嵌套、overlay、跨容器 hover、`Label` 内容驱动、`Table` 分页与页码都能直接观察。
+- 兼容性说明：兼容
+- 迁移说明：[可选]
+  - 仍然通过 `#define KEY 5` 进入，无额外迁移。
+
+## 验证与落地
+
+- 验证方式:
+  - 编译 `z-testDome.cpp /DKEY=5`
+  - 手动观察窗口 resize、hover、tooltip、overlay、分页和 `Label` 变化
+- 验证结果:
+  - 编译级验证通过
+  - GUI 手动验证待本机执行
+- 关联 BUG / Fix：[可选]
+  - `BUG-20260415-0005`
+  - `Fix-BUG-20260415-0005`
+- Commit: 未提交（当前工作区）
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
+  - `Label` 样式变化验证明确依赖 `setDirty(true)` 使用约定。

开发记录/功能变更/Feature-20260416-0009-KEY2-使用新布局API重构与联动刷新.md

@@ -0,0 +1,87 @@
+# 功能变更 ID: Feature-20260416-0009
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260416-0009
+- 标题: KEY2 使用新布局 API 重构与联动刷新
+- 状态：开发中
+- 类型：修改
+- 级别：L2 中等
+- 模块: 测试用例 / Layout API 迁移样例
+- 版本 / 分支: 当前工作区
+- 环境: Windows + EasyX
+- 负责人: Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - `KEY2` 原有布局主要依赖旧 `setAnchor(...)` 语义，无法清晰表达“固定尺寸 + 比例位移”。
+  - 32 位位号标签与位按钮分别按各自尺寸参与比例位移，窗口拉伸后会发生错位。
+  - 位按钮点击后，下面的十六进制、十进制与二进制显示区刷新链散落在多个回调中，维护成本高且容易漏更新。
+- 目标:
+  - 把 `KEY2` 改成新布局 API 的首个完整迁移样例。
+  - 修复位标签与位按钮 resize 后错位问题。
+  - 让位按钮、位操作按钮、配置区按钮共用一条统一的显示刷新链。
+- 不做什么：[可选]
+  - 不重构 `KEY1 / KEY5`
+  - 不引入 `KEY2` 以外的新功能
+
+## 变更内容
+
+- 变更摘要:
+  - 重构 `KEY2` 位选择区为“每一位一个小 Canvas 单元”。
+  - 使用新布局 API 重排 `KEY2` 的选择区、功能区、数值显示区、二进制显示区与配置区。
+  - 抽出统一的 bit 快照、应用、显示刷新链，收口位按钮与功能按钮的联动。
+- 新增项：[可选]
+  - `KEY2` 内部的布局辅助策略函数
+  - `snapshotBits / applyBits / refreshDisplaysWithBits` 这类统一刷新路径
+- 修改项：[可选]
+  - 32 位位标签与位按钮的组织方式
+  - 顶层区域的拉伸策略
+  - 一键置 0 / 一键置 1 / 左移 / 右移 / 位取反 / signed toggle 的显示刷新方式
+- 删除 / 废弃项：[可选]
+  - 废弃旧的“位标签和位按钮分别做比例位移”的选择区组织方式
+  - 废弃散在多个回调中的局部显示刷新
+- 受影响的文件 / 类 / 函数:
+  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp)
+- 对外 API / 属性变化：[可选]
+  - 无框架级 API 变化，属于测试用例迁移
+
+## 行为对照
+
+- 变更前:
+  - 32 位位标签与位按钮在窗口拉伸后会发生错位。
+  - 位按钮点击后，显示区更新链不统一，后续维护难度高。
+  - `KEY2` 的多个区域仍依赖旧锚点表达，窗口拉伸时不够稳定。
+- 变更后:
+  - 每一位作为独立单元整体位移，位标签与位按钮不再分离漂移。
+  - 位按钮、一键置 0/1、位取反、左移、右移、signed toggle 均通过统一刷新链更新显示区。
+  - 顶层五个区域在窗口拉伸后继续铺满可用空间，内部小控件保持固定尺寸。
+- 兼容性说明：兼容
+- 迁移说明：[可选]
+  - 这是新布局 API 的示例迁移，不影响其它 `KEY` 入口。
+
+## 验证与落地
+
+- 验证方式:
+  - 编译 `z-testDome.cpp /DKEY=2`
+  - 编译 `z-testDome.cpp /DKEY=5`
+  - 手动验证 `KEY2`：
+    - 窗口横向拉伸
+    - 位按钮点击
+    - 位取反 / 左移 / 右移
+    - 一键置 0 / 一键置 1
+    - 有符号 / 无符号切换
+- 验证结果:
+  - 编译级验证通过。
+  - GUI 手动验证待本机继续确认。
+- 关联 BUG / Fix：[可选]
+  - 无单独 BUG 记录，本次属于布局 API 落地后的示例迁移
+- Commit:
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
+  - 当前功能区采用左/中/右固定宽度面板布局；窗口变宽时可稳定铺满，若后续需要进一步适配极窄窗口，再考虑把功能区做成等比分栏。

开发记录/功能变更/Feature-20260418-0010-当前阶段测试用例矩阵与定位.md

@@ -0,0 +1,156 @@
+# 功能变更 ID: Feature-20260418-0010
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260418-0010
+- 标题: 当前阶段测试用例矩阵与定位
+- 状态：已完成
+- 类型：修改
+- 级别：L1 轻量
+- 模块: 测试用例 / 回归策略
+- 版本 / 分支: 当前工作区
+- 环境: Windows + EasyX
+- 负责人: Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - 第二阶段主线、布局策略公开 API、`KEY2` 迁移以及近期重绘 / tooltip / overlay / `TabControl` / `Table` 修复已基本收口。
+  - 当前项目中同时存在 `KEY1 ~ KEY5` 多组测试入口，但各自负责覆盖什么、哪些是主集、哪些是专项补充，若不显式记录，后续容易继续依赖聊天上下文记忆。
+- 目标:
+  - 把当前阶段各测试入口的职责、覆盖范围和预期行为正式写成测试矩阵。
+  - 明确本阶段建议主回归集与补充专项。
+- 不做什么：[可选]
+  - 不新增测试逻辑。
+  - 不修改运行时代码。
+  - 不把测试矩阵扩成自动化测试体系。
+
+## 变更内容
+
+- 变更摘要:
+  - 新增当前阶段测试矩阵记录。
+  - 同步 `KEY1 ~ KEY5` 的阶段定位与行为预期。
+- 新增项：[可选]
+  - 当前阶段建议主回归集：`KEY1 + KEY2 + KEY5`
+  - Dialog / MessageBox 补充专项：`KEY4`
+- 修改项：[可选]
+  - 无代码修改，仅补充测试约定与阶段定位。
+- 删除 / 废弃项：[可选]
+  - 无
+- 受影响的文件 / 类 / 函数:
+  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp)
+- 对外 API / 属性变化：[可选]
+  - 无
+
+## 行为对照
+
+- 变更前:
+  - `KEY1 ~ KEY5` 的职责划分主要依赖源码注释和聊天上下文。
+  - 很难快速判断“当前阶段主回归集”与“专项补充集”分别是什么。
+- 变更后:
+  - 每个 `KEY` 入口的阶段定位、覆盖重点和行为预期都有正式记录。
+  - 可以按矩阵组织回归，而不再只靠记忆。
+- 兼容性说明：兼容
+- 迁移说明：[可选]
+  - 无需迁移，属于当前阶段测试约定落地。
+
+## 验证与落地
+
+- 验证方式:
+  - 对照当前 [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp) 中 `KEY1 ~ KEY5` 的实际结构与近期修复范围进行人工核对。
+- 验证结果:
+  - 当前矩阵与现有测试入口和阶段主线一致。
+- 关联 BUG / Fix：[可选]
+  - [Module-20260415-0004-布局系统第二阶段验收与封口.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/模块/Module-20260415-0004-布局系统第二阶段验收与封口.md)
+  - [Module-20260416-0005-布局策略公开API落地.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/模块/Module-20260416-0005-布局策略公开API落地.md)
+- Commit:
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
+  - resize 过程中若开启高频 console 日志，可能出现一帧视觉延迟；当前判断属于调试态 I/O 现象，不按 bug 处理。
+
+## 当前阶段测试矩阵
+
+### KEY1：旧页签链路 + Table 超界残留回归
+
+- 覆盖目标:
+  - `TabControl` 重复激活同一页签
+  - 切页 / 关页后的快照与清理链
+  - 页内容超出页范围时的残影与恢复
+- 当前预期:
+  - 外部重复激活当前页签，不再扰动当前页快照链。
+  - 页签 1 中 `Table` 超出页区域的部分，在切页或关闭页签时不会残留。
+  - 正常全量重绘后，不应再出现额外残影或层级错乱。
+- 阶段定位:
+  - 当前主回归集之一。
+
+### KEY2：公开布局 API 首个迁移样例
+
+- 覆盖目标:
+  - 新公开布局 API 的真实使用
+  - 位选择区容器化重构
+  - 显示区统一刷新链
+  - 顶层区块拉伸铺满
+- 当前预期:
+  - 32 位选择区中的“位号 + 位按钮”以单元整体位移，窗口拉伸后保持对齐。
+  - 位按钮点击、位取反、左移、右移、一键置 0/1、签名切换，会统一刷新十六进制、十进制、上次值、本次值和 `initData`。
+  - 顶层五个区块在正常拉伸 / 最大化后继续铺满窗口。
+  - 当前更偏重横向铺满验证；极窄窗口下功能区进一步自适应，不作为本阶段硬指标。
+- 阶段定位:
+  - 当前主回归集之一。
+  - 同时是新布局 API 的首个迁移示例。
+
+### KEY3：旧业务大场景保留用例
+
+- 覆盖目标:
+  - 保留老业务页示例
+  - 观察新主线是否把旧业务场景直接打坏
+- 当前预期:
+  - 登录页、`TabControl`、旧业务页基本行为保持可运行。
+  - 不要求覆盖新布局 API、overlay、tooltip 或第二阶段专项行为。
+- 阶段定位:
+  - 保留用例，不纳入当前主回归集。
+
+### KEY4：Dialog / MessageBox 专项回归
+
+- 覆盖目标:
+  - 模态 / 非模态 `Dialog`
+  - 遮挡交互
+  - 关闭后 hover 恢复
+  - 拖拽 resize
+- 当前预期:
+  - 非模态 `Dialog` 遮挡底层按钮时，不应出现 hover / tooltip 穿透或残留。
+  - 模态 `Dialog` 打开后拖拽窗口，标题、关闭按钮和底层恢复链保持稳定。
+  - 对话框关闭后，底层按钮 hover 能及时恢复。
+- 阶段定位:
+  - 当前补充专项，不纳入每轮主回归集。
+
+### KEY5：第二阶段专项主回归
+
+- 覆盖目标:
+  - 三层 `Canvas` 嵌套
+  - 跨容器 hover / tooltip
+  - overlay 补画与 coverage 链
+  - `TabControl`
+  - `Table`
+  - 页码与分页按钮
+- 当前预期:
+  - 三层 `Canvas` 嵌套下，深层按钮 hover / press / release / tooltip 都能正确刷新。
+  - `Window / Canvas / TabControl` 的 overlay 补画与 coverage 链闭合，不再出现遮挡错层。
+  - `TabControl` 页签按钮与页面层级正确；页签 tooltip 不会再被页面盖掉。
+  - `Table` 分页按钮、页码标签、与上层浮层相交时的重绘链保持正确。
+- 阶段定位:
+  - 当前主回归集之一。
+  - 第二阶段及重绘主线的核心专项入口。
+
+## 当前建议
+
+- 当前阶段建议主回归集:
+  - `KEY1 + KEY2 + KEY5`
+- 当前补充专项:
+  - `KEY4`
+- 暂不纳入每轮主集:
+  - `KEY3`

开发记录/功能变更/Feature-20260509-0011-布局API使用说明与旧接口覆盖规则.md

@@ -0,0 +1,295 @@
+# 功能变更 ID: Feature-20260509-0011
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260509-0011
+- 标题: 布局 API 使用说明与旧接口覆盖规则
+- 状态：已验证
+- 类型：新增
+- 级别：L2 中等
+- 模块: Layout API / Control
+- 版本 / 分支: 当前工作区
+- 环境: Windows + EasyX
+- 负责人: Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - 当前布局系统内部已经以 `LayoutSpec` 为统一解算依据。
+  - 旧接口 `setLayoutMode(...)` / `setAnchor(...)` 仍然保留，但只能表达有限的双锚点语义。
+  - 新增公开布局 API 后，需要明确用户应如何设置轴向锚点、尺寸策略和固定尺寸位移策略。
+- 目标:
+  - 说明新布局 API 的职责和使用方式。
+  - 明确新旧接口混用时的覆盖规则。
+  - 给出常见布局组合和 `KEY2` 迁移场景中的推荐写法。
+- 不做什么：[可选]
+  - 不开放 `LayoutCapability` 的普通外部写入接口。
+  - 不修改 `Table` 当前版本 `Y Fixed` 的能力边界。
+  - 不处理 Tooltip 智能选位、`Table` 内部局部重绘、`Dialog` synthetic move 统一等后置项。
+
+## 变更内容
+
+- 变更摘要:
+  - 增加布局 API 使用说明文档。
+  - 明确新接口与旧接口的覆盖关系。
+  - 汇总常见布局模式的代码写法。
+- 新增项：[可选]
+  - 新公开接口说明
+  - 旧接口映射说明
+  - 混用覆盖规则
+  - 常见写法示例
+  - 调试态日志说明
+- 修改项：[可选]
+  - 无运行时代码修改，本文件只记录使用说明。
+- 删除 / 废弃项：[可选]
+  - 无
+- 受影响的文件 / 类 / 函数:
+  - [`Control.h`](D:/programming/imGUI-easyX/imGui-easyX/Control.h)
+  - [`Control.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Control.cpp)
+  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp)
+- 对外 API / 属性变化：[可选]
+  - `setHorizontalLayoutSpec(...)`
+  - `setVerticalLayoutSpec(...)`
+  - `setHorizontalAnchors(...)`
+  - `setVerticalAnchors(...)`
+  - `setHorizontalSizePolicy(...)`
+  - `setVerticalSizePolicy(...)`
+  - `setHorizontalAlignPolicy(...)`
+  - `setVerticalAlignPolicy(...)`
+  - `getHorizontalLayoutSpec()`
+  - `getVerticalLayoutSpec()`
+
+## 行为对照
+
+- 变更前:
+  - 用户主要通过 `setLayoutMode(...)` 与 `setAnchor(...)` 设置布局。
+  - 固定尺寸 + 居中、固定尺寸 + 比例位移等组合无法通过旧接口清晰表达。
+  - 旧双锚点在某些测试场景中会被迫承担 Stretch 语义，导致固定按钮和内容驱动标签在 resize 后错位。
+- 变更后:
+  - 用户可按水平轴 / 垂直轴分别设置锚点集合、尺寸策略和固定尺寸位移策略。
+  - 旧接口仍可用，但只作为兼容输入层。
+  - 新旧接口混用时，最后调用的接口覆盖对应轴的布局规格。
+- 兼容性说明：兼容
+- 迁移说明：[可选]
+  - 新代码建议优先使用新布局 API。
+  - 旧代码可以继续使用 `setAnchor(...)`，但复杂布局应逐步迁移到新接口。
+
+## 验证与落地
+
+- 验证方式:
+  - 编译 `Control.cpp`
+  - 编译 `z-testDome.cpp /DKEY=2`
+  - 编译 `z-testDome.cpp /DKEY=5`
+  - 手测 `KEY1 / KEY2 / KEY5`
+- 验证结果:
+  - 编译级验证通过。
+  - 用户手测当前暂未发现问题。
+- 关联 BUG / Fix：[可选]
+  - [Feature-20260416-0009-KEY2-使用新布局API重构与联动刷新.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/功能变更/Feature-20260416-0009-KEY2-使用新布局API重构与联动刷新.md)
+  - [Feature-20260418-0010-当前阶段测试用例矩阵与定位.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/功能变更/Feature-20260418-0010-当前阶段测试用例矩阵与定位.md)
+- Commit:
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
+  - resize 收口阶段若开启高频 console 日志，可能出现一帧视觉延迟；当前按调试态 I/O 现象记录，不作为 bug 处理。
+
+## API 总览
+
+### 完整轴向规格接口
+
+```cpp
+void setHorizontalLayoutSpec(const StellarX::AxisLayoutSpec& spec);
+void setVerticalLayoutSpec(const StellarX::AxisLayoutSpec& spec);
+```
+
+- 直接覆盖对应轴的完整布局规格。
+- 调用后自动切换到 `StellarX::LayoutMode::AnchorToEdges`。
+- 适合调用方已经准备好完整 `AxisLayoutSpec` 的场景。
+
+### 锚点集合接口
+
+```cpp
+void setHorizontalAnchors(bool left, bool right);
+void setVerticalAnchors(bool top, bool bottom);
+```
+
+- 水平轴对应 `left / right`。
+- 垂直轴对应 `top / bottom`。
+- 只修改对应轴的锚点集合，不主动改变尺寸策略或位移策略。
+
+### 尺寸策略接口
+
+```cpp
+void setHorizontalSizePolicy(StellarX::AxisSizePolicy policy);
+void setVerticalSizePolicy(StellarX::AxisSizePolicy policy);
+```
+
+- `Stretch`：允许该轴尺寸随父容器变化。
+- `FixedSize`：该轴尺寸保持设计态尺寸。
+- 控件能力边界仍然生效。例如 `Table` 当前版本不允许 `Y Stretch`，即使用户设置垂直 `Stretch`，也会被能力边界降级。
+
+### 固定尺寸位移策略接口
+
+```cpp
+void setHorizontalAlignPolicy(StellarX::AxisAlignPolicy policy);
+void setVerticalAlignPolicy(StellarX::AxisAlignPolicy policy);
+```
+
+- 只在 `FixedSize` 语义下决定位置。
+- 不负责改变尺寸。
+- 常用值：
+  - `Start`：保持起边关系，例如左固定、上固定。
+  - `End`：保持终边关系，例如右固定、下固定。
+  - `Center`：保持居中关系。
+  - `Proportional`：保持设计态相对位置比例，适合固定尺寸控件在可变宽容器中按比例移动。
+
+### 读取接口
+
+```cpp
+StellarX::AxisLayoutSpec getHorizontalLayoutSpec() const;
+StellarX::AxisLayoutSpec getVerticalLayoutSpec() const;
+```
+
+- 返回当前生效的新模型轴向规格。
+- 不保证能完整逆映射回旧 `anchor_1 / anchor_2` 语义。
+
+## 新旧接口覆盖规则
+
+### 旧接口仍然保留
+
+```cpp
+void setLayoutMode(StellarX::LayoutMode layoutMode);
+void setAnchor(StellarX::Anchor anchor1, StellarX::Anchor anchor2);
+```
+
+- 旧接口是兼容入口。
+- `setAnchor(...)` 内部会把旧双锚点映射到新的 `layoutSpec.horizontal` 与 `layoutSpec.vertical`。
+- 旧接口无法表达所有新模型状态，例如固定尺寸 + 比例位移、固定尺寸 + 居中等。
+
+### 后调用者生效
+
+规则：
+
+- 先调用 `setAnchor(...)`，再调用新 API，则新 API 覆盖对应轴规格。
+- 先调用新 API，再调用 `setAnchor(...)`，则旧接口重新覆盖水平轴和垂直轴规格。
+- 新 API 只覆盖自己负责的轴或字段。例如 `setHorizontalSizePolicy(...)` 只修改水平轴尺寸策略，不修改垂直轴。
+
+示例：
+
+```cpp
+button->setLayoutMode(StellarX::LayoutMode::AnchorToEdges);
+button->setAnchor(StellarX::Anchor::Left, StellarX::Anchor::Right);
+
+// 覆盖水平轴：改为固定尺寸 + 居中，不再沿用旧接口映射出的 Stretch。
+button->setHorizontalSizePolicy(StellarX::AxisSizePolicy::FixedSize);
+button->setHorizontalAlignPolicy(StellarX::AxisAlignPolicy::Center);
+```
+
+### 新 API 自动切换布局模式
+
+所有新布局 setter 都会自动将 `layoutMode` 切换为 `AnchorToEdges`。
+因此新代码通常不需要再额外写：
+
+```cpp
+control->setLayoutMode(StellarX::LayoutMode::AnchorToEdges);
+```
+
+## 常见布局写法
+
+### 左固定
+
+```cpp
+control->setHorizontalAnchors(true, false);
+control->setHorizontalSizePolicy(StellarX::AxisSizePolicy::FixedSize);
+control->setHorizontalAlignPolicy(StellarX::AxisAlignPolicy::Start);
+```
+
+### 右固定
+
+```cpp
+control->setHorizontalAnchors(false, true);
+control->setHorizontalSizePolicy(StellarX::AxisSizePolicy::FixedSize);
+control->setHorizontalAlignPolicy(StellarX::AxisAlignPolicy::End);
+```
+
+### 水平拉伸
+
+```cpp
+control->setHorizontalAnchors(true, true);
+control->setHorizontalSizePolicy(StellarX::AxisSizePolicy::Stretch);
+control->setHorizontalAlignPolicy(StellarX::AxisAlignPolicy::Start);
+```
+
+### 固定尺寸居中
+
+```cpp
+control->setHorizontalAnchors(true, true);
+control->setHorizontalSizePolicy(StellarX::AxisSizePolicy::FixedSize);
+control->setHorizontalAlignPolicy(StellarX::AxisAlignPolicy::Center);
+```
+
+### 固定尺寸比例位移
+
+```cpp
+control->setHorizontalAnchors(true, true);
+control->setHorizontalSizePolicy(StellarX::AxisSizePolicy::FixedSize);
+control->setHorizontalAlignPolicy(StellarX::AxisAlignPolicy::Proportional);
+```
+
+适用场景：
+
+- 一组固定尺寸按钮需要随着父容器变宽按比例展开。
+- `KEY2` 中每个 bit 单元就是该策略的典型使用方式。
+
+## KEY2 迁移要点
+
+`KEY2` 原问题不是单纯参数错误，而是布局单元拆分不合理：
+
+- 位号 `Label` 是内容驱动尺寸。
+- 位按钮是固定尺寸。
+- 二者分别使用比例位移时，因为自身尺寸不同，resize 后会出现错位。
+
+当前迁移方式：
+
+- 每一位创建一个小 `Canvas` 单元。
+- 单元内部固定放置位号 `Label` 与位按钮。
+- 单元自身使用 `FixedSize + Proportional`。
+- 这样移动的是整个 bit 单元，而不是标签和按钮分别移动。
+
+示意写法：
+
+```cpp
+auto cell = std::make_unique<Canvas>(cellX, 0, 32, 50);
+cell->setHorizontalAnchors(true, true);
+cell->setHorizontalSizePolicy(StellarX::AxisSizePolicy::FixedSize);
+cell->setHorizontalAlignPolicy(StellarX::AxisAlignPolicy::Proportional);
+```
+
+## 能力边界说明
+
+布局 API 表达的是“调用方希望如何布局”，但控件能力边界仍然优先。
+
+当前关键边界：
+
+- `Canvas`：`X / Y` 均允许 Stretch。
+- `TabControl`：外层允许 Stretch，内部页签栏 / 页面区仍由自身管理。
+- `Table`：当前版本 `X Stretch / Y Fixed`，这是当前实现边界，不是永久产品结论。
+- `TextBox`：默认更适合 `X Stretch / Y FixedSize`。
+- `Label`：默认固定或内容驱动刷新运行态尺寸，不建议做双轴 Stretch。
+- `Dialog`：只居中，不参与父级拉伸。
+
+如果用户设置的策略超出控件能力边界，统一解算层会按现有降级规则处理，并保留必要日志。
+
+## 调试态说明
+
+resize / 最大化 / 还原过程中，如果开启大量 console 日志，可能出现一帧视觉延迟或短暂残影。
+当前判断原因是日志系统同步写控制台且默认逐行 flush，导致主线程 resize 收口绘制被 I/O 拖慢。
+
+处理建议：
+
+- 常规手测可关闭 console 日志。
+- 需要日志时可优先输出到文件。
+- 当前不作为布局或重绘 bug 处理，后续可在官网/API 文档中作为调试说明记录。