docs: 完善画布注释并复核核心数据边界 #11

2026-11-12T03:30:01Z

codex-bot commented

2026-11-12 03:30:01 +00:00

浏览器场景、旧画布测试和样式/配置缺少足够的流程说明，容易把内存替身或静态断言误读成真实后端、原生布局或完整产品验收。本 PR 补充中文模块、辅助函数、场景和逻辑块说明，标明状态归属、竞态、清理与证据边界。

改动范围：

Runtime 账本/调度复核：ledger 压缩前提、冻结/结果/退休与持久水位；scheduler 端口合同、pipeline 并发、本地 claims/hold、持久屏障、重试/启动/停止；structures 的 FIFO/heap 引用与 comparator 边界。
查询/类型/入口复核：queries 的变更提示、空间预算、引用可解释性、coverage 与三态读取；types 的存在性/历史/能力/几何合同；index 的实际重导出边界。
手势会话复核：gestures 的 manager/view 归属、选择/模式/视口与准入分层、预览/提交/取消/卸载；gesture-placement 的 owner→view 签名、缓存和类型只读边界。
能力/几何复核：features 的基础 data/路径检查、默认缩放/旋转及连接几何；geometry 的空间前提与 Bezier 控制柄；curve-hit 的 DFS、误差区间与 confirmed/possible/budget 含义。
深复制/解散复核：copy-paths 通配符与 many、复制入边/出边范围及资源/任务字段处理、checkpoint 绑定/预算/输出重建边界、解散的成员提升/全局声明引用改写与 policy 命令。
创建/结构/坐标复核：creation-draft 追加层折叠与物化、creation-size-plan 按宽高继承和历史修正、structure 删除范围与连线 owner 修复、coordinates 的校验/早返回边界。
editor/history/units 复核：同步重入与副作用约定、文档身份查询、handler 分派、no-op/发布与两栈移动、历史 DTO/缓存边界、单位换算等效早返回。
core 数据边界复核：修订 data-containers、json-data、element-data、values、document、registry 六模块的来源证明、浅冻结、schema/墓碑校验、field 回放范围和迁移共享引用说明。
浏览器存储场景：共享字节回收、引用清单、导入恢复与加载屏障等段落。
页面集成场景：装配与代理替身、原生手势、恢复、AI、资源/导入、保留渲染和失效回调等流程。
根目录 13 个单测及六个场景/执行入口：旧快照历史/同步、目录/workspace、资源与图标、HTTP smoke、JSDOM、成员迁移、上传和反馈。
全部七个 CSS 文件：布局、交互命中、状态层、响应式、动画与同名选择器的后置覆盖。
README、环境模板和忽略规则：解释包/TS/组件生成器配置、headless 输出入口、严格 JSON 的字段与生成链路；在图标生成器和服务单测使用处增加数据旁注。

验证：

各批次修改的 TS/JS AST 对比一致；六个根场景入口的 node --check 通过。
七个 CSS 文件的 PostCSS 解析树（排除注释）一致，规则、声明和值及顺序未改。
根目录单测 84/84、服务适配器单测 14/14 通过；核心/元素校验/JSON 隔离/条件回放相关单测 37/37 通过；editor/历史增量/创建尺寸/解散相关单测 61/61 通过；创建草稿/尺寸/核心/解散相关单测 49/49 通过；复制/检查点/工作预算/解散相关单测 24/24 通过；核心/模型命中/复制相关单测 40/40 通过；核心/手势坐标/会话生命周期相关单测 43/43 通过；查询/命中/元素订阅/核心相关单测 47/47 通过；账本/调度/抵消/持久屏障相关单测 34/34 通过。
106 个跟踪 JSON 均可解析且保持原字节；环境模板的赋值与 gitignore 的有效规则不变。
git diff --check 通过。未为这些注释批次重跑浏览器场景、Next 服务、构建或后端集成。

只修改注释与阅读说明，没有实现行为变更。项目注释任务已完成各目录首轮说明，第五阶段已完成core 全部二十六个文件及 runtime 账本/调度/容器三个文件的逐函数/类型与逻辑块复核，其余模块准确性与细粒度覆盖审查仍在进行；本 PR 不宣称整个任务完成。目标 main，等待用户手动合并。

浏览器场景、旧画布测试和样式/配置缺少足够的流程说明，容易把内存替身或静态断言误读成真实后端、原生布局或完整产品验收。本 PR 补充中文模块、辅助函数、场景和逻辑块说明，标明状态归属、竞态、清理与证据边界。改动范围： - Runtime 账本/调度复核：ledger 压缩前提、冻结/结果/退休与持久水位；scheduler 端口合同、pipeline 并发、本地 claims/hold、持久屏障、重试/启动/停止；structures 的 FIFO/heap 引用与 comparator 边界。 - 查询/类型/入口复核：queries 的变更提示、空间预算、引用可解释性、coverage 与三态读取；types 的存在性/历史/能力/几何合同；index 的实际重导出边界。 - 手势会话复核：gestures 的 manager/view 归属、选择/模式/视口与准入分层、预览/提交/取消/卸载；gesture-placement 的 owner→view 签名、缓存和类型只读边界。 - 能力/几何复核：features 的基础 data/路径检查、默认缩放/旋转及连接几何；geometry 的空间前提与 Bezier 控制柄；curve-hit 的 DFS、误差区间与 confirmed/possible/budget 含义。 - 深复制/解散复核：copy-paths 通配符与 many、复制入边/出边范围及资源/任务字段处理、checkpoint 绑定/预算/输出重建边界、解散的成员提升/全局声明引用改写与 policy 命令。 - 创建/结构/坐标复核：creation-draft 追加层折叠与物化、creation-size-plan 按宽高继承和历史修正、structure 删除范围与连线 owner 修复、coordinates 的校验/早返回边界。 - editor/history/units 复核：同步重入与副作用约定、文档身份查询、handler 分派、no-op/发布与两栈移动、历史 DTO/缓存边界、单位换算等效早返回。 - core 数据边界复核：修订 data-containers、json-data、element-data、values、document、registry 六模块的来源证明、浅冻结、schema/墓碑校验、field 回放范围和迁移共享引用说明。 - 浏览器存储场景：共享字节回收、引用清单、导入恢复与加载屏障等段落。 - 页面集成场景：装配与代理替身、原生手势、恢复、AI、资源/导入、保留渲染和失效回调等流程。 - 根目录 13 个单测及六个场景/执行入口：旧快照历史/同步、目录/workspace、资源与图标、HTTP smoke、JSDOM、成员迁移、上传和反馈。 - 全部七个 CSS 文件：布局、交互命中、状态层、响应式、动画与同名选择器的后置覆盖。 - README、环境模板和忽略规则：解释包/TS/组件生成器配置、headless 输出入口、严格 JSON 的字段与生成链路；在图标生成器和服务单测使用处增加数据旁注。验证： - 各批次修改的 TS/JS AST 对比一致；六个根场景入口的 node --check 通过。 - 七个 CSS 文件的 PostCSS 解析树（排除注释）一致，规则、声明和值及顺序未改。 - 根目录单测 84/84、服务适配器单测 14/14 通过；核心/元素校验/JSON 隔离/条件回放相关单测 37/37 通过；editor/历史增量/创建尺寸/解散相关单测 61/61 通过；创建草稿/尺寸/核心/解散相关单测 49/49 通过；复制/检查点/工作预算/解散相关单测 24/24 通过；核心/模型命中/复制相关单测 40/40 通过；核心/手势坐标/会话生命周期相关单测 43/43 通过；查询/命中/元素订阅/核心相关单测 47/47 通过；账本/调度/抵消/持久屏障相关单测 34/34 通过。 - 106 个跟踪 JSON 均可解析且保持原字节；环境模板的赋值与 gitignore 的有效规则不变。 - git diff --check 通过。未为这些注释批次重跑浏览器场景、Next 服务、构建或后端集成。只修改注释与阅读说明，没有实现行为变更。项目注释任务已完成各目录首轮说明，第五阶段已完成core 全部二十六个文件及 runtime 账本/调度/容器三个文件的逐函数/类型与逻辑块复核，其余模块准确性与细粒度覆盖审查仍在进行；本 PR 不宣称整个任务完成。目标 main，等待用户手动合并。

codex-bot added 1 commit 2026-11-12 03:30:03 +00:00

docs(tests): explain storage collection import recovery and loading barriers bd728d2d94

codex-bot added 1 commit 2026-11-12 03:36:49 +00:00

docs(tests): explain renderer fixture setup proxy routes and native gestures 50675ffed3

codex-bot changed title from ~~docs(tests): 说明浏览器存储回收、导入与加载恢复~~ to docs(tests): 说明浏览器存储与页面集成场景

2026-11-12 03:37:09 +00:00

codex-bot added 1 commit 2026-11-12 03:43:41 +00:00

docs(tests): explain renderer recovery AI import and retained ownership flows 6ad003eb37

codex-bot added 1 commit 2026-11-12 03:51:21 +00:00

docs(tests): explain legacy canvas and workspace unit coverage 412e31e898

codex-bot added 1 commit 2026-11-12 03:57:09 +00:00

docs(tests): explain legacy canvas scenario setup and recovery flows 2a0b6bb9d9