Checkpoint web parity through Chromium input tasks

docs/TASK_BREAKDOWN.md

@@ -0,0 +1,208 @@
+# 项目任务分解与最小上下文指南
+
+更新时间：2026-08-19（America/New_York）
+
+本文件是“如何拆任务、如何领取任务、如何交接”的规划索引，不是实现状态事实源。当前状态仍以
+`docs/EXECUTION_QUEUE.md`、当前任务的 `manifest.json`、对应 `docs/status/<task>.md` 和可复验命令为准。
+本文件的目标是让一次任务只加载必要上下文，不要求阅读整份路线图或历史接续日志。
+
+## 1. 30 秒入口
+
+每轮只按下面顺序读取：
+
+1. `docs/EXECUTION_QUEUE.md`：确认唯一当前 `nextTask`、Chromium-only 规则和专项命令。
+2. `docs/tasks/<task>.md`：读取目标、输入、范围、验收和回滚。
+3. `tests/golden/<parent>/manifest.json`：确认 parent hash、依赖、运行时和下一任务。
+4. `docs/status/<parent>.md`：只读取上一项的证据摘要和已知风险。
+
+只有遇到以下问题才继续读取：
+
+| 问题 | 追加读取 |
+| --- | --- |
+| 不确定产品是否承诺 | `WEB_BLENDER_MODELER_V1_SCOPE.md` |
+| 不确定实现事实或已有命令 | `PROJECT_STATUS_AND_NEXT_WORK.md` 的相关小节 |
+| 不确定长期依赖或全域差距 | `BLENDER_5_2_FULL_WEB_PARITY_EXECUTION_PLAN.md` 的对应 M/F 小节 |
+| 不确定 family 状态 | `status/parity-ledger.json` 和 `release-evidence.json` |
+| 不确定协议字段 | 任务卡列出的 `web/protocol/*` 文件，不扫描整个 `web/` |
+
+不要把 `README.md`、`后续工作.txt`、完整路线图和全部 status 日志作为每轮默认上下文。
+根目录路线图与历史接续记录仅用于背景；它们不能覆盖机器 manifest 的指针。
+
+## 2. 文档职责和冲突处理
+
+| 层级 | 唯一职责 | 可以回答 | 不能回答 |
+| --- | --- | --- | --- |
+| 产品契约 | `WEB_BLENDER_MODELER_V1_SCOPE.md` | V1 承诺、非目标、发布门 | 当前领取哪一项 |
+| 短周期入口 | `EXECUTION_QUEUE.md` | 当前任务、parent、专项命令 | 实现是否真的通过 |
+| 任务卡 | `tasks/<task>.md` | 单项范围、最小输入、验收、回滚 | 历史实现日志 |
+| 机器事实 | `tests/golden/*/manifest.json`、`status/*.json` | hash、依赖、运行时、状态轴 | 人类意图 |
+| 完成证据 | `status/<task>.md` | 实际命令、退出码、报告、风险 | 下一任务的推导顺序 |
+| 长期规划 | `BLENDER_5_2_FULL_WEB_PARITY_EXECUTION_PLAN.md` | M12-M23/F 域规划 | 当前队列指针 |
+| 覆盖参考 | `BLENDER_5_2_FULL_PARITY_WBS.md` | Blender 全域检查表 | 独立完成证明 |
+
+冲突时使用以下优先级：
+
+```text
+可复验命令输出 > manifest/evidence > 当前任务卡 > 执行队列描述 > 长期规划/历史日志
+```
+
+如果 manifest、status 和命令互相矛盾，先标记 `blocked`，不要修改 checkbox 或手工推进
+`nextTask`。
+
+## 3. 原子任务规则
+
+一个任务只能有一个主要行为变化，或一个独立证据变化。把“实现、浏览器接线、发布证据”混在一项
+会导致上下文过大，也会让测试文件存在被误判成生产能力完成。
+
+每项任务都要能回答以下六个问题：
+
+| 字段 | 最小内容 |
+| --- | --- |
+| 输入 | parent manifest、一个最小 fixture、生产入口 |
+| 行为 | 一个可观察的状态/数据/错误变化 |
+| 边界 | 至少一个非法、取消、超限或重复事件 |
+| 产物 | 一个协议/实现改动 + 一个 focused test/checker |
+| 验收 | 一条首选命令，必要时追加 typecheck/build |
+| 交接 | report、manifest、status、下一任务、回滚点 |
+
+### 3.1 建议的子任务门
+
+复杂能力按以下门拆开，每个门都可独立复验：
+
+| 门 | 交付内容 | 常见文件 |
+| --- | --- | --- |
+| C 契约 | schema、稳定 ID、预算、错误码、revision 规则 | `web/protocol/*` |
+| P 生产路径 | Main/Worker/App/viewport 真正消费契约 | `web/app/src/*`、`web/engine/*` |
+| N 负例 | 非法、重复、取消、迟到、超限不改已提交状态 | `web/tests/unit/*` |
+| B 浏览器 | Chromium 真实用户路径和可见状态 | `tools/web/check-*.mjs`、`web/tests/e2e/*` |
+| R 资源 | dispose、取消、Worker 重启、OPFS/ GPU 预算归零 | Worker、storage、viewport |
+| E 证据 | 报告、SHA-256、manifest、status、回滚 | `tests/golden/*`、`docs/status/*` |
+
+任务卡可以把 C/P/N/B/R/E 写成子任务，但只有所有适用门通过后，主任务才可变为 `done`。
+
+## 4. 项目阶段分解
+
+下面是导航级分解；具体领取仍由短周期队列决定。
+
+| 阶段 | 主题 | 交付边界 | 当前使用方式 |
+| --- | --- | --- | --- |
+| M0 | 范围与状态模型 | V1 契约、双轴 ledger、P0 用户闭环 | 已完成，持续回归 |
+| M1 | 工作区收口 | 静态门、VDB 基线、P0 一致性 | 已完成，持续回归 |
+| M2 | 大几何 | 10M geometry、LOD、取消、释放、恢复 | 已完成，持续回归 |
+| M3 | 长媒体 | 索引、seek、取消、缓存、重开 | 已完成，持续回归 |
+| M4 | OOM/fault | WASM、OPFS、GPU、VDB 确定性恢复 | 已完成，持续回归 |
+| M5-M6 | V1/可部署 RC | 离线包、SBOM、CI、部署、升级、回滚 | 已完成，持续回归 |
+| M7 | 核心体验 | action/dirty/save/restart/recent projects/input 基础 | 已完成，持续回归 |
+| M8 | VDB 自动分页 | range/OPFS/LRU/双视口/device loss | 已完成，持续回归 |
+| M9 | 非 Mesh/GP/Paint | 有界 reader/writer、Main、保存重开、故障 | 已完成的 V1 slice；全域仍可能 BLOCKED |
+| M10 | GN/Shader/NLA/Simulation | allowlist、compile/cache、错误与恢复 | 已完成的 V1 slice；完整 evaluator 仍排除 |
+| M11 | Render/Compositor/Media | bounded local、server route、codec/revision/audio | 已完成的 V1 slice |
+| M12 | Asset/IO/Editors | 资产库、GLB/OBJ/STL/PLY、编辑器上下文 | 按 manifest 继续领取，不能按总百分比判断 |
+| M13 | Scripting/Security | metadata-only、default-deny、sandbox、server isolation、CSP | 每个安全门独立验收；execution 默认禁用 |
+| M14 | Chromium 设备与输入 | capability、预算、DPR、pointer、IME、keymap、modal、可访问性 | 当前短周期在 `M14-04F` |
+| M15 | 全域审计 | Blender 5.2 inventory、operator/node/editor/format gap | 未开始；不阻断已限定 V1 |
+
+状态轴必须分开：V1 `releaseStatus=READY` 不等于 Blender 全域 `parityStatus=COMPLETE`。
+
+## 5. 当前 M14-04F 细分
+
+### 5.1 当前已知上下文
+
+- parent：`M14-04E`，状态页已记录 keymap fixture 的成功证据。
+- 当前任务：`M14-04F`，任务卡为 `docs/tasks/M14-04F.md`。
+- 协议：`web/protocol/input-modal.ts`。
+- 单测：`web/tests/unit/input-modal.test.mjs`。
+- Chromium 检查器：`tools/web/check-chromium-input-modal.mjs`。
+- 报告/manifest：`tests/golden/M14-04F/`。
+- focused command：`npm --prefix web run test:chromium-input-modal`。
+
+当前命令已经能证明协议单测通过，并能在 Chromium 页面派发 touch/pen 事件；完成主任务前还要
+确认事件确实进入生产输入状态和 Main transaction，而不是只在 checker 内构造事件并写入固定
+保证值。
+
+### 5.2 子任务清单
+
+| 子任务 | 唯一目标 | 最小改动面 | 必须证明 |
+| --- | --- | --- | --- |
+| F-C | 冻结 `InputModalState` schema 和状态转移 | `web/protocol/input-modal.ts` | pointer ID 非法时稳定拒绝；状态转移确定 |
+| F-T | 触控 modal 取消 | protocol + 生产 pointer cancel 入口 | cancel 后 `kind=NONE`、无 Main commit、活动 pointer 清零 |
+| F-2T | 双指导航 session 去重 | protocol + navigation dispatch | 从 1 到 2 个 pointer 只增加一次 `navigationRevision`；重复 down 不增加 |
+| F-P | 笔 stroke 单次提交 | protocol + pen pointerup/cancel 入口 | 第一个合法 up 最多一个 Main commit；late up/cancel 无二次提交 |
+| F-W | 主线程/Offscreen 生产接线 | App、viewport、Worker 输入边界 | 两条生产视口消费同一状态规则；cancel/late result 不污染 revision |
+| F-B | Chromium 真实断言 | checker/e2e + 最小 fixture | 读取 DOM/诊断/Main revision 的真实结果，而不是只检查派发数量 |
+| F-E | 证据和交接 | report、manifest、status | 命令退出 0、artifact hash 非空、风险/回滚清楚 |
+
+### 5.3 完成门
+
+主任务只有同时满足以下条件才可标记 `done`：
+
+1. `F-C`、`F-T`、`F-2T`、`F-P` 的 Node 单测通过。
+2. `F-W` 在生产 App/viewport 中有实际 import 和事件消费路径。
+3. `F-B` 对至少 touch cancel、双指 session、pen late-up/cancel 做真实正负例断言。
+4. 取消或重复事件不产生迟到 Main commit，且 revision/commit counter 可观测。
+5. focused Chromium 命令、必要的 `typecheck`/`build` 和 `git diff --check` 通过。
+6. `docs/status/M14-04F.md`、`tests/golden/M14-04F/manifest.json` 和代码 hash 一致。
+
+如果只有协议和测试通过，状态应保持 `in_progress`，不得提前领取 M14-04G。
+
+## 6. M14 后续任务草案
+
+这些是领取前的拆分草案；正式任务仍须由 parent manifest 生成任务卡。
+
+### M14-04G：响应式布局无重叠/溢出
+
+- 输入：M14-04F manifest、App shell、viewport CSS、四档 Chromium viewport。
+- 正例：`1440x900`、`1280x720`、`834x1112`、`390x844`。
+- 检查：`scrollWidth <= clientWidth`；topbar/sidebar/viewport/timeline/status 不互相覆盖；文字不被裁切；触控目标仍可操作。
+- 负例：窄视口、长项目名、错误提示、打开进度、面板展开、DPR 2。
+- 产物：布局 checker、4 档报告、截图或 bounding-box 摘要、manifest、status。
+- 不做：Firefox/WebKit；完整响应式重设计；新增 Blender 功能。
+
+### M14-04H：键盘无障碍与焦点恢复
+
+- 输入：M14-04G manifest、现有菜单/操作搜索/文件对话入口。
+- 正例：Tab 顺序、Escape 关闭 modal、Enter 提交、焦点回到触发器、按钮有 name/role。
+- 负例：modal 打开时快捷键穿透、焦点丢失、隐藏元素进入 tab 顺序、IME 期间提交 operator。
+- 产物：Chromium keyboard-only checker、焦点轨迹报告、必要的 ARIA/DOM 修复、manifest/status。
+- 不做：screen reader 的浏览器兼容性声明；Firefox/WebKit 证据。
+
+### M15-01A 至 M15-01F：全域清单审计
+
+1. 从 Blender 5.2 RNA 生成 data-block inventory。
+2. 生成 operator、poll context 和 property inventory。
+3. 生成 modifier、constraint、shader/GN/compositor node inventory。
+4. 生成 sequencer、physics、import/export inventory。
+5. 生成 editor/space/region/workspace/keymap inventory。
+6. 将 inventory ID 映射到 `parity-ledger.json`，拒绝未分类新增项并固定总 hash。
+
+每一项都只产出一个稳定 inventory 或映射证据；不要在 M15 直接实现功能。
+
+## 7. 交接格式
+
+完成任务后，status 页只保留可审计摘要：
+
+```text
+status: done | blocked
+task: <ID>
+updated: <timezone>
+scope: 一句话行为变化
+evidence: 命令、退出码、关键结果
+artifacts: report/manifest/代码 SHA-256
+nextTask: 仅复制 manifest.nextTask
+knownRisk: 仍未覆盖的边界
+rollback: 删除本任务产物并恢复 parent 队列尾
+```
+
+不要把完整终端日志、实现过程或下一阶段设想复制进 status 页；长日志留在构件目录，任务卡只留
+最小输入和验收入口。
+
+## 8. 领取前检查表
+
+- [ ] 当前 task 与 parent manifest 的 `nextTask` 一致。
+- [ ] parent status 为 `done`，或明确写出允许并行的 `enablingTask`。
+- [ ] 任务卡只有一个主要行为。
+- [ ] focused command 已存在，或任务明确包含创建该命令。
+- [ ] 生产入口和测试入口分别列出，没有只写“相关代码”。
+- [ ] 至少一个负例、取消或重复事件已列出。
+- [ ] 任务状态不会误改 `parityStatus`/`releaseStatus` 另一条轴。
+- [ ] 完成后能生成 report、manifest、status 和可回滚路径。