Make/StellarX-kaifa
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 收口阶段 2 焦点系统与回归结论

Browse Source
This commit is contained in:
Codex
2026-10-08 18:38:14 +08:00
parent 255aba688f
commit 69c26a35a2
3 changed files with 211 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
开发记录/TESTING.md
+14 -1
View File
@@ -25,7 +25,7 @@
- `Unit`：构建核心静态库并运行 VS Native Unit Test。 - `Unit`：构建核心静态库并运行 VS Native Unit Test。
- `NonUI`：运行 Debug x64、Debug x64 ASan、Release x64、Debug Win32 和 KEY1 至 KEY6 编译，不启动或操作任何窗口。 - `NonUI`：运行 Debug x64、Debug x64 ASan、Release x64、Debug Win32 和 KEY1 至 KEY6 编译，不启动或操作任何窗口。
- `Render`：运行确定性 EasyX fixture 和关键像素断言；当前与单轮 UI fixture 共用实现。 - `Render`：运行确定性 EasyX fixture 和关键像素断言；当前与单轮 UI fixture 共用实现。
- `UI`：使用 `SendInput` 驱动 ownership、geometry、tooltip、tab、table、dialog 六类真实窗口场景。 - `UI`：使用 `SendInput` 驱动 ownership、geometry、tooltip、tab、table、dialog、focus、input-shadow 八类真实窗口场景。
- `All`：Debug x64、Debug x64 ASan、Release x64、Debug Win32、KEY1 至 KEY6 编译、UI 连续三轮。 - `All`：Debug x64、Debug x64 ASan、Release x64、Debug Win32、KEY1 至 KEY6 编译、UI 连续三轮。
- `CI`：默认运行 Debug x64、Release x64 和 Debug Win32；设置 `STELLARX_UI_TESTS=1` 后增加单轮 UI。 - `CI`：默认运行 Debug x64、Release x64 和 Debug Win32；设置 `STELLARX_UI_TESTS=1` 后增加单轮 UI。
@@ -44,6 +44,8 @@ Windows MSVC AddressSanitizer 不支持 LeakSanitizer，因此脚本使用 `dete
- Tooltip 单调时钟 tick、禁用和移出清理。 - Tooltip 单调时钟 tick、禁用和移出清理。
- 1000 条消息的 128 条批处理上限、空闲休眠和关闭顺序。 - 1000 条消息的 128 条批处理上限、空闲休眠和关闭顺序。
- 日志配置原子切换与滚动行完整性。 - 日志配置原子切换与滚动行完整性。
- FocusTargetId 递归解析、焦点回调重入、单槽 pending、64 轮活性保护、作用域恢复和 pending removal 回退。
- TabControl 真实页签句柄与非活动页面焦点过滤。
UI/像素测试覆盖： UI/像素测试覆盖：
@@ -53,6 +55,8 @@ UI/像素测试覆盖：
- 同名页签唯一选中、唯一页面可见。 - 同名页签唯一选中、唯一页面可见。
- 极窄 Table 的最小宽度和 coverage 外像素不变量。 - 极窄 Table 的最小宽度和 coverage 外像素不变量。
- 两层异步 Dialog 先后关闭、下层可见且可继续交互。 - 两层异步 Dialog 先后关闭、下层可见且可继续交互。
- Button/TextBox 焦点框、Table 分页 Button 动态资格、TabControl 活动页焦点树和 `subNode == 0`。
- 阶段 1 新队列与旧 `EX_KEY` 旁路的 input-shadow 顺序、排空与内存稳定性。
## 诊断产物 ## 诊断产物
@@ -138,6 +142,15 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-key.ps1
- KEY2 是 KEY1–6 中唯一启用文件日志的场景；轮转阈值由 `1024` 字节调整为 `10 * 1024 * 1024` 字节（10 MiB）。轮转在完整日志行写完后检查，单文件允许最多超出最后一行的长度。 - KEY2 是 KEY1–6 中唯一启用文件日志的场景；轮转阈值由 `1024` 字节调整为 `10 * 1024 * 1024` 字节（10 MiB）。轮转在完整日志行写完后检查，单文件允许最多超出最后一行的长度。
- 调整后执行正式 `NonUI`：Debug x64、x64 ASan、Release x64、Debug Win32 均为 27/27，KEY1–6 全部重新编译链接成功。 - 调整后执行正式 `NonUI`：Debug x64、x64 ASan、Release x64、Debug Win32 均为 27/27，KEY1–6 全部重新编译链接成功。
### 阶段 2 通用焦点自动回归（2026-10-08）
- `FocusManagerTests` 覆盖嵌套解析、PointerDown、回调删除/禁用目标、FocusGained 自删、单槽 latest-wins、FocusLost/FocusGained 中 pushScope、64 轮上限、active removal、clear 批量失效、真实页签句柄和非活动页面过滤。
- 正式 `NonUI`：Debug x64、x64 ASan、Release x64、Debug Win32 均为 40/40；KEY1–KEY6 全部编译/链接成功。
- 最终源码的独立 `focus` UI 连续 3 轮通过：TextBox 初始焦点框、Button 点击焦点框、第一页 Table 仅 next 分页 Button 进入 Tab stop、活动页后代存在、非活动页后代缺席、全部现有目标 `subNode == 0`。
- 针对旧 `tooltip` 像素等待和 `geometry` 点击结果超时，以阶段 1 基线 `81341fa` 和阶段 2 工作树执行受控 A/B：62/62 个结构化样本通过，geometry、tooltip 两端各累计 8/8，共有七场景两端各 3/3；双方未出现失败断言或明显耗时劣化。
- 当前阶段 2 随后通过正式完整 UI 三轮，八场景共 24/24。结论仅排除阶段 2 稳定引入的隐性回归；此前超时定性为间歇性桌面 fixture / 输入时序波动，仍保留残余偶发波动的可能，不表述为“证明 UI 永不波动”。
- 阶段 2 的实现与回归归因门槛均已关闭，可以进入阶段 3。阶段 2 不迁移键盘业务，不需要重复真实 IME 提交矩阵；阶段 1 的 IME/KEY1–6 人工基线继续有效，阶段 3 仍需明确 Tab 导航和 `EX_KEY` 原子换轨测试。
### 失败留证 ### 失败留证
- 记录 KEY 编号、窗口尺寸、操作顺序和实际现象。 - 记录 KEY 编号、窗口尺寸、操作顺序和实际现象。
开发记录/模块/Module-20261001-0001-通用输入焦点与键盘路由系统设计.md
+71 -32
View File
@@ -7,7 +7,7 @@
- 模块 ID：Module-20261001-0001 - 模块 ID：Module-20261001-0001
- 模块名称：通用输入采集、焦点与键盘路由系统 - 模块名称：通用输入采集、焦点与键盘路由系统
- 状态：实现中（v0.14；0C/0B 前置基线已关闭；阶段 1 输入采集、规范化与观察队列已落地并通过自动回归，待真实 IME/KEY1–6 人工回归；焦点与键盘路由尚未开始） - 状态：实现中（v0.16；0C/0B 前置基线、阶段 1 输入地基及阶段 2 实现与回归归因均已关闭；可以进入阶段 3，键盘换轨尚未开始）
- 类型：新增模块 / 架构演进 - 类型：新增模块 / 架构演进
- 所属系统 / 子系统：StellarX Core / Window / Control / Input / Focus / TextBox - 所属系统 / 子系统：StellarX Core / Window / Control / Input / Focus / TextBox
- 版本 / 分支：`master`，阶段 0A 实现基线 `c218c25` - 版本 / 分支：`master`，阶段 0A 实现基线 `c218c25`
@@ -37,7 +37,7 @@
- v1 不自绘 IME 拼音组合串和候选列表，继续使用系统 IME UI。 - v1 不自绘 IME 拼音组合串和候选列表，继续使用系统 IME UI。
- v1 不重写现有全部鼠标采集链；现有 EasyX 鼠标消息只在框架入口规范化为 `PointerEvent`。 - v1 不重写现有全部鼠标采集链；现有 EasyX 鼠标消息只在框架入口规范化为 `PointerEvent`。
- v1 不承诺完整 Unicode grapheme cluster 编辑，只保证不拆分 UTF-16 代理对。 - v1 不承诺完整 Unicode grapheme cluster 编辑，只保证不拆分 UTF-16 代理对。
- 本稿中的阶段 1 已有实现记录和自动验证证据；阶段 2 至阶段 6 仍是设计目标，不应被误读为已经实现。 - 本稿中的阶段 1 与阶段 2 已有实现记录和自动验证证据；阶段 3 至阶段 6 仍是设计目标，不应被误读为已经实现。
## 模块边界 ## 模块边界
@@ -566,15 +566,23 @@ DPI 规则：
#### 10.1 焦点能力 #### 10.1 焦点能力
```cpp ```cpp
enum class FocusPolicy enum class FocusPolicy : std::uint8_t
{ {
None, None = 0,
Programmatic, Programmatic = 1u << 0,
Click, Pointer = 1u << 1,
TabAndClick Tab = 1u << 2
};
struct FocusTargetId
{
ControlHandle owner;
std::uint32_t subNode = 0;
}; };
``` ```
`FocusTargetId` 是 FocusManager 唯一长期身份。阶段 2 审计确认 Table 分页按钮与 TabControl 页签按钮都是真实 `Button`，所以现有焦点节点全部使用 `{buttonHandle, 0}`；非零 `subNode` 只预留给未来确实没有独立 `Control` 的轻量节点，不得为现有 Button 制造第二套身份。
| 控件 | 焦点角色 | | 控件 | 焦点角色 |
|---|---| |---|---|
| Label | 不可聚焦 | | Label | 不可聚焦 |
@@ -586,20 +594,28 @@ enum class FocusPolicy
| Dialog | 焦点作用域 | | Dialog | 焦点作用域 |
| Window | 根焦点作用域 | | Window | 根焦点作用域 |
#### 10.2 `ControlHandle` #### 10.2 身份与瞬时快照协议
当前 `ControlHandle` 是进程内单调递增且不复用的 `uint64_t`，`0` 表示无效；不存在 slot/generation 复用模型。焦点树长期只保存 `FocusTargetId`，解析时临时取得 `FocusTargetSnapshot`：
```cpp ```cpp
struct ControlHandle struct FocusTargetSnapshot
{ {
WindowId owner; FocusTargetId id;
uint32_t slot; FocusTargetId logicalParent;
uint32_t generation; FocusScopeId scope;
FocusPolicy policy;
bool visible;
bool enabled;
bool focusable;
bool tabStop;
std::int32_t tabIndex;
}; };
``` ```
- slot 重用必须递增 generation。 - `Window::findControl()` 只查直接子级，不能承担焦点解析；FocusManager 使用独立递归协议遍历 Canvas、Table 和 TabControl。
- 失效句柄解析为空。 - `enabled` 由控件协议动态给出，不假定基类存在统一 enabled 字段；例如 Button 从 `ButtonMode::DISABLED` 推导。
- `collectTabStops()` 返回 `ControlHandle`。 - 快照布尔值只代表采集时刻。任何 FocusLost/FocusGained 用户回调结束后必须重新解析并重新拉取全部字段。
- `Control*` 只允许作为当前函数内立即使用的借用视图，不得跨事件、回调、mutation transaction 或模态调用保存。 - `Control*` 只允许作为当前函数内立即使用的借用视图，不得跨事件、回调、mutation transaction 或模态调用保存。
#### 10.3 焦点有效条件 #### 10.3 焦点有效条件
@@ -618,19 +634,23 @@ struct ControlHandle
```cpp ```cpp
FocusChangeResult requestFocus( FocusChangeResult requestFocus(
ControlHandle target, FocusTargetId target,
FocusReason reason); FocusReason reason);
``` ```
顺序： 切换在宿主线程的 mutation transaction 中执行：
1. 验证目标。 1. 重新解析并验证目标。
2. 保存旧句柄。 2. 保存旧 `FocusTargetId`，临时清空 active。
3. 更新 FocusManager。 3. 向旧目标发送 `FocusLost`；回调可删除控件、切页、push scope 或再次请求焦点。
4. 向旧目标发送 `FocusLost`。 4. 回调后重新拉取目标的完整快照；目标失效时保持无焦点，不复活旧目标。
5. 向新目标发送 `FocusGained`。 5. 提交新 active，再发送 `FocusGained`。
6. 使相关区域失效并重绘。 6. 回调后再次验证 active；active 失效才进入独立的失效回退路径。
7. 新目标为 TextBox 时更新 IME 锚点。 7. 使旧/新控件所属托管区域失效并重绘。
回调内的 `requestFocus()` 不递归切换，只覆盖当前回合的单槽 pending。回合末只验证最终槽位；最终请求失效就丢弃，不恢复被覆盖请求。一次外层调用最多执行 64 轮，超限返回 `FocusError::ReentrancyLimit`、清空 pending，并保留最后一个已提交且仍有效的 active。
`pushScope()` 若发生在 FocusLost 回调中，恢复点取该回调对应的旧目标；若发生在 FocusGained 回调中，恢复点取新目标。不能因为切换中间态 `activeTarget` 暂时为空而丢失外层恢复身份。
#### 10.5 焦点失效回退 #### 10.5 焦点失效回退
@@ -645,6 +665,8 @@ FocusChangeResult requestFocus(
控件进入 pending removal 前，必须先让焦点系统中的对应句柄失效。 控件进入 pending removal 前，必须先让焦点系统中的对应句柄失效。
pending 请求失效与 active 焦点失效是两个入口：pending 失效只丢弃；active 失效才执行上述回退。`clearControls()` 必须先批量标记整批子树失效，再选择后备，禁止焦点落到同批即将删除的兄弟控件。
#### 10.6 Dialog 作用域 #### 10.6 Dialog 作用域
Dialog 打开： Dialog 打开：
@@ -661,6 +683,8 @@ Dialog 关闭：
3. 验证并恢复原焦点。 3. 验证并恢复原焦点。
4. 原焦点失效时执行外层回退。 4. 原焦点失效时执行外层回退。
阶段 2 只实现并测试 `pushScope/popScope` 机制，使用测试作用域验证重入与恢复；真实 Dialog 的打开/关闭接入仍留阶段 4，避免在焦点地基阶段提前改变模态行为。
### 11. Tab 顺序与复合控件 ### 11. Tab 顺序与复合控件
#### 11.1 Tab 顺序 #### 11.1 Tab 顺序
@@ -1048,11 +1072,14 @@ struct ProbeConsumeRule
#### 阶段 2：FocusManager #### 阶段 2：FocusManager
- ControlHandle。 - 已实现 `FocusTargetId`、瞬时快照协议和递归焦点树解析。
- 焦点申请与回退。 - 已实现每 Window `FocusManager`、焦点申请、失效回退、单槽重入与 64 轮活性保护。
- Window/Dialog FocusScope。 - 已实现 FocusScope 机制与恢复身份；真实 Dialog 接入留阶段 4。
- PointerDown 申请焦点。 - Button/TextBox PointerDown 申请焦点并绘制焦点框。
- mutation 生命周期。 - Table 暴露真实分页 Button；TabControl 暴露真实页签 Button 和活动页面树。
- pending removal 入队时逻辑失效，并与 mutation transaction 同步收口。
- 阶段 1 基线与阶段 2 工作树受控 A/B 为 62/62，通过后当前阶段 2 正式完整 UI 三轮 24/24；未发现阶段 2 相关失败或耗时劣化，阶段 2 实现与回归归因门槛均已关闭。
- 不实现 Tab 键导航、按键路由、Table 键盘翻页、页签 roving-tab-stop 或 TextBox 编辑内核。
#### 阶段 3：KeyboardRouter #### 阶段 3：KeyboardRouter
@@ -1060,6 +1087,8 @@ struct ProbeConsumeRule
- 句柄路由路径。 - 句柄路由路径。
- 冒泡和框架默认动作。 - 冒泡和框架默认动作。
- Button 和 Dialog 键盘行为。 - Button 和 Dialog 键盘行为。
- Table 分页 Button 仅在首次 draw 后 materialize；首次 draw 前“无可遍历项”表示焦点树尚未就绪，不得缓存或解释为该 Table 永久没有 Tab stop。
- Button 键盘按压态必须与阶段 2 的最小焦点框叠加绘制，不得用按压态覆盖或抹除键盘焦点反馈。
#### 阶段 4：复合控件 #### 阶段 4：复合控件
@@ -1117,17 +1146,26 @@ struct ProbeConsumeRule
33. `mutex + deque` 在正常资源条件下不得丢输入；分配失败或队列异常必须 fail-stop，不能捕获后假装成功。 33. `mutex + deque` 在正常资源条件下不得丢输入；分配失败或队列异常必须 fail-stop，不能捕获后假装成功。
34. `WM_IME_ENDCOMPOSITION` 不得在转发旧窗口过程之前清空结果回声；END 处理中嵌套或紧随其后的匹配 `WM_IME_CHAR/WM_CHAR` 仍须抑制重复入队。 34. `WM_IME_ENDCOMPOSITION` 不得在转发旧窗口过程之前清空结果回声；END 处理中嵌套或紧随其后的匹配 `WM_IME_CHAR/WM_CHAR` 仍须抑制重复入队。
35. 无效文本序列、IMM 查询失败和残留半截解码状态必须以不含原文的计数显式诊断，不得写入替代文本或静默记为成功。 35. 无效文本序列、IMM 查询失败和残留半截解码状态必须以不含原文的计数显式诊断，不得写入替代文本或静默记为成功。
36. 焦点长期身份统一为 `FocusTargetId`；现有真实 Control 节点一律使用 `subNode == 0`，Table 分页和 TabControl 页签不得建立合成身份。
37. 当前 `ControlHandle` 在进程内单调分配且不复用，不采用 slot/generation 草案；焦点解析使用独立递归快照协议。
38. 焦点回调重入使用当前事务回合内的单槽 latest-wins；最终槽位失效只丢弃，不复活旧请求。
39. 焦点切换最多 64 轮；超限以 `FocusError::ReentrancyLimit` 明确失败，并保留最后一个仍有效的已提交焦点。
40. removal 请求入队时立即让对应焦点子树逻辑失效；批量 clear 必须先使整批失效，再执行 active 回退。
41. 阶段 2 只建立 FocusScope 机制；真实 Dialog 作用域接入、Tab 导航和键盘路由不得提前混入。
42. 阶段 3 的 Tab 遍历必须区分 Table 分页 Button“首次 draw 前尚未 materialize”与“永久无停靠项”，不得把 draw 前空快照固化为长期结论。
43. 阶段 3 的 Button 键盘按压视觉必须叠加在最小焦点框之上，焦点框不得因按压态切换而消失。
## 实现与影响 ## 实现与影响
- 关键实现点: - 关键实现点:
- 阶段 0A 探测器和 0C 独立视觉探测已进入仓库；阶段 1 的生产 NativeInputQueue、输入事件结构、采集规范化、IME 状态与观察排空已实现。FocusManager、KeyboardRouter 和 TextBox 改造尚未开始。 - 阶段 0A 探测器和 0C 独立视觉探测已进入仓库；阶段 1 的 NativeInputQueue 与输入规范化已经实现；阶段 2 的 FocusManager、递归焦点协议、PointerDown 聚焦、失效回退和作用域机制已经实现。KeyboardRouter 与 TextBox 编辑内核尚未开始。
- 独立 EasyX 探测已经推翻 v0.4 的单线程假设，v0.5 据此补入跨线程队列约束；v0.6 根据微软拼音/搜狗真实日志锁定结果串与回声关系，并补入输入布局 request/change 分层；v0.7 根据专用短测区分 TSF 配置文件切换与跨语言 HKL，并增加重新获焦快照约束；v0.8 根据 0C 自动证据锁定宽字符绘制、批次进入顺序与当前 DPI 坐标规则；v0.9 根据搜狗真实失败与修复复验锁定 IME 位置双时机规则；v0.13 根据 0B 证据锁定默认转发与无生产消费白名单；v0.14 根据阶段 1 实现审查锁定 EX_KEY 兼容过渡、两轴快照、fail-stop、END 回声边界和显式异常计数。 - 独立 EasyX 探测已经推翻 v0.4 的单线程假设，v0.5 据此补入跨线程队列约束；v0.6 根据微软拼音/搜狗真实日志锁定结果串与回声关系，并补入输入布局 request/change 分层；v0.7 根据专用短测区分 TSF 配置文件切换与跨语言 HKL，并增加重新获焦快照约束；v0.8 根据 0C 自动证据锁定宽字符绘制、批次进入顺序与当前 DPI 坐标规则；v0.9 根据搜狗真实失败与修复复验锁定 IME 位置双时机规则；v0.13 根据 0B 证据锁定默认转发与无生产消费白名单；v0.14 根据阶段 1 实现审查锁定 EX_KEY 兼容过渡、两轴快照、fail-stop、END 回声边界和显式异常计数；v0.15 根据阶段 2 审计与实现锁定 FocusTargetId、瞬时快照、单槽重入、64 轮活性保护和 pending removal 即时失效；v0.16 根据受控 A/B 和正式完整 UI 三轮结果关闭阶段 2 回归归因门槛，并锁定 Table 首次 draw 生命周期与 Button 按压/焦点视觉叠加约束。
- 涉及文件 / 类 / 函数: - 涉及文件 / 类 / 函数:
- 预计涉及 `Window`、`Control`、`Canvas`、`Button`、`TextBox`、`Table`、`TabControl`、`Dialog`。 - 预计涉及 `Window`、`Control`、`Canvas`、`Button`、`TextBox`、`Table`、`TabControl`、`Dialog`。
- 实际文件和接口必须在阶段 0 与实现前只读检查后确定。 - 实际文件和接口必须在阶段 0 与实现前只读检查后确定。
- 兼容性影响: - 兼容性影响:
- 设计目标是保留现有鼠标行为和公共文本 API 的兼容入口。 - 设计目标是保留现有鼠标行为和公共文本 API 的兼容入口。
- 阶段 2 向 `Control` 增加焦点协议虚接口，现有二进制派生控件需要重新编译；源码接口没有删除，源码分发用户按正常流程重编译即可。
- 阶段 1 不改变现有 `EX_KEY` 业务交付；阶段 3 停止向 `Control::handleEvent()` 下发 `EX_KEY` 时属于明确的派生控件迁移点，`EX_MOUSE` 永久保留。 - 阶段 1 不改变现有 `EX_KEY` 业务交付；阶段 3 停止向 `Control::handleEvent()` 下发 `EX_KEY` 时属于明确的派生控件迁移点，`EX_MOUSE` 永久保留。
- 输入链路和 TextBox 内部模型将发生架构级变化，必须分阶段接入。 - 输入链路和 TextBox 内部模型将发生架构级变化，必须分阶段接入。
- 性能影响: - 性能影响:
@@ -1142,7 +1180,7 @@ struct ProbeConsumeRule
- 测试范围: - 测试范围:
- 设计评审覆盖输入采集、同步消息、Unicode、IME、焦点、复合控件、按键归属、TextBox 和模态重入。 - 设计评审覆盖输入采集、同步消息、Unicode、IME、焦点、复合控件、按键归属、TextBox 和模态重入。
- 独立线程归属探测、0A、0C、0B 门槛均已完成；阶段 1 已加入逻辑测试与真实 EasyX `input-shadow` 场景，焦点系统尚未开始。 - 独立线程归属探测、0A、0C、0B 门槛均已完成；阶段 1 已加入逻辑测试与真实 EasyX `input-shadow` 场景；阶段 2 已加入焦点事务单测和真实 EasyX `focus` 场景，并以 62/62 受控 A/B 和 24/24 正式完整 UI 关闭回归归因门槛。
- 验证步骤: - 验证步骤:
1. 先按关联规格实现阶段 0A 被动探测并取得消息链路证据。 1. 先按关联规格实现阶段 0A 被动探测并取得消息链路证据。
@@ -1172,6 +1210,7 @@ struct ProbeConsumeRule
- 2026-10-07：搜狗候选态没有向目标 HWND 暴露 START/COMPOSITION/END 生命周期；最终 Consume 请求以 `ime_condition_not_met` 正确 fail-open 为 Forward，规则零命中、零消费、EasyX 键出现一次，结构 verdict 为 `MustForward`。 - 2026-10-07：搜狗候选态没有向目标 HWND 暴露 START/COMPOSITION/END 生命周期；最终 Consume 请求以 `ime_condition_not_met` 正确 fail-open 为 Forward，规则零命中、零消费、EasyX 键出现一次，结构 verdict 为 `MustForward`。
- 2026-10-07：最终 Debug x64 单元测试 15/15、UI fixture 1 轮、F24 KeyDown A/B 新运行通过；既有 KeyUp 与 baseline mismatch 证据经当前分析器回放保持有效。阶段 1 以默认转发且无消费白名单为起点。 - 2026-10-07：最终 Debug x64 单元测试 15/15、UI fixture 1 轮、F24 KeyDown A/B 新运行通过；既有 KeyUp 与 baseline mismatch 证据经当前分析器回放保持有效。阶段 1 以默认转发且无消费白名单为起点。
- 2026-10-07：阶段 1 自动回归通过：Debug x64、x64 ASan、Release x64、Debug Win32 均为 27/27，KEY1–6 全部编译/链接成功；完整 UI fixture 曾一轮通过，最终源码的独立 `input-shadow` 再次通过，旧 EX_KEY 与新队列均完整观察 4000/4000 条事件，新队列最终深度 0、顺序严格、内存增长 0、无 fault/规范化异常；PowerShell 5.1/7 AST、工程 XML 和 `git diff --check` 通过。最终完整 UI 的两次追加复跑分别在 `geometry/ownership` 鼠标点击检查点超时，均未进入输入场景，按既有桌面焦点抖动保留失败证据，不冒充最终全套连续通过。真实 IME 与 KEY1–6 交互仍待人工确认。 - 2026-10-07：阶段 1 自动回归通过：Debug x64、x64 ASan、Release x64、Debug Win32 均为 27/27，KEY1–6 全部编译/链接成功；完整 UI fixture 曾一轮通过，最终源码的独立 `input-shadow` 再次通过，旧 EX_KEY 与新队列均完整观察 4000/4000 条事件，新队列最终深度 0、顺序严格、内存增长 0、无 fault/规范化异常；PowerShell 5.1/7 AST、工程 XML 和 `git diff --check` 通过。最终完整 UI 的两次追加复跑分别在 `geometry/ownership` 鼠标点击检查点超时，均未进入输入场景，按既有桌面焦点抖动保留失败证据，不冒充最终全套连续通过。真实 IME 与 KEY1–6 交互仍待人工确认。
- 2026-10-08：阶段 2 FocusManager 完成实现审查；Debug x64、x64 ASan、Release x64、Debug Win32 均为 40/40，KEY1–6 全部编译/链接成功。最终源码的独立 `focus` UI 连续 3 轮通过。针对随后出现的 Tooltip 像素等待和 geometry 点击结果超时，以阶段 1 基线 `81341fa` 与阶段 2 工作树执行受控 A/B，62/62 个结构化样本全部通过；当前阶段 2 正式完整 UI 三轮八场景共 24/24 通过，未发现阶段 2 相关失败或耗时劣化。此前超时定性为间歇性桌面 fixture / 输入时序波动，仍保留残余偶发波动可能，不把关闭门槛表述为证明 UI 永不波动。
- 已知限制 / 遗留问题: - 已知限制 / 遗留问题:
- §5.3 当前明确不建立生产消费白名单；若后续需要窄消费规则，仍必须补对应消息、虚拟键、IME 和环境的独立 0B 证据。 - §5.3 当前明确不建立生产消费白名单；若后续需要窄消费规则，仍必须补对应消息、虚拟键、IME 和环境的独立 0B 证据。
- §7.3 的微软拼音/搜狗回声状态机已有 0A 证据，其他 IME 仍需保持可诊断回退。 - §7.3 的微软拼音/搜狗回声状态机已有 0A 证据，其他 IME 仍需保持可诊断回退。
开发记录/模块/Module-20261008-0006-阶段2通用焦点管理器实现.md
+126
View File
@@ -0,0 +1,126 @@
# 新增功能模块 / 模块重构
> 本记录描述通用输入系统阶段 2 的实际实现边界。阶段 2 建立逻辑焦点地基，但不切换键盘业务轨道。
## 基本信息
- 模块 ID：Module-20261008-0006
- 模块名称：阶段 2 通用焦点管理器与复合控件焦点树
- 状态：实现及回归归因均已关闭，可以进入阶段 3
- 类型：新增模块 / 架构演进
- 所属系统 / 子系统：StellarX Core / Window / Control / Focus
- 版本 / 分支：`master`，未提交工作区
- 环境：Windows + Visual Studio 2022 + MSVC v143 + EasyX + MBCS 工程配置
- 负责人：Codex 协作实现
## 背景与目标
- 阶段 1 已建立跨线程输入采集和观察队列，但没有“哪个控件持有逻辑焦点”的统一模型。
- 焦点不能成为 TextBox 私有状态；Button、TextBox、Table 分页 Button、TabControl 页签和活动页面必须进入同一递归焦点树。
- 回调允许删除控件、切页、修改可见性和打开更高作用域，因此焦点切换必须与 mutation transaction、稳定身份和重入保护一起实现。
## 模块边界
### 已实现
- `FocusTargetId { ControlHandle owner, uint32_t subNode }`；阶段 2 现有节点全部 `subNode == 0`。
- 每 Window 一个 `FocusManager`，公开程序化申请、清焦点、查询 active、Tab stop 快照和 FocusScope 机制。
- `Control` 瞬时焦点快照协议：逻辑父级、policy、effective visible、动态 enabled、tabStop 和 tabIndex。
- Window、Canvas、Table、TabControl 的递归解析、收集和焦点状态提交。
- Button/TextBox 默认支持 Programmatic、Pointer、Tab；PointerDown 申请焦点并绘制焦点框。
- Table 复用真实 prev/next Button 句柄，按当前页和总页数动态过滤首尾分页资格。
- TabControl 复用真实页签 Button，非活动页面通过 effective visibility 退出焦点树。
- pending removal 在入队时立即使焦点子树失效；批量 clear 先批量失效再寻找后备。
- FocusScope push/pop、外层焦点恢复和回调中 push 的稳定恢复身份。
### 明确未实现
- Tab/Shift+Tab 键盘遍历、KeyboardRouter 和祖先冒泡。
- `EX_KEY` 业务换轨；阶段 1 的旧 `Control::handleEvent(EX_KEY)` 兼容旁路保持不变。
- Button 的 Enter/Space 键盘语义、Table 键盘翻页、TabControl roving-tab-stop 与方向键切换。
- 真实 Dialog 打开/关闭与 FocusScope 的绑定；阶段 2 只实现并测试作用域机制。
- TextBox UTF-16 编辑内核、caret、选区、剪贴板和 IME anchor。
- 窗口激活态对键盘路由的门控；当前只保留逻辑焦点，待阶段 3 使用阶段 1 的 WindowActivationEvent。
## 关键设计
### 身份与快照
- 当前 `ControlHandle` 为进程内单调递增且不复用的 `uint64_t`，不是 slot/generation 句柄。
- FocusManager 长期只保存 `FocusTargetId`、FocusScope 条目和待失效根句柄，不保存裸指针。
- `Window::findControl()` 只查直接子级，焦点系统使用独立递归协议。
- 快照只在当前调用中有效；每次用户回调之后重新解析并重拉 visible/enabled/focusable/tabStop。
### 重入事务
- 普通 `requestFocus()` 立即在 mutation transaction 内执行。
- 焦点回调中的请求进入单槽 pending，后一次覆盖前一次；回合结束只验证最终请求。
- pending 最终请求失效时丢弃，不恢复被覆盖请求。
- active 焦点失效独立执行“下一个 Tab stop → 上一个 → initialFocus → 无焦点”回退。
- 单次外层切换最多 64 回合；超限返回 `FocusError::ReentrancyLimit`，清空 pending，保留最后一个仍有效的已提交焦点。
- FocusLost 回调中 push scope 时，以正在丢失的旧目标作为恢复点；FocusGained 回调中以新目标作为恢复点。
### mutation 与复合控件
- remove/clear 一经入队，FocusManager 立即把对应子树视为无效，即使对象尚未物理释放。
- `clearControls()` 先收集并批量标记所有现有根，避免回退到同批待删兄弟。
- Canvas 可见性改变在整棵子树状态更新后通知 FocusManager。
- Table 分页 Button 在首次 draw 后创建，真实 UI fixture 验证第一页只有 next 进入 Tab stop。
- TabControl 页签 Button 始终使用真实句柄；只有活动页面的后代进入焦点树。
## 实现文件
- `include/StellarX/FocusManager.h`
- `src/StellarX/FocusManager.cpp`
- `include/StellarX/CoreTypes.h`
- `include/StellarX/Control.h` / `src/StellarX/Control.cpp`
- `include/StellarX/Window.h` / `src/StellarX/Window.cpp`
- `include/StellarX/Canvas.h` / `src/StellarX/Canvas.cpp`
- `Button`、`TextBox`、`Table`、`TabControl`、`Dialog` 对应实现文件
- `tests/StellarXTests.cpp`
- `tests/UiFixture.cpp`
- `scripts/run-ui-tests.ps1`
## 测试与验证
### 逻辑测试
- 嵌套 Canvas 递归解析与稳定目标身份。
- Button/TextBox PointerDown 焦点切换。
- FocusLost 删除/禁用新目标后的完整快照复验。
- FocusGained 删除自身后的 active 回退。
- 单槽 latest-wins 不复活旧请求。
- FocusGained 与 FocusLost 回调中 push scope，pop 后恢复真实外层目标。
- 64 轮 A/B 重入循环返回 `ReentrancyLimit`。
- active removal 下一个 Tab stop 回退和 clear 批量失效。
- TabControl 真实页签句柄、`subNode == 0` 和非活动页面过滤。
### 自动结果
- Debug x64：40/40。
- x64 ASan：40/40，无 sanitizer 报错。
- Release x64：40/40。
- Debug Win32：40/40。
- KEY1–KEY6：全部编译/链接成功。
- 最终源码的独立 `focus` UI 连续 3 轮通过，包含 Button/TextBox 焦点框像素、Table 分页资格、TabControl 活动页过滤和 subNode 检查。
- 初次完整 UI 两次复跑分别在既有 Tooltip 像素等待和 geometry 点击结果等待处超时，因此追加阶段 1 基线 `81341fa` 与阶段 2 工作树的受控 A/B，而不以场景执行顺序直接排除焦点影响。
- 受控 A/B 共 62/62 个结构化样本通过：geometry、tooltip 两端各累计 8/8，共有七场景两端各 3/3；当前阶段 2 正式完整 UI 八场景再执行三轮，共 24/24 通过，未发现阶段 2 相关失败或耗时劣化。
- 裁决为排除阶段 2 稳定引入的隐性回归；此前超时定性为间歇性桌面 fixture / 输入时序波动，关闭阶段门槛不等于证明未来永不发生残余偶发波动。
- A/B 运行器首次把成功进程的 `ExitCode=0` 误读为空值，已修正并重新构建、重跑；原误报保留，并在 `TestResults/Stage2RegressionAB/20261008-120909-362/manifest.json` 中登记。
## 兼容性与风险
- 新增 `Control` 虚接口会改变 vtable；二进制派生控件必须重新编译。StellarX 以源码方式使用时，正常全量重编译即可。
- 没有删除既有公开接口，没有停止 `EX_KEY` 旧入口，阶段 2 不构成键盘迁移点。
- Table 内部按钮仍只在首次 draw 后存在；在 draw 前收集焦点树不会返回它们，这是当前生命周期事实。
- Button/TextBox 焦点框是阶段 2 的最小视觉反馈，最终主题化样式可在后续阶段增强。
- 真实 Dialog scope、窗口激活门控和键盘导航仍未接入，不能仅凭阶段 2 宣称完整键盘可访问性。
## 落地信息
- 关联功能变更 ID：无
- 关联 BUG / Fix：无
- Commit：待提交
- PR：无
- 发布版本：未发布
- 相关文档：[`Module-20261001-0001-通用输入焦点与键盘路由系统设计.md`](./Module-20261001-0001-通用输入焦点与键盘路由系统设计.md)